[babeltrace.git] / include / babeltrace2 / graph / port.h

/*
 * SPDX-License-Identifier: MIT
 *
 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
 */

#ifndef BABELTRACE2_GRAPH_PORT_H
#define BABELTRACE2_GRAPH_PORT_H

/* IWYU pragma: private, include <babeltrace2/babeltrace.h> */

#ifndef __BT_IN_BABELTRACE_H
# error "Please include <babeltrace2/babeltrace.h> instead."
#endif

#include <stdint.h>

#include <babeltrace2/types.h>

#ifdef __cplusplus
extern "C" {
#endif

/*!
@defgroup api-port Ports
@ingroup api-comp

@brief
    \bt_c_comp input and output ports.

A <strong><em>port</em></strong> is a point of \bt_conn between
\bt_p_comp:

@image html component-zoom.png

A port is a \ref api-fund-shared-object "shared object": get a new
reference with bt_port_get_ref() and put an existing reference with
bt_port_put_ref().

The common C&nbsp;type of a port is #bt_port.

There are two types of ports:

<dl>
  <dt>\anchor api-port-in Input port</dt>
  <dd>
    Input connection point from which \bt_p_msg are received.

    Filter and sink components have input ports.

    An input port's specific type is #bt_port_input and its type
    enumerator is #BT_PORT_TYPE_INPUT.

    \ref api-fund-c-typing "Upcast" the #bt_port_input type to the
    #bt_port type with bt_port_input_as_port_const().

    Get a new input port reference with bt_port_input_get_ref() and put
    an existing one with bt_port_input_put_ref().
  </dd>

  <dt>\anchor api-port-out Output port</dt>
  <dd>
    Output connection point to which messages are sent.

    Source and filter components have output ports.

    An output port's specific type is #bt_port_output and its type
    enumerator is #BT_PORT_TYPE_OUTPUT.

    \ref api-fund-c-typing "Upcast" the #bt_port_output type to the
    #bt_port type with bt_port_output_as_port_const().

    Get a new output port reference with bt_port_output_get_ref() and
    put an existing one with bt_port_output_put_ref().
  </dd>
</dl>

Get a port's type enumerator with bt_port_get_type(). You can also use
the bt_port_is_input() and bt_port_is_output() helper functions.

A \bt_comp can add a port with:

- bt_self_component_source_add_output_port()
- bt_self_component_filter_add_input_port()
- bt_self_component_filter_add_output_port()
- bt_self_component_sink_add_input_port()

Borrow a port's \bt_conn, if any, with
bt_port_borrow_connection_const().

Borrow the component to which a port belongs with
bt_port_borrow_component_const().

<h1>Properties</h1>

A port has the following common properties:

<dl>
  <dt>
    \anchor api-port-prop-name
    Name
  </dt>
  <dd>
    Name of the port.

    For a given \bt_comp:

    - Each input port has a unique name.
    - Each output port has a unique name.

    A port's name is set when the component adds it; you cannot change
    it afterwards.

    Get a port's name with bt_port_get_name().
  </dd>

  <dt>
    \anchor api-port-prop-is-connected
    Is connected?
  </dt>
  <dd>
    Whether or not the port is currently connected to another port.

    Get whether or not a port is connected with bt_port_is_connected().

    When a port is unconnected, bt_port_borrow_connection_const()
    returns \c NULL.
  </dd>
</dl>
*/

/*! @{ */

/*!
@name Types
@{

@typedef struct bt_port bt_port;

@brief
    Port.

@typedef struct bt_port_input bt_port_input;

@brief
    \bt_c_iport.

@typedef struct bt_port_output bt_port_output;

@brief
    \bt_c_oport.

@}
*/

/*!
@name Type query
@{
*/

/*!
@brief
    Port type enumerators.
*/
typedef enum bt_port_type {
	/*!
	@brief
	    \bt_c_iport.
	*/
	BT_PORT_TYPE_INPUT	= 1 << 0,

	/*!
	@brief
	    \bt_c_oport.
	*/
	BT_PORT_TYPE_OUTPUT	= 1 << 1,
} bt_port_type;

/*!
@brief
    Returns the type enumerator of the port \bt_p{port}.

@param[in] port
    Port of which to get the type enumerator

@returns
    Type enumerator of \bt_p{port}.

@bt_pre_not_null{port}

@sa bt_port_is_input() &mdash;
    Returns whether or not a port is an \bt_iport.
@sa bt_port_is_output() &mdash;
    Returns whether or not a port is an \bt_oport.
*/
extern bt_port_type bt_port_get_type(const bt_port *port) __BT_NOEXCEPT;

/*!
@brief
    Returns whether or not the port \bt_p{port} is an \bt_iport.

@param[in] port
    Port to check.

@returns
    #BT_TRUE if \bt_p{port} is an input port.

@bt_pre_not_null{port}

@sa bt_port_get_type() &mdash;
    Returns the type enumerator of a port.
*/
static inline
bt_bool bt_port_is_input(const bt_port *port) __BT_NOEXCEPT
{
	return bt_port_get_type(port) == BT_PORT_TYPE_INPUT;
}

/*!
@brief
    Returns whether or not the port \bt_p{port} is an \bt_oport.

@param[in] port
    Port to check.

@returns
    #BT_TRUE if \bt_p{port} is an output port.

@bt_pre_not_null{port}

@sa bt_port_get_type() &mdash;
    Returns the type enumerator of a port.
*/
static inline
bt_bool bt_port_is_output(const bt_port *port) __BT_NOEXCEPT
{
	return bt_port_get_type(port) == BT_PORT_TYPE_OUTPUT;
}

/*! @} */

/*!
@name Connection access
@{
*/

/*!
@brief
    Borrows the \bt_conn of the port \bt_p{port}.

This function returns \c NULL if \bt_p{port} is unconnected
(bt_port_is_connected() returns #BT_FALSE).

@param[in] port
    Port of which to borrow the connection.

@returns
    \em Borrowed reference of the connection of \bt_p{port}.

@bt_pre_not_null{port}
*/
extern const bt_connection *bt_port_borrow_connection_const(
		const bt_port *port) __BT_NOEXCEPT;

/*! @} */

/*!
@name Component access
@{
*/

/*!
@brief
    Borrows the \bt_comp to which the port \bt_p{port} belongs.

@param[in] port
    Port of which to borrow the component which owns it.

@returns
    \em Borrowed reference of the component which owns \bt_p{port}.

@bt_pre_not_null{port}
*/
extern const bt_component *bt_port_borrow_component_const(
		const bt_port *port) __BT_NOEXCEPT;

/*! @} */

/*!
@name Properties
@{
*/

/*!
@brief
    Returns the name of the port \bt_p{port}.

See the \ref api-port-prop-name "name" property.

@param[in] port
    Port of which to get the name.

@returns
    @parblock
    Name of \bt_p{port}, or \c NULL if none.

    The returned pointer remains valid as long as \bt_p{port} exists.
    @endparblock

@bt_pre_not_null{port}
*/
extern const char *bt_port_get_name(const bt_port *port) __BT_NOEXCEPT;

/*!
@brief
    Returns whether or not the port \bt_p{port} is connected.

See the \ref api-port-prop-is-connected "is connected?" property.

@param[in] port
    Port of which to get whether or not it's connected.

@returns
    #BT_TRUE if \bt_p{port} is connected.

@bt_pre_not_null{port}
*/
extern bt_bool bt_port_is_connected(const bt_port *port) __BT_NOEXCEPT;

/*! @} */

/*!
@name Reference count (common)
@{
*/

/*!
@brief
    Increments the \ref api-fund-shared-object "reference count" of
    the port \bt_p{port}.

@param[in] port
    @parblock
    Port of which to increment the reference count.

    Can be \c NULL.
    @endparblock

@sa bt_port_put_ref() &mdash;
    Decrements the reference count of a port.
*/
extern void bt_port_get_ref(const bt_port *port) __BT_NOEXCEPT;

/*!
@brief
    Decrements the \ref api-fund-shared-object "reference count" of
    the port \bt_p{port}.

@param[in] port
    @parblock
    Port of which to decrement the reference count.

    Can be \c NULL.
    @endparblock

@sa bt_port_get_ref() &mdash;
    Increments the reference count of a port.
*/
extern void bt_port_put_ref(const bt_port *port) __BT_NOEXCEPT;

/*!
@brief
    Decrements the reference count of the port
    \bt_p{_port}, and then sets \bt_p{_port} to \c NULL.

@param _port
    @parblock
    Port of which to decrement the reference count.

    Can contain \c NULL.
    @endparblock

@bt_pre_assign_expr{_port}
*/
#define BT_PORT_PUT_REF_AND_RESET(_port)	\
	do {					\
		bt_port_put_ref(_port);		\
		(_port) = NULL;			\
	} while (0)

/*!
@brief
    Decrements the reference count of the port \bt_p{_dst}, sets
    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.

This macro effectively moves a port reference from the
expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
existing \bt_p{_dst} reference.

@param _dst
    @parblock
    Destination expression.

    Can contain \c NULL.
    @endparblock
@param _src
    @parblock
    Source expression.

    Can contain \c NULL.
    @endparblock

@bt_pre_assign_expr{_dst}
@bt_pre_assign_expr{_src}
*/
#define BT_PORT_MOVE_REF(_dst, _src)	\
	do {				\
		bt_port_put_ref(_dst);	\
		(_dst) = (_src);	\
		(_src) = NULL;		\
	} while (0)

/*! @} */

/*!
@name Input port
@{
*/

/*!
@brief
    \ref api-fund-c-typing "Upcasts" the \bt_iport \bt_p{port} to the
    common #bt_port type.

@param[in] port
    @parblock
    Input port to upcast.

    Can be \c NULL.
    @endparblock

@returns
    \bt_p{port} as a common port.
*/
static inline
const bt_port *bt_port_input_as_port_const(
		const bt_port_input *port) __BT_NOEXCEPT
{
	return __BT_UPCAST_CONST(bt_port, port);
}

/*!
@brief
    Increments the \ref api-fund-shared-object "reference count" of
    the \bt_iport \bt_p{port}.

@param[in] port
    @parblock
    Input port of which to increment the reference count.

    Can be \c NULL.
    @endparblock

@sa bt_port_input_put_ref() &mdash;
    Decrements the reference count of an input port.
*/
extern void bt_port_input_get_ref(const bt_port_input *port) __BT_NOEXCEPT;

/*!
@brief
    Decrements the \ref api-fund-shared-object "reference count" of
    the \bt_iport \bt_p{port}.

@param[in] port
    @parblock
    Input port of which to decrement the reference count.

    Can be \c NULL.
    @endparblock

@sa bt_port_input_get_ref() &mdash;
    Increments the reference count of an input port.
*/
extern void bt_port_input_put_ref(const bt_port_input *port) __BT_NOEXCEPT;

/*!
@brief
    Decrements the reference count of the \bt_iport
    \bt_p{_port}, and then sets \bt_p{_port} to \c NULL.

@param _port
    @parblock
    Input port of which to decrement the reference count.

    Can contain \c NULL.
    @endparblock

@bt_pre_assign_expr{_port}
*/
#define BT_PORT_INPUT_PUT_REF_AND_RESET(_port)		\
	do {						\
		bt_port_input_put_ref(_port);		\
		(_port) = NULL;				\
	} while (0)

/*!
@brief
    Decrements the reference count of the \bt_iport \bt_p{_dst}, sets
    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.

This macro effectively moves an \bt_iport reference from the
expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
existing \bt_p{_dst} reference.

@param _dst
    @parblock
    Destination expression.

    Can contain \c NULL.
    @endparblock
@param _src
    @parblock
    Source expression.

    Can contain \c NULL.
    @endparblock

@bt_pre_assign_expr{_dst}
@bt_pre_assign_expr{_src}
*/
#define BT_PORT_INPUT_MOVE_REF(_dst, _src)	\
	do {					\
		bt_port_input_put_ref(_dst);	\
		(_dst) = (_src);		\
		(_src) = NULL;			\
	} while (0)

/*! @} */

/*!
@name Output port
@{
*/

/*!
@brief
    \ref api-fund-c-typing "Upcasts" the \bt_oport \bt_p{port} to the
    common #bt_port type.

@param[in] port
    @parblock
    Output port to upcast.

    Can be \c NULL.
    @endparblock

@returns
    \bt_p{port} as a common port.
*/
static inline
const bt_port *bt_port_output_as_port_const(
		const bt_port_output *port) __BT_NOEXCEPT
{
	return __BT_UPCAST_CONST(bt_port, port);
}

/*!
@brief
    Increments the \ref api-fund-shared-object "reference count" of
    the \bt_oport \bt_p{port}.

@param[in] port
    @parblock
    Output port of which to increment the reference count.

    Can be \c NULL.
    @endparblock

@sa bt_port_output_put_ref() &mdash;
    Decrements the reference count of a \bt_oport.
*/
extern void bt_port_output_get_ref(const bt_port_output *port) __BT_NOEXCEPT;

/*!
@brief
    Decrements the \ref api-fund-shared-object "reference count" of
    the \bt_oport \bt_p{port}.

@param[in] port
    @parblock
    Output port of which to decrement the reference count.

    Can be \c NULL.
    @endparblock

@sa bt_port_output_get_ref() &mdash;
    Increments the reference count of a \bt_oport.
*/
extern void bt_port_output_put_ref(const bt_port_output *port) __BT_NOEXCEPT;

/*!
@brief
    Decrements the reference count of the \bt_oport
    \bt_p{_port}, and then sets \bt_p{_port} to \c NULL.

@param _port
    @parblock
    Output port of which to decrement the reference count.

    Can contain \c NULL.
    @endparblock

@bt_pre_assign_expr{_port}
*/
#define BT_PORT_OUTPUT_PUT_REF_AND_RESET(_port)		\
	do {						\
		bt_port_output_put_ref(_port);		\
		(_port) = NULL;				\
	} while (0)

/*!
@brief
    Decrements the reference count of the \bt_oport \bt_p{_dst}, sets
    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.

This macro effectively moves an \bt_oport reference from the
expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
existing \bt_p{_dst} reference.

@param _dst
    @parblock
    Destination expression.

    Can contain \c NULL.
    @endparblock
@param _src
    @parblock
    Source expression.

    Can contain \c NULL.
    @endparblock

@bt_pre_assign_expr{_dst}
@bt_pre_assign_expr{_src}
*/
#define BT_PORT_OUTPUT_MOVE_REF(_dst, _src)	\
	do {					\
		bt_port_output_put_ref(_dst);	\
		(_dst) = (_src);		\
		(_src) = NULL;			\
	} while (0)

/*! @} */

/*! @} */

#ifdef __cplusplus
}
#endif

