2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_GRAPH_PORT_H
8 #define BABELTRACE2_GRAPH_PORT_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
18 #include <babeltrace2/types.h>
25 @defgroup api-port Ports
29 \bt_c_comp input and output ports.
31 A <strong><em>port</em></strong> is a point of \bt_conn between
34 @image html component-zoom.png
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
40 The common C type of a port is #bt_port.
42 There are two types of ports:
45 <dt>\anchor api-port-in Input port</dt>
47 Input connection point from which \bt_p_msg are received.
49 Filter and sink components have input ports.
51 An input port's specific type is #bt_port_input and its type
52 enumerator is #BT_PORT_TYPE_INPUT.
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().
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().
61 <dt>\anchor api-port-out Output port</dt>
63 Output connection point to which messages are sent.
65 Source and filter components have output ports.
67 An output port's specific type is #bt_port_output and its type
68 enumerator is #BT_PORT_TYPE_OUTPUT.
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().
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().
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.
81 A \bt_comp can add a port with:
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()
88 Borrow a port's \bt_conn, if any, with
89 bt_port_borrow_connection_const().
91 Borrow the component to which a port belongs with
92 bt_port_borrow_component_const().
96 A port has the following common properties:
100 \anchor api-port-prop-name
106 For a given \bt_comp:
108 - Each input port has a unique name.
109 - Each output port has a unique name.
111 A port's name is set when the component adds it; you cannot change
114 Get a port's name with bt_port_get_name().
118 \anchor api-port-prop-is-connected
122 Whether or not the port is currently connected to another port.
124 Get whether or not a port is connected with bt_port_is_connected().
126 When a port is unconnected, bt_port_borrow_connection_const()
138 @typedef struct bt_port bt_port;
143 @typedef struct bt_port_input bt_port_input;
148 @typedef struct bt_port_output bt_port_output;
163 Port type enumerators.
165 typedef enum bt_port_type
{
170 BT_PORT_TYPE_INPUT
= 1 << 0,
176 BT_PORT_TYPE_OUTPUT
= 1 << 1,
181 Returns the type enumerator of the port \bt_p{port}.
184 Port of which to get the type enumerator
187 Type enumerator of \bt_p{port}.
189 @bt_pre_not_null{port}
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.
196 extern bt_port_type
bt_port_get_type(const bt_port
*port
) __BT_NOEXCEPT
;
200 Returns whether or not the port \bt_p{port} is an \bt_iport.
206 #BT_TRUE if \bt_p{port} is an input port.
208 @bt_pre_not_null{port}
210 @sa bt_port_get_type() —
211 Returns the type enumerator of a port.
214 bt_bool
bt_port_is_input(const bt_port
*port
) __BT_NOEXCEPT
216 return bt_port_get_type(port
) == BT_PORT_TYPE_INPUT
;
221 Returns whether or not the port \bt_p{port} is an \bt_oport.
227 #BT_TRUE if \bt_p{port} is an output port.
229 @bt_pre_not_null{port}
231 @sa bt_port_get_type() —
232 Returns the type enumerator of a port.
235 bt_bool
bt_port_is_output(const bt_port
*port
) __BT_NOEXCEPT
237 return bt_port_get_type(port
) == BT_PORT_TYPE_OUTPUT
;
243 @name Connection access
249 Borrows the \bt_conn of the port \bt_p{port}.
251 This function returns \c NULL if \bt_p{port} is unconnected
252 (bt_port_is_connected() returns #BT_FALSE).
255 Port of which to borrow the connection.
258 \em Borrowed reference of the connection of \bt_p{port}.
260 @bt_pre_not_null{port}
262 extern const bt_connection
*bt_port_borrow_connection_const(
263 const bt_port
*port
) __BT_NOEXCEPT
;
268 @name Component access
274 Borrows the \bt_comp to which the port \bt_p{port} belongs.
277 Port of which to borrow the component which owns it.
280 \em Borrowed reference of the component which owns \bt_p{port}.
282 @bt_pre_not_null{port}
284 extern const bt_component
*bt_port_borrow_component_const(
285 const bt_port
*port
) __BT_NOEXCEPT
;
296 Returns the name of the port \bt_p{port}.
298 See the \ref api-port-prop-name "name" property.
301 Port of which to get the name.
305 Name of \bt_p{port}, or \c NULL if none.
307 The returned pointer remains valid as long as \bt_p{port} exists.
310 @bt_pre_not_null{port}
312 extern const char *bt_port_get_name(const bt_port
*port
) __BT_NOEXCEPT
;
316 Returns whether or not the port \bt_p{port} is connected.
318 See the \ref api-port-prop-is-connected "is connected?" property.
321 Port of which to get whether or not it's connected.
324 #BT_TRUE if \bt_p{port} is connected.
326 @bt_pre_not_null{port}
328 extern bt_bool
bt_port_is_connected(const bt_port
*port
) __BT_NOEXCEPT
;
333 @name Reference count (common)
339 Increments the \ref api-fund-shared-object "reference count" of
340 the port \bt_p{port}.
344 Port of which to increment the reference count.
349 @sa bt_port_put_ref() —
350 Decrements the reference count of a port.
352 extern void bt_port_get_ref(const bt_port
*port
) __BT_NOEXCEPT
;
356 Decrements the \ref api-fund-shared-object "reference count" of
357 the port \bt_p{port}.
361 Port of which to decrement the reference count.
366 @sa bt_port_get_ref() —
367 Increments the reference count of a port.
369 extern void bt_port_put_ref(const bt_port
*port
) __BT_NOEXCEPT
;
373 Decrements the reference count of the port
374 \bt_p{_port}, and then sets \bt_p{_port} to \c NULL.
378 Port of which to decrement the reference count.
383 @bt_pre_assign_expr{_port}
385 #define BT_PORT_PUT_REF_AND_RESET(_port) \
387 bt_port_put_ref(_port); \
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.
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.
402 Destination expression.
413 @bt_pre_assign_expr{_dst}
414 @bt_pre_assign_expr{_src}
416 #define BT_PORT_MOVE_REF(_dst, _src) \
418 bt_port_put_ref(_dst); \
432 \ref api-fund-c-typing "Upcasts" the \bt_iport \bt_p{port} to the
433 common #bt_port type.
437 Input port to upcast.
443 \bt_p{port} as a common port.
446 const bt_port
*bt_port_input_as_port_const(
447 const bt_port_input
*port
) __BT_NOEXCEPT
449 return __BT_UPCAST_CONST(bt_port
, port
);
454 Increments the \ref api-fund-shared-object "reference count" of
455 the \bt_iport \bt_p{port}.
459 Input port of which to increment the reference count.
464 @sa bt_port_input_put_ref() —
465 Decrements the reference count of an input port.
467 extern void bt_port_input_get_ref(const bt_port_input
*port
) __BT_NOEXCEPT
;
471 Decrements the \ref api-fund-shared-object "reference count" of
472 the \bt_iport \bt_p{port}.
476 Input port of which to decrement the reference count.
481 @sa bt_port_input_get_ref() —
482 Increments the reference count of an input port.
484 extern void bt_port_input_put_ref(const bt_port_input
*port
) __BT_NOEXCEPT
;
488 Decrements the reference count of the \bt_iport
489 \bt_p{_port}, and then sets \bt_p{_port} to \c NULL.
493 Input port of which to decrement the reference count.
498 @bt_pre_assign_expr{_port}
500 #define BT_PORT_INPUT_PUT_REF_AND_RESET(_port) \
502 bt_port_input_put_ref(_port); \
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.
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.
517 Destination expression.
528 @bt_pre_assign_expr{_dst}
529 @bt_pre_assign_expr{_src}
531 #define BT_PORT_INPUT_MOVE_REF(_dst, _src) \
533 bt_port_input_put_ref(_dst); \
547 \ref api-fund-c-typing "Upcasts" the \bt_oport \bt_p{port} to the
548 common #bt_port type.
552 Output port to upcast.
558 \bt_p{port} as a common port.
561 const bt_port
*bt_port_output_as_port_const(
562 const bt_port_output
*port
) __BT_NOEXCEPT
564 return __BT_UPCAST_CONST(bt_port
, port
);
569 Increments the \ref api-fund-shared-object "reference count" of
570 the \bt_oport \bt_p{port}.
574 Output port of which to increment the reference count.
579 @sa bt_port_output_put_ref() —
580 Decrements the reference count of a \bt_oport.
582 extern void bt_port_output_get_ref(const bt_port_output
*port
) __BT_NOEXCEPT
;
586 Decrements the \ref api-fund-shared-object "reference count" of
587 the \bt_oport \bt_p{port}.
591 Output port of which to decrement the reference count.
596 @sa bt_port_output_get_ref() —
597 Increments the reference count of a \bt_oport.
599 extern void bt_port_output_put_ref(const bt_port_output
*port
) __BT_NOEXCEPT
;
603 Decrements the reference count of the \bt_oport
604 \bt_p{_port}, and then sets \bt_p{_port} to \c NULL.
608 Output port of which to decrement the reference count.
613 @bt_pre_assign_expr{_port}
615 #define BT_PORT_OUTPUT_PUT_REF_AND_RESET(_port) \
617 bt_port_output_put_ref(_port); \
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.
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.
632 Destination expression.
643 @bt_pre_assign_expr{_dst}
644 @bt_pre_assign_expr{_src}
646 #define BT_PORT_OUTPUT_MOVE_REF(_dst, _src) \
648 bt_port_output_put_ref(_dst); \
661 #endif /* BABELTRACE2_GRAPH_PORT_H */
This page took 0.065873 seconds and 4 git commands to generate.