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