#endif /* BABELTRACE2_GRAPH_PORT_H */
Commit	Line	Data
43c59509	1	/*
0235b0db	2	* SPDX-License-Identifier: MIT
43c59509	3	*
0235b0db	4	* Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
43c59509 PP	5	*/
43c59509 PP	6
0235b0db MJ	7	#ifndef BABELTRACE2_GRAPH_PORT_H
	8	#define BABELTRACE2_GRAPH_PORT_H
	9
f38da6ca SM	10	/* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
f38da6ca SM	11
43c59509 PP	12	#ifndef __BT_IN_BABELTRACE_H
	13	# error "Please include <babeltrace2/babeltrace.h> instead."
	14	#endif
	15
	16	#include <stdint.h>
	17
	18	#include <babeltrace2/types.h>
	19
	20	#ifdef __cplusplus
	21	extern "C" {
	22	#endif
	23
	24	/*!
	25	@defgroup api-port Ports
	26	@ingroup api-comp
	27
	28	@brief
	29	\bt_c_comp input and output ports.
	30
	31	A <strong><em>port</em></strong> is a point of \bt_conn between
	32	\bt_p_comp:
	33
	34	@image html component-zoom.png
	35
	36	A port is a \ref api-fund-shared-object "shared object": get a new
	37	reference with bt_port_get_ref() and put an existing reference with
	38	bt_port_put_ref().
	39
	40	The common C type of a port is #bt_port.
	41
	42	There are two types of ports:
	43
	44	<dl>
	45	<dt>\anchor api-port-in Input port</dt>
	46	<dd>
	47	Input connection point from which \bt_p_msg are received.
	48
	49	Filter and sink components have input ports.
	50
	51	An input port's specific type is #bt_port_input and its type
	52	enumerator is #BT_PORT_TYPE_INPUT.
	53
	54	\ref api-fund-c-typing "Upcast" the #bt_port_input type to the
	55	#bt_port type with bt_port_input_as_port_const().
	56
	57	Get a new input port reference with bt_port_input_get_ref() and put
	58	an existing one with bt_port_input_put_ref().
	59	</dd>
	60
	61	<dt>\anchor api-port-out Output port</dt>
	62	<dd>
	63	Output connection point to which messages are sent.
	64
	65	Source and filter components have output ports.
	66
	67	An output port's specific type is #bt_port_output and its type
	68	enumerator is #BT_PORT_TYPE_OUTPUT.
	69
	70	\ref api-fund-c-typing "Upcast" the #bt_port_output type to the
	71	#bt_port type with bt_port_output_as_port_const().
	72
	73	Get a new output port reference with bt_port_output_get_ref() and
	74	put an existing one with bt_port_output_put_ref().
	75	</dd>
76	</dl>
77
78	Get a port's type enumerator with bt_port_get_type(). You can also use
79	the bt_port_is_input() and bt_port_is_output() helper functions.
80
81	A \bt_comp can add a port with:
82
83	- bt_self_component_source_add_output_port()
84	- bt_self_component_filter_add_input_port()
85	- bt_self_component_filter_add_output_port()
86	- bt_self_component_sink_add_input_port()
87
88	Borrow a port's \bt_conn, if any, with
89	bt_port_borrow_connection_const().
90
91	Borrow the component to which a port belongs with
92	bt_port_borrow_component_const().
93
94	<h1>Properties</h1>
95
96	A port has the following common properties:
97
98	<dl>
99	<dt>
100	\anchor api-port-prop-name
101	Name
102	</dt>
103	<dd>
104	Name of the port.
105
106	For a given \bt_comp:
107
108	- Each input port has a unique name.
109	- Each output port has a unique name.
110
111	A port's name is set when the component adds it; you cannot change
112	it afterwards.
113
114	Get a port's name with bt_port_get_name().
115	</dd>
116
117	<dt>
118	\anchor api-port-prop-is-connected
119	Is connected?
120	</dt>
121	<dd>
122	Whether or not the port is currently connected to another port.
123
124	Get whether or not a port is connected with bt_port_is_connected().
125
126	When a port is unconnected, bt_port_borrow_connection_const()
127	returns \c NULL.
128	</dd>
129	</dl>
130	*/
131
132	/! @{ /
133
134	/*!
135	@name Types
136	@{
137
138	@typedef struct bt_port bt_port;
139
140	@brief
141	Port.
142
143	@typedef struct bt_port_input bt_port_input;
144
145	@brief
146	\bt_c_iport.
147
148	@typedef struct bt_port_output bt_port_output;
149
150	@brief
151	\bt_c_oport.
152
153	@}
154	*/
155
156	/*!
157	@name Type query
158	@{
159	*/
160
161	/*!
162	@brief
163	Port type enumerators.
164	*/
165	typedef enum bt_port_type {
166	/*!
167	@brief
168	\bt_c_iport.
169	*/
170	BT_PORT_TYPE_INPUT = 1 << 0,
171
172	/*!
173	@brief
174	\bt_c_oport.
175	*/
176	BT_PORT_TYPE_OUTPUT = 1 << 1,
177	} bt_port_type;
178
179	/*!
180	@brief
181	Returns the type enumerator of the port \bt_p{port}.
182
183	@param[in] port
184	Port of which to get the type enumerator
185
186	@returns
187	Type enumerator of \bt_p{port}.
188
189	@bt_pre_not_null{port}
190
191	@sa bt_port_is_input() —
192	Returns whether or not a port is an \bt_iport.
193	@sa bt_port_is_output() —
194	Returns whether or not a port is an \bt_oport.
195	*/
4c81a2b7	196	extern bt_port_type bt_port_get_type(const bt_port *port) __BT_NOEXCEPT;
43c59509 PP	197
	198	/*!
	199	@brief
	200	Returns whether or not the port \bt_p{port} is an \bt_iport.
	201
	202	@param[in] port
	203	Port to check.
	204
	205	@returns
	206	#BT_TRUE if \bt_p{port} is an input port.
	207
	208	@bt_pre_not_null{port}
	209
	210	@sa bt_port_get_type() —
	211	Returns the type enumerator of a port.
	212	*/
	213	static inline
4c81a2b7	214	bt_bool bt_port_is_input(const bt_port *port) __BT_NOEXCEPT
43c59509 PP	215	{
	216	return bt_port_get_type(port) == BT_PORT_TYPE_INPUT;
	217	}
	218
	219	/*!
	220	@brief
	221	Returns whether or not the port \bt_p{port} is an \bt_oport.
	222
	223	@param[in] port
	224	Port to check.
	225
	226	@returns
	227	#BT_TRUE if \bt_p{port} is an output port.
	228
	229	@bt_pre_not_null{port}
	230
	231	@sa bt_port_get_type() —
	232	Returns the type enumerator of a port.
	233	*/
	234	static inline
4c81a2b7	235	bt_bool bt_port_is_output(const bt_port *port) __BT_NOEXCEPT
43c59509 PP	236	{
	237	return bt_port_get_type(port) == BT_PORT_TYPE_OUTPUT;
	238	}
	239
	240	/! @} /
	241
	242	/*!
	243	@name Connection access
	244	@{
	245	*/
	246
	247	/*!
	248	@brief
	249	Borrows the \bt_conn of the port \bt_p{port}.
	250
	251	This function returns \c NULL if \bt_p{port} is unconnected
	252	(bt_port_is_connected() returns #BT_FALSE).
	253
	254	@param[in] port
	255	Port of which to borrow the connection.
	256
	257	@returns
	258	\em Borrowed reference of the connection of \bt_p{port}.
	259
	260	@bt_pre_not_null{port}
	261	*/
	262	extern const bt_connection *bt_port_borrow_connection_const(
4c81a2b7	263	const bt_port *port) __BT_NOEXCEPT;
43c59509 PP	264
	265	/! @} /
	266
	267	/*!
	268	@name Component access
	269	@{
	270	*/
	271
	272	/*!
	273	@brief
	274	Borrows the \bt_comp to which the port \bt_p{port} belongs.
	275
	276	@param[in] port
	277	Port of which to borrow the component which owns it.
	278
	279	@returns
	280	\em Borrowed reference of the component which owns \bt_p{port}.
	281
	282	@bt_pre_not_null{port}
	283	*/
	284	extern const bt_component *bt_port_borrow_component_const(
4c81a2b7	285	const bt_port *port) __BT_NOEXCEPT;
43c59509 PP	286
	287	/! @} /
	288
	289	/*!
	290	@name Properties
	291	@{
	292	*/
	293
	294	/*!
	295	@brief
	296	Returns the name of the port \bt_p{port}.
	297
	298	See the \ref api-port-prop-name "name" property.
	299
	300	@param[in] port
	301	Port of which to get the name.
	302
	303	@returns
	304	@parblock
	305	Name of \bt_p{port}, or \c NULL if none.
	306
	307	The returned pointer remains valid as long as \bt_p{port} exists.
	308	@endparblock
	309
	310	@bt_pre_not_null{port}
	311	*/
