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 | */ |
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> */ |
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( |
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( |
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 */ |