Move to kernel style SPDX license identifiers
[babeltrace.git] / include / babeltrace2 / graph / port.h
1 /*
2 * SPDX-License-Identifier: MIT
3 *
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
5 */
6
7 #ifndef BABELTRACE2_GRAPH_PORT_H
8 #define BABELTRACE2_GRAPH_PORT_H
9
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&nbsp;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() &mdash;
190 Returns whether or not a port is an \bt_iport.
191 @sa bt_port_is_output() &mdash;
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() &mdash;
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() &mdash;
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() &mdash;
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() &mdash;
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() &mdash;
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() &mdash;
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() &mdash;
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() &mdash;
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 */
This page took 0.045019 seconds and 4 git commands to generate.