4c81a2b7	312	extern const char bt_port_get_name(const bt_port port) __BT_NOEXCEPT;
43c59509 PP	313
	314	/*!
	315	@brief
	316	Returns whether or not the port \bt_p{port} is connected.
	317
	318	See the \ref api-port-prop-is-connected "is connected?" property.
	319
	320	@param[in] port
	321	Port of which to get whether or not it's connected.
	322
	323	@returns
	324	#BT_TRUE if \bt_p{port} is connected.
	325
	326	@bt_pre_not_null{port}
	327	*/
4c81a2b7	328	extern bt_bool bt_port_is_connected(const bt_port *port) __BT_NOEXCEPT;
43c59509 PP	329
	330	/! @} /
	331
	332	/*!
	333	@name Reference count (common)
	334	@{
	335	*/
	336
	337	/*!
	338	@brief
	339	Increments the \ref api-fund-shared-object "reference count" of
	340	the port \bt_p{port}.
	341
	342	@param[in] port
	343	@parblock
	344	Port of which to increment the reference count.
	345
	346	Can be \c NULL.
	347	@endparblock
	348
	349	@sa bt_port_put_ref() —
	350	Decrements the reference count of a port.
	351	*/
4c81a2b7	352	extern void bt_port_get_ref(const bt_port *port) __BT_NOEXCEPT;
43c59509 PP	353
	354	/*!
	355	@brief
	356	Decrements the \ref api-fund-shared-object "reference count" of
	357	the port \bt_p{port}.
	358
	359	@param[in] port
	360	@parblock
	361	Port of which to decrement the reference count.
	362
	363	Can be \c NULL.
	364	@endparblock
	365
	366	@sa bt_port_get_ref() —
	367	Increments the reference count of a port.
	368	*/
