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