include/babeltrace2: add `noexcept` specifier for C++ ≥ 11
[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 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
11
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&nbsp;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() &mdash;
192 Returns whether or not a port is an \bt_iport.
193 @sa bt_port_is_output() &mdash;
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) __BT_NOEXCEPT;
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() &mdash;
211 Returns the type enumerator of a port.
212 */
213 static inline
214 bt_bool bt_port_is_input(const bt_port *port) __BT_NOEXCEPT
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() &mdash;
232 Returns the type enumerator of a port.
233 */
234 static inline
235 bt_bool bt_port_is_output(const bt_port *port) __BT_NOEXCEPT
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) __BT_NOEXCEPT;
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) __BT_NOEXCEPT;
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) __BT_NOEXCEPT;
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) __BT_NOEXCEPT;
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() &mdash;
350 Decrements the reference count of a port.
351 */
352 extern void bt_port_get_ref(const bt_port *port) __BT_NOEXCEPT;
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() &mdash;
367 Increments the reference count of a port.
368 */
369 extern void bt_port_put_ref(const bt_port *port) __BT_NOEXCEPT;
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(
447 const bt_port_input *port) __BT_NOEXCEPT
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() &mdash;
465 Decrements the reference count of an input port.
466 */
467 extern void bt_port_input_get_ref(const bt_port_input *port) __BT_NOEXCEPT;
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() &mdash;
482 Increments the reference count of an input port.
483 */
484 extern void bt_port_input_put_ref(const bt_port_input *port) __BT_NOEXCEPT;
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
561 const bt_port *bt_port_output_as_port_const(
562 const bt_port_output *port) __BT_NOEXCEPT
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() &mdash;
580 Decrements the reference count of a \bt_oport.
581 */
582 extern void bt_port_output_get_ref(const bt_port_output *port) __BT_NOEXCEPT;
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() &mdash;
597 Increments the reference count of a \bt_oport.
598 */
599 extern void bt_port_output_put_ref(const bt_port_output *port) __BT_NOEXCEPT;
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 */
This page took 0.065873 seconds and 4 git commands to generate.