4c81a2b7	369	extern void bt_port_put_ref(const bt_port *port) __BT_NOEXCEPT;
43c59509 PP	370
	371	/*!
	372	@brief
	373	Decrements the reference count of the port
	374	\bt_p{_port}, and then sets \bt_p{_port} to \c NULL.
	375
	376	@param _port
	377	@parblock
	378	Port of which to decrement the reference count.
	379
	380	Can contain \c NULL.
	381	@endparblock
	382
	383	@bt_pre_assign_expr{_port}
	384	*/
	385	#define BT_PORT_PUT_REF_AND_RESET(_port) \
	386	do { \
	387	bt_port_put_ref(_port); \
	388	(_port) = NULL; \
	389	} while (0)
	390
	391	/*!
	392	@brief
	393	Decrements the reference count of the port \bt_p{_dst}, sets
	394	\bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
	395
	396	This macro effectively moves a port reference from the
	397	expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
	398	existing \bt_p{_dst} reference.
	399
	400	@param _dst
	401	@parblock
	402	Destination expression.
	403
	404	Can contain \c NULL.
	405	@endparblock
	406	@param _src
	407	@parblock
	408	Source expression.
	409
	410	Can contain \c NULL.
	411	@endparblock
	412
	413	@bt_pre_assign_expr{_dst}
	414	@bt_pre_assign_expr{_src}
	415	*/
	416	#define BT_PORT_MOVE_REF(_dst, _src) \
	417	do { \
	418	bt_port_put_ref(_dst); \
	419	(_dst) = (_src); \
	420	(_src) = NULL; \
	421	} while (0)
	422
	423	/! @} /
	424
	425	/*!
	426	@name Input port
	427	@{
	428	*/
	429
	430	/*!
	431	@brief
	432	\ref api-fund-c-typing "Upcasts" the \bt_iport \bt_p{port} to the
	433	common #bt_port type.
434
435	@param[in] port
436	@parblock
437	Input port to upcast.
438
439	Can be \c NULL.
440	@endparblock
441
442	@returns
443	\bt_p{port} as a common port.
444	*/
445	static inline
4c81a2b7 PP	446	const bt_port *bt_port_input_as_port_const(
4c81a2b7 PP	447	const bt_port_input *port) __BT_NOEXCEPT
43c59509 PP	448	{
	449	return __BT_UPCAST_CONST(bt_port, port);
	450	}
	451
	452	/*!
	453	@brief
	454	Increments the \ref api-fund-shared-object "reference count" of
	455	the \bt_iport \bt_p{port}.
	456
	457	@param[in] port
	458	@parblock
	459	Input port of which to increment the reference count.
	460
	461	Can be \c NULL.
	462	@endparblock
	463
	464	@sa bt_port_input_put_ref() —
	465	Decrements the reference count of an input port.
	466	*/
