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 | */ | |
196 | extern bt_port_type bt_port_get_type(const bt_port *port); | |
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 | |
214 | bt_bool bt_port_is_input(const bt_port *port) | |
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 | |
235 | bt_bool bt_port_is_output(const bt_port *port) | |
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( | |
263 | const bt_port *port); | |
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( | |
285 | const bt_port *port); | |
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 | */ | |
312 | extern const char *bt_port_get_name(const bt_port *port); | |
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 | */ | |
328 | extern bt_bool bt_port_is_connected(const bt_port *port); | |
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 | */ | |
352 | extern void bt_port_get_ref(const bt_port *port); | |
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 | */ | |
369 | extern void bt_port_put_ref(const bt_port *port); | |
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 | |
446 | const bt_port *bt_port_input_as_port_const(const bt_port_input *port) | |
447 | { | |
448 | return __BT_UPCAST_CONST(bt_port, port); | |
449 | } | |
450 | ||
451 | /*! | |
452 | @brief | |
453 | Increments the \ref api-fund-shared-object "reference count" of | |
454 | the \bt_iport \bt_p{port}. | |
455 | ||
456 | @param[in] port | |
457 | @parblock | |
458 | Input port of which to increment the reference count. | |
459 | ||
460 | Can be \c NULL. | |
461 | @endparblock | |
462 | ||
463 | @sa bt_port_input_put_ref() — | |
464 | Decrements the reference count of an input port. | |
465 | */ | |
466 | extern void bt_port_input_get_ref(const bt_port_input *port); | |
467 | ||
468 | /*! | |
469 | @brief | |
470 | Decrements the \ref api-fund-shared-object "reference count" of | |
471 | the \bt_iport \bt_p{port}. | |
472 | ||
473 | @param[in] port | |
474 | @parblock | |
475 | Input port of which to decrement the reference count. | |
476 | ||
477 | Can be \c NULL. | |
478 | @endparblock | |
479 | ||
480 | @sa bt_port_input_get_ref() — | |
481 | Increments the reference count of an input port. | |
482 | */ | |
483 | extern void bt_port_input_put_ref(const bt_port_input *port); | |
484 | ||
485 | /*! | |
486 | @brief | |
487 | Decrements the reference count of the \bt_iport | |
488 | \bt_p{_port}, and then sets \bt_p{_port} to \c NULL. | |
489 | ||
490 | @param _port | |
491 | @parblock | |
492 | Input port of which to decrement the reference count. | |
493 | ||
494 | Can contain \c NULL. | |
495 | @endparblock | |
496 | ||
497 | @bt_pre_assign_expr{_port} | |
498 | */ | |
499 | #define BT_PORT_INPUT_PUT_REF_AND_RESET(_port) \ | |
500 | do { \ | |
501 | bt_port_input_put_ref(_port); \ | |
502 | (_port) = NULL; \ | |
503 | } while (0) | |
504 | ||
505 | /*! | |
506 | @brief | |
507 | Decrements the reference count of the \bt_iport \bt_p{_dst}, sets | |
508 | \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL. | |
509 | ||
510 | This macro effectively moves an \bt_iport reference from the | |
511 | expression \bt_p{_src} to the expression \bt_p{_dst}, putting the | |
512 | existing \bt_p{_dst} reference. | |
513 | ||
514 | @param _dst | |
515 | @parblock | |
516 | Destination expression. | |
517 | ||
518 | Can contain \c NULL. | |
519 | @endparblock | |
520 | @param _src | |
521 | @parblock | |
522 | Source expression. | |
523 | ||
524 | Can contain \c NULL. | |
525 | @endparblock | |
526 | ||
527 | @bt_pre_assign_expr{_dst} | |
528 | @bt_pre_assign_expr{_src} | |
529 | */ | |
530 | #define BT_PORT_INPUT_MOVE_REF(_dst, _src) \ | |
531 | do { \ | |
532 | bt_port_input_put_ref(_dst); \ | |
533 | (_dst) = (_src); \ | |
534 | (_src) = NULL; \ | |
535 | } while (0) | |
536 | ||
537 | /*! @} */ | |
538 | ||
539 | /*! | |
540 | @name Output port | |
541 | @{ | |
542 | */ | |
543 | ||
544 | /*! | |
545 | @brief | |
546 | \ref api-fund-c-typing "Upcasts" the \bt_oport \bt_p{port} to the | |
547 | common #bt_port type. | |
548 | ||
549 | @param[in] port | |
550 | @parblock | |
551 | Output port to upcast. | |
552 | ||
553 | Can be \c NULL. | |
554 | @endparblock | |
555 | ||
556 | @returns | |
557 | \bt_p{port} as a common port. | |
558 | */ | |
559 | static inline | |
560 | const bt_port *bt_port_output_as_port_const(const bt_port_output *port) | |
561 | { | |
562 | return __BT_UPCAST_CONST(bt_port, port); | |
563 | } | |
564 | ||
565 | /*! | |
566 | @brief | |
567 | Increments the \ref api-fund-shared-object "reference count" of | |
568 | the \bt_oport \bt_p{port}. | |
569 | ||
570 | @param[in] port | |
571 | @parblock | |
572 | Output port of which to increment the reference count. | |
573 | ||
574 | Can be \c NULL. | |
575 | @endparblock | |
576 | ||
577 | @sa bt_port_output_put_ref() — | |
578 | Decrements the reference count of a \bt_oport. | |
579 | */ | |
580 | extern void bt_port_output_get_ref(const bt_port_output *port); | |
581 | ||
582 | /*! | |
583 | @brief | |
584 | Decrements the \ref api-fund-shared-object "reference count" of | |
585 | the \bt_oport \bt_p{port}. | |
586 | ||
587 | @param[in] port | |
588 | @parblock | |
589 | Output port of which to decrement the reference count. | |
590 | ||
591 | Can be \c NULL. | |
592 | @endparblock | |
593 | ||
594 | @sa bt_port_output_get_ref() — | |
595 | Increments the reference count of a \bt_oport. | |
596 | */ | |
597 | extern void bt_port_output_put_ref(const bt_port_output *port); | |
598 | ||
599 | /*! | |
600 | @brief | |
601 | Decrements the reference count of the \bt_oport | |
602 | \bt_p{_port}, and then sets \bt_p{_port} to \c NULL. | |
603 | ||
604 | @param _port | |
605 | @parblock | |
606 | Output port of which to decrement the reference count. | |
607 | ||
608 | Can contain \c NULL. | |
609 | @endparblock | |
610 | ||
611 | @bt_pre_assign_expr{_port} | |
612 | */ | |
613 | #define BT_PORT_OUTPUT_PUT_REF_AND_RESET(_port) \ | |
614 | do { \ | |
615 | bt_port_output_put_ref(_port); \ | |
616 | (_port) = NULL; \ | |
617 | } while (0) | |
618 | ||
619 | /*! | |
620 | @brief | |
621 | Decrements the reference count of the \bt_oport \bt_p{_dst}, sets | |
622 | \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL. | |
623 | ||
624 | This macro effectively moves an \bt_oport reference from the | |
625 | expression \bt_p{_src} to the expression \bt_p{_dst}, putting the | |
626 | existing \bt_p{_dst} reference. | |
627 | ||
628 | @param _dst | |
629 | @parblock | |
630 | Destination expression. | |
631 | ||
632 | Can contain \c NULL. | |
633 | @endparblock | |
634 | @param _src | |
635 | @parblock | |
636 | Source expression. | |
637 | ||
638 | Can contain \c NULL. | |
639 | @endparblock | |
640 | ||
641 | @bt_pre_assign_expr{_dst} | |
642 | @bt_pre_assign_expr{_src} | |
643 | */ | |
644 | #define BT_PORT_OUTPUT_MOVE_REF(_dst, _src) \ | |
645 | do { \ | |
646 | bt_port_output_put_ref(_dst); \ | |
647 | (_dst) = (_src); \ | |
648 | (_src) = NULL; \ | |
649 | } while (0) | |
650 | ||
651 | /*! @} */ | |
652 | ||
653 | /*! @} */ | |
654 | ||
655 | #ifdef __cplusplus | |
656 | } | |
657 | #endif | |
658 | ||
659 | #endif /* BABELTRACE2_GRAPH_PORT_H */ |