4c81a2b7	467	extern void bt_port_input_get_ref(const bt_port_input *port) __BT_NOEXCEPT;
43c59509 PP	468
	469	/*!
	470	@brief
	471	Decrements the \ref api-fund-shared-object "reference count" of
	472	the \bt_iport \bt_p{port}.
	473
	474	@param[in] port
	475	@parblock
	476	Input port of which to decrement the reference count.
	477
	478	Can be \c NULL.
	479	@endparblock
	480
	481	@sa bt_port_input_get_ref() —
	482	Increments the reference count of an input port.
	483	*/
4c81a2b7	484	extern void bt_port_input_put_ref(const bt_port_input *port) __BT_NOEXCEPT;
43c59509 PP	485
	486	/*!
	487	@brief
	488	Decrements the reference count of the \bt_iport
	489	\bt_p{_port}, and then sets \bt_p{_port} to \c NULL.
	490
	491	@param _port
	492	@parblock
	493	Input port of which to decrement the reference count.
	494
	495	Can contain \c NULL.
	496	@endparblock
	497
	498	@bt_pre_assign_expr{_port}
	499	*/
	500	#define BT_PORT_INPUT_PUT_REF_AND_RESET(_port) \
	501	do { \
	502	bt_port_input_put_ref(_port); \
	503	(_port) = NULL; \
	504	} while (0)
	505
	506	/*!
	507	@brief
	508	Decrements the reference count of the \bt_iport \bt_p{_dst}, sets
	509	\bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
	510
	511	This macro effectively moves an \bt_iport reference from the
	512	expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
	513	existing \bt_p{_dst} reference.
	514
	515	@param _dst
	516	@parblock
	517	Destination expression.
	518
	519	Can contain \c NULL.
	520	@endparblock
	521	@param _src
	522	@parblock
	523	Source expression.
	524
	525	Can contain \c NULL.
	526	@endparblock
	527
	528	@bt_pre_assign_expr{_dst}
	529	@bt_pre_assign_expr{_src}
	530	*/
	531	#define BT_PORT_INPUT_MOVE_REF(_dst, _src) \
	532	do { \
	533	bt_port_input_put_ref(_dst); \
	534	(_dst) = (_src); \
	535	(_src) = NULL; \
	536	} while (0)
	537
	538	/! @} /
	539
	540	/*!
	541	@name Output port
	542	@{
	543	*/
	544
	545	/*!
	546	@brief
	547	\ref api-fund-c-typing "Upcasts" the \bt_oport \bt_p{port} to the
	548	common #bt_port type.
549
550	@param[in] port
551	@parblock
552	Output port to upcast.
553
554	Can be \c NULL.
555	@endparblock
556
557	@returns
558	\bt_p{port} as a common port.
559	*/
560	static inline
4c81a2b7 PP	561	const bt_port *bt_port_output_as_port_const(
4c81a2b7 PP	562	const bt_port_output *port) __BT_NOEXCEPT
43c59509 PP	563	{
	564	return __BT_UPCAST_CONST(bt_port, port);
	565	}
	566
	567	/*!
	568	@brief
	569	Increments the \ref api-fund-shared-object "reference count" of
	570	the \bt_oport \bt_p{port}.
	571
	572	@param[in] port
	573	@parblock
	574	Output port of which to increment the reference count.
	575
	576	Can be \c NULL.
	577	@endparblock
	578
	579	@sa bt_port_output_put_ref() —
	580	Decrements the reference count of a \bt_oport.
	581	*/
4c81a2b7	582	extern void bt_port_output_get_ref(const bt_port_output *port) __BT_NOEXCEPT;
43c59509 PP	583
	584	/*!
	585	@brief
	586	Decrements the \ref api-fund-shared-object "reference count" of
	587	the \bt_oport \bt_p{port}.
	588
	589	@param[in] port
	590	@parblock
	591	Output port of which to decrement the reference count.
	592
	593	Can be \c NULL.
	594	@endparblock
	595
	596	@sa bt_port_output_get_ref() —
	597	Increments the reference count of a \bt_oport.
	598	*/
4c81a2b7	599	extern void bt_port_output_put_ref(const bt_port_output *port) __BT_NOEXCEPT;
43c59509 PP	600
	601	/*!
	602	@brief
	603	Decrements the reference count of the \bt_oport
	604	\bt_p{_port}, and then sets \bt_p{_port} to \c NULL.
	605
	606	@param _port
	607	@parblock
	608	Output port of which to decrement the reference count.
	609
	610	Can contain \c NULL.
	611	@endparblock
	612
	613	@bt_pre_assign_expr{_port}
	614	*/
	615	#define BT_PORT_OUTPUT_PUT_REF_AND_RESET(_port) \
	616	do { \
	617	bt_port_output_put_ref(_port); \
	618	(_port) = NULL; \
	619	} while (0)
	620
	621	/*!
	622	@brief
	623	Decrements the reference count of the \bt_oport \bt_p{_dst}, sets
	624	\bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
	625
	626	This macro effectively moves an \bt_oport reference from the
	627	expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
	628	existing \bt_p{_dst} reference.
	629
	630	@param _dst
	631	@parblock
	632	Destination expression.
	633
	634	Can contain \c NULL.
	635	@endparblock
	636	@param _src
	637	@parblock
	638	Source expression.
	639
	640	Can contain \c NULL.
	641	@endparblock
	642
	643	@bt_pre_assign_expr{_dst}
	644	@bt_pre_assign_expr{_src}
	645	*/
	646	#define BT_PORT_OUTPUT_MOVE_REF(_dst, _src) \
	647	do { \
	648	bt_port_output_put_ref(_dst); \
	649	(_dst) = (_src); \
	650	(_src) = NULL; \
	651	} while (0)
	652
	653	/! @} /
	654
	655	/! @} /
	656
	657	#ifdef __cplusplus
	658	}
	659	#endif
	660
	661	#endif /* BABELTRACE2_GRAPH_PORT_H */