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_COMPONENT_H |
8 | #define BABELTRACE2_GRAPH_COMPONENT_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 <babeltrace2/graph/component-class.h> | |
17 | #include <babeltrace2/types.h> | |
18 | #include <babeltrace2/logging.h> | |
19 | ||
20 | #ifdef __cplusplus | |
21 | extern "C" { | |
22 | #endif | |
23 | ||
24 | /*! | |
25 | @defgroup api-comp Components | |
26 | @ingroup api-graph | |
27 | ||
28 | @brief | |
29 | Source, filter, and sink components: nodes in a trace processing | |
30 | \bt_graph. | |
31 | ||
32 | A <strong><em>component</em></strong> is a node within a trace | |
33 | processing \bt_graph: | |
34 | ||
35 | @image html component.png | |
36 | ||
37 | A component is \bt_comp_cls instance. Borrow the class of a | |
38 | component with bt_component_borrow_class_const(), | |
39 | bt_component_source_borrow_class_const(), | |
40 | bt_component_filter_borrow_class_const(), and | |
41 | bt_component_sink_borrow_class_const(). | |
42 | ||
43 | A component is a \ref api-fund-shared-object "shared object": get a new | |
44 | reference with bt_component_get_ref() and put an existing reference with | |
45 | bt_component_put_ref(). | |
46 | ||
47 | The common C type of a port is #bt_component. | |
48 | ||
49 | There are three types of components, which come from the three types | |
50 | of component classes: | |
51 | ||
52 | <dl> | |
53 | <dt>\anchor api-comp-src Source component</dt> | |
54 | <dd> | |
55 | A source component's \bt_msg_iter emits fresh \bt_p_msg. | |
56 | ||
57 | A source component's specific type is #bt_component_source and its | |
58 | class's type enumerator is #BT_COMPONENT_CLASS_TYPE_SOURCE. | |
59 | ||
60 | \ref api-fund-c-typing "Upcast" the #bt_component_source type to the | |
61 | #bt_component type with bt_component_source_as_component_const(). | |
62 | ||
63 | Get a new source component reference with | |
64 | bt_component_source_get_ref() and put an existing one with | |
65 | bt_component_source_put_ref(). | |
66 | ||
67 | A source component has \bt_p_oport only. | |
68 | ||
69 | Get the number of output ports a source component has with | |
70 | bt_component_source_get_output_port_count(). | |
71 | ||
72 | Borrow a source component's output port by index with | |
73 | bt_component_source_borrow_output_port_by_index_const() or by name | |
74 | with bt_component_source_borrow_output_port_by_name_const(). | |
75 | </dd> | |
76 | ||
77 | <dt>\anchor api-comp-flt Filter component</dt> | |
78 | <dd> | |
79 | A filter component's message iterator emits fresh and transformed | |
80 | messages. It can also discard existing messages. | |
81 | ||
82 | A filter component's specific type is #bt_component_filter and its | |
83 | class's type enumerator is #BT_COMPONENT_CLASS_TYPE_FILTER. | |
84 | ||
85 | \ref api-fund-c-typing "Upcast" the #bt_component_filter type to the | |
86 | #bt_component type with bt_component_filter_as_component_const(). | |
87 | ||
88 | Get a new filter component reference with | |
89 | bt_component_filter_get_ref() and put an existing one with | |
90 | bt_component_filter_put_ref(). | |
91 | ||
92 | A filter component has \bt_p_iport and \bt_p_oport. | |
93 | ||
94 | Get the number of output ports a filter component has with | |
95 | bt_component_filter_get_output_port_count(). | |
96 | ||
97 | Borrow a filter component's output port by index with | |
98 | bt_component_filter_borrow_output_port_by_index_const() or by name | |
99 | with bt_component_filter_borrow_output_port_by_name_const(). | |
100 | ||
101 | Get the number of input ports a filter component has with | |
102 | bt_component_filter_get_input_port_count(). | |
103 | ||
104 | Borrow a filter component's input port by index with | |
105 | bt_component_filter_borrow_input_port_by_index_const() or by name | |
106 | with bt_component_filter_borrow_input_port_by_name_const(). | |
107 | </dd> | |
108 | ||
109 | <dt>\anchor api-comp-sink Sink component</dt> | |
110 | <dd> | |
111 | A sink component consumes messages from a source or filter message | |
112 | iterator. | |
113 | ||
114 | A filter component's specific type is #bt_component_sink and its | |
115 | class's type enumerator is #BT_COMPONENT_CLASS_TYPE_SINK. | |
116 | ||
117 | \ref api-fund-c-typing "Upcast" the #bt_component_sink type to the | |
118 | #bt_component type with bt_component_sink_as_component_const(). | |
119 | ||
120 | Get a new sink component reference with bt_component_sink_get_ref() | |
121 | and put an existing one with bt_component_sink_put_ref(). | |
122 | ||
123 | A sink component has \bt_p_iport only. | |
124 | ||
125 | Get the number of input ports a sink component has with | |
126 | bt_component_sink_get_input_port_count(). | |
127 | ||
128 | Borrow a sink component's input port by index with | |
129 | bt_component_sink_borrow_input_port_by_index_const() or by name | |
130 | with bt_component_sink_borrow_input_port_by_name_const(). | |
131 | </dd> | |
132 | </dl> | |
133 | ||
134 | Get a component's class type enumerator with | |
135 | bt_component_get_class_type(). You can also use the | |
136 | bt_component_is_source(), bt_component_is_filter(), and | |
137 | bt_component_is_sink() helper functions. | |
138 | ||
139 | You cannot directly create a component: there are no | |
140 | <code>bt_component_*_create()</code> functions. A trace processing | |
141 | \bt_graph creates a component from a \bt_comp_cls when you call one of | |
142 | the <code>bt_graph_add_*_component*()</code> functions. Those functions | |
143 | also return a borrowed reference of the created component through their | |
144 | \bt_p{component} parameter. | |
145 | ||
146 | <h1>Properties</h1> | |
147 | ||
148 | A component has the following common properties: | |
149 | ||
150 | <dl> | |
151 | <dt> | |
152 | \anchor api-comp-prop-name | |
153 | Name | |
154 | </dt> | |
155 | <dd> | |
156 | Name of the component. | |
157 | ||
158 | Each component has a unique name within a given trace processing | |
159 | \bt_graph. | |
160 | ||
161 | A component's name is set when you | |
162 | \ref api-graph-lc-add "add it to a graph" with one of the | |
163 | <code>bt_graph_add_*_component*()</code> functions (\bt_p{name} | |
164 | parameter); you cannot change it afterwards. | |
165 | ||
166 | Get a component's name with bt_component_get_name(). | |
167 | </dd> | |
168 | ||
169 | <dt> | |
170 | \anchor api-comp-prop-log-lvl | |
171 | Logging level | |
172 | </dt> | |
173 | <dd> | |
174 | Logging level of the component (and its message iterators, if any). | |
175 | ||
176 | A component's logging level is set when you | |
177 | \ref api-graph-lc-add "add it to a trace processing graph" with one | |
178 | of the <code>bt_graph_add_*_component*()</code> functions | |
179 | (\bt_p{logging_level} parameter); as of | |
180 | \bt_name_version_min_maj, you cannot change it afterwards. | |
181 | ||
182 | Get a component's logging level with | |
183 | bt_component_get_logging_level(). | |
184 | </dd> | |
185 | </dl> | |
186 | */ | |
187 | ||
188 | /*! @{ */ | |
189 | ||
190 | /*! | |
191 | @name Types | |
192 | @{ | |
193 | ||
194 | @typedef struct bt_component bt_component; | |
195 | ||
196 | @brief | |
197 | Component. | |
198 | ||
199 | @typedef struct bt_component_source bt_component_source; | |
200 | ||
201 | @brief | |
202 | \bt_c_src_comp. | |
203 | ||
204 | @typedef struct bt_component_filter bt_component_filter; | |
205 | ||
206 | @brief | |
207 | \bt_c_flt_comp. | |
208 | ||
209 | @typedef struct bt_component_sink bt_component_sink; | |
210 | ||
211 | @brief | |
212 | \bt_c_sink_comp. | |
213 | ||
214 | @} | |
215 | */ | |
216 | ||
217 | /*! | |
218 | @name Class type query | |
219 | @{ | |
220 | */ | |
221 | ||
222 | /*! | |
223 | @brief | |
224 | Returns the type enumerator of the \ref api-comp-cls "class" of | |
225 | the component \bt_p{component}. | |
226 | ||
227 | @param[in] component | |
228 | Component of which to get the class's type enumerator. | |
229 | ||
230 | @returns | |
231 | Type enumerator of the class of \bt_p{component}. | |
232 | ||
233 | @bt_pre_not_null{component} | |
234 | ||
235 | @sa bt_component_is_source() — | |
236 | Returns whether or not a component is a \bt_src_comp. | |
237 | @sa bt_component_is_filter() — | |
238 | Returns whether or not a component is a \bt_flt_comp. | |
239 | @sa bt_component_is_sink() — | |
240 | Returns whether or not a component is a \bt_sink_comp. | |
241 | */ | |
242 | extern bt_component_class_type bt_component_get_class_type( | |
4c81a2b7 | 243 | const bt_component *component) __BT_NOEXCEPT; |
43c59509 PP |
244 | |
245 | /*! | |
246 | @brief | |
247 | Returns whether or not the component \bt_p{component} is a | |
248 | \bt_src_comp. | |
249 | ||
250 | @param[in] component | |
251 | Component to check. | |
252 | ||
253 | @returns | |
254 | #BT_TRUE if \bt_p{component} is a source component. | |
255 | ||
256 | @bt_pre_not_null{component} | |
257 | ||
258 | @sa bt_component_get_class_type() — | |
259 | Returns the type enumerator of a component's class. | |
260 | */ | |
261 | static inline | |
4c81a2b7 | 262 | bt_bool bt_component_is_source(const bt_component *component) __BT_NOEXCEPT |
43c59509 PP |
263 | { |
264 | return bt_component_get_class_type(component) == | |
265 | BT_COMPONENT_CLASS_TYPE_SOURCE; | |
266 | } | |
267 | ||
268 | /*! | |
269 | @brief | |
270 | Returns whether or not the component \bt_p{component} is a | |
271 | \bt_flt_comp. | |
272 | ||
273 | @param[in] component | |
274 | Component to check. | |
275 | ||
276 | @returns | |
277 | #BT_TRUE if \bt_p{component} is a filter component. | |
278 | ||
279 | @bt_pre_not_null{component} | |
280 | ||
281 | @sa bt_component_get_class_type() — | |
282 | Returns the type enumerator of a component's class. | |
283 | */ | |
284 | static inline | |
4c81a2b7 | 285 | bt_bool bt_component_is_filter(const bt_component *component) __BT_NOEXCEPT |
43c59509 PP |
286 | { |
287 | return bt_component_get_class_type(component) == | |
288 | BT_COMPONENT_CLASS_TYPE_FILTER; | |
289 | } | |
290 | ||
291 | /*! | |
292 | @brief | |
293 | Returns whether or not the component \bt_p{component} is a | |
294 | \bt_sink_comp. | |
295 | ||
296 | @param[in] component | |
297 | Component to check. | |
298 | ||
299 | @returns | |
300 | #BT_TRUE if \bt_p{component} is a sink component. | |
301 | ||
302 | @bt_pre_not_null{component} | |
303 | ||
304 | @sa bt_component_get_class_type() — | |
305 | Returns the type enumerator of a component's class. | |
306 | */ | |
307 | static inline | |
4c81a2b7 | 308 | bt_bool bt_component_is_sink(const bt_component *component) __BT_NOEXCEPT |
43c59509 PP |
309 | { |
310 | return bt_component_get_class_type(component) == | |
311 | BT_COMPONENT_CLASS_TYPE_SINK; | |
312 | } | |
313 | ||
314 | /*! @} */ | |
315 | ||
316 | /*! | |
317 | @name Common class access | |
318 | @{ | |
319 | */ | |
320 | ||
321 | /*! | |
322 | @brief | |
323 | Borrows the \ref api-comp-cls "class" of the component | |
324 | \bt_p{component}. | |
325 | ||
326 | @param[in] component | |
327 | Component of which to borrow the class. | |
328 | ||
329 | @returns | |
330 | \em Borrowed reference of the class of \bt_p{component}. | |
331 | ||
332 | @bt_pre_not_null{component} | |
333 | */ | |
334 | extern const bt_component_class *bt_component_borrow_class_const( | |
4c81a2b7 | 335 | const bt_component *component) __BT_NOEXCEPT; |
43c59509 PP |
336 | |
337 | /*! @} */ | |
338 | ||
339 | /*! | |
340 | @name Common properties | |
341 | @{ | |
342 | */ | |
343 | ||
344 | /*! | |
345 | @brief | |
346 | Returns the name of the component \bt_p{component}. | |
347 | ||
348 | See the \ref api-comp-prop-name "name" property. | |
349 | ||
350 | @param[in] component | |
351 | Component of which to get the name. | |
352 | ||
353 | @returns | |
354 | @parblock | |
355 | Name of \bt_p{component}. | |
356 | ||
357 | The returned pointer remains valid as long as \bt_p{component} | |
358 | exists. | |
359 | @endparblock | |
360 | ||
361 | @bt_pre_not_null{component} | |
362 | */ | |
4c81a2b7 PP |
363 | extern const char *bt_component_get_name(const bt_component *component) |
364 | __BT_NOEXCEPT; | |
43c59509 PP |
365 | |
366 | /*! | |
367 | @brief | |
368 | Returns the logging level of the component \bt_p{component} and its | |
369 | \bt_p_msg_iter, if any. | |
370 | ||
371 | See the \ref api-comp-prop-log-lvl "logging level" property. | |
372 | ||
373 | @param[in] component | |
374 | Component of which to get the logging level. | |
375 | ||
376 | @returns | |
377 | Logging level of \bt_p{component}. | |
378 | ||
379 | @bt_pre_not_null{component} | |
380 | */ | |
381 | extern bt_logging_level bt_component_get_logging_level( | |
4c81a2b7 | 382 | const bt_component *component) __BT_NOEXCEPT; |
43c59509 PP |
383 | |
384 | /*! @} */ | |
385 | ||
386 | /*! | |
387 | @name Common reference count | |
388 | @{ | |
389 | */ | |
390 | ||
391 | /*! | |
392 | @brief | |
393 | Increments the \ref api-fund-shared-object "reference count" of | |
394 | the component \bt_p{component}. | |
395 | ||
396 | @param[in] component | |
397 | @parblock | |
398 | Component of which to increment the reference count. | |
399 | ||
400 | Can be \c NULL. | |
401 | @endparblock | |
402 | ||
403 | @sa bt_component_put_ref() — | |
404 | Decrements the reference count of a component. | |
405 | */ | |
4c81a2b7 | 406 | extern void bt_component_get_ref(const bt_component *component) __BT_NOEXCEPT; |
43c59509 PP |
407 | |
408 | /*! | |
409 | @brief | |
410 | Decrements the \ref api-fund-shared-object "reference count" of | |
411 | the component \bt_p{component}. | |
412 | ||
413 | @param[in] component | |
414 | @parblock | |
415 | Component of which to decrement the reference count. | |
416 | ||
417 | Can be \c NULL. | |
418 | @endparblock | |
419 | ||
420 | @sa bt_component_get_ref() — | |
421 | Increments the reference count of a component. | |
422 | */ | |
4c81a2b7 | 423 | extern void bt_component_put_ref(const bt_component *component) __BT_NOEXCEPT; |
43c59509 PP |
424 | |
425 | /*! | |
426 | @brief | |
427 | Decrements the reference count of the component | |
428 | \bt_p{_component}, and then sets \bt_p{_component} to \c NULL. | |
429 | ||
430 | @param _component | |
431 | @parblock | |
432 | Component of which to decrement the reference count. | |
433 | ||
434 | Can contain \c NULL. | |
435 | @endparblock | |
436 | ||
437 | @bt_pre_assign_expr{_component} | |
438 | */ | |
439 | #define BT_COMPONENT_PUT_REF_AND_RESET(_component) \ | |
440 | do { \ | |
441 | bt_component_put_ref(_component); \ | |
442 | (_component) = NULL; \ | |
443 | } while (0) | |
444 | ||
445 | /*! | |
446 | @brief | |
447 | Decrements the reference count of the component \bt_p{_dst}, sets | |
448 | \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL. | |
449 | ||
450 | This macro effectively moves a component reference from the expression | |
451 | \bt_p{_src} to the expression \bt_p{_dst}, putting the existing | |
452 | \bt_p{_dst} reference. | |
453 | ||
454 | @param _dst | |
455 | @parblock | |
456 | Destination expression. | |
457 | ||
458 | Can contain \c NULL. | |
459 | @endparblock | |
460 | @param _src | |
461 | @parblock | |
462 | Source expression. | |
463 | ||
464 | Can contain \c NULL. | |
465 | @endparblock | |
466 | ||
467 | @bt_pre_assign_expr{_dst} | |
468 | @bt_pre_assign_expr{_src} | |
469 | */ | |
470 | #define BT_COMPONENT_MOVE_REF(_dst, _src) \ | |
471 | do { \ | |
472 | bt_component_put_ref(_dst); \ | |
473 | (_dst) = (_src); \ | |
474 | (_src) = NULL; \ | |
475 | } while (0) | |
476 | ||
477 | /*! @} */ | |
478 | ||
479 | /*! | |
480 | @name Source component class access | |
481 | @{ | |
482 | */ | |
483 | ||
484 | /*! | |
485 | @brief | |
486 | Borrows the \ref api-comp-cls "class" of the \bt_src_comp | |
487 | \bt_p{component}. | |
488 | ||
489 | @param[in] component | |
490 | Source component of which to borrow the class. | |
491 | ||
492 | @returns | |
493 | \em Borrowed reference of the class of \bt_p{component}. | |
494 | ||
495 | @bt_pre_not_null{component} | |
496 | */ | |
497 | extern const bt_component_class_source * | |
498 | bt_component_source_borrow_class_const( | |
4c81a2b7 | 499 | const bt_component_source *component) __BT_NOEXCEPT; |
43c59509 PP |
500 | |
501 | /*! @} */ | |
502 | ||
503 | /*! | |
504 | @name Source component upcast | |
505 | @{ | |
506 | */ | |
507 | ||
508 | /*! | |
509 | @brief | |
510 | \ref api-fund-c-typing "Upcasts" the \bt_src_comp \bt_p{component} | |
511 | to the common #bt_component type. | |
512 | ||
513 | @param[in] component | |
514 | @parblock | |
515 | Source component to upcast. | |
516 | ||
517 | Can be \c NULL. | |
518 | @endparblock | |
519 | ||
520 | @returns | |
521 | \bt_p{component} as a common component. | |
522 | */ | |
523 | static inline | |
524 | const bt_component *bt_component_source_as_component_const( | |
4c81a2b7 | 525 | const bt_component_source *component) __BT_NOEXCEPT |
43c59509 PP |
526 | { |
527 | return __BT_UPCAST_CONST(bt_component, component); | |
528 | } | |
529 | ||
530 | /*! @} */ | |
531 | ||
532 | /*! | |
533 | @name Source component port access | |
534 | @{ | |
535 | */ | |
536 | ||
537 | /*! | |
538 | @brief | |
539 | Returns the number of \bt_p_oport that the \bt_src_comp | |
540 | \bt_p{component} has. | |
541 | ||
542 | @param[in] component | |
543 | Source component of which to get the number of output ports. | |
544 | ||
545 | @returns | |
546 | Number of output ports that \bt_p{component} has. | |
547 | ||
548 | @bt_pre_not_null{component} | |
549 | */ | |
550 | extern uint64_t bt_component_source_get_output_port_count( | |
4c81a2b7 | 551 | const bt_component_source *component) __BT_NOEXCEPT; |
43c59509 PP |
552 | |
553 | /*! | |
554 | @brief | |
555 | Borrows the \bt_oport at index \bt_p{index} from the | |
556 | \bt_src_comp \bt_p{component}. | |
557 | ||
558 | @param[in] component | |
559 | Source component from which to borrow the output port at index | |
560 | \bt_p{index}. | |
561 | @param[in] index | |
562 | Index of the output port to borrow from \bt_p{component}. | |
563 | ||
564 | @returns | |
565 | @parblock | |
566 | \em Borrowed reference of the output port of | |
567 | \bt_p{component} at index \bt_p{index}. | |
568 | ||
569 | The returned pointer remains valid as long as \bt_p{component} | |
570 | exists. | |
571 | @endparblock | |
572 | ||
573 | @bt_pre_not_null{component} | |
574 | @pre | |
575 | \bt_p{index} is less than the number of output ports | |
576 | \bt_p{component} has (as returned by | |
577 | bt_component_source_get_output_port_count()). | |
578 | ||
579 | @sa bt_component_source_get_output_port_count() — | |
580 | Returns the number of output ports that a source component has. | |
581 | */ | |
582 | extern const bt_port_output * | |
583 | bt_component_source_borrow_output_port_by_index_const( | |
4c81a2b7 PP |
584 | const bt_component_source *component, |
585 | uint64_t index) __BT_NOEXCEPT; | |
43c59509 PP |
586 | |
587 | /*! | |
588 | @brief | |
589 | Borrows the \bt_oport named \bt_p{name} from the \bt_src_comp | |
590 | \bt_p{component}. | |
591 | ||
592 | If \bt_p{component} has no output port named \bt_p{name}, this function | |
593 | returns \c NULL. | |
594 | ||
595 | @param[in] component | |
596 | Source component from which to borrow the output port | |
597 | named \bt_p{name}. | |
598 | @param[in] name | |
599 | Name of the output port to borrow from \bt_p{component}. | |
600 | ||
601 | @returns | |
602 | @parblock | |
603 | \em Borrowed reference of the output port of | |
604 | \bt_p{component} named \bt_p{name}, or \c NULL if none. | |
605 | ||
606 | The returned pointer remains valid as long as \bt_p{component} | |
607 | exists. | |
608 | @endparblock | |
609 | ||
610 | @bt_pre_not_null{component} | |
611 | @bt_pre_not_null{name} | |
612 | */ | |
613 | extern const bt_port_output * | |
614 | bt_component_source_borrow_output_port_by_name_const( | |
4c81a2b7 PP |
615 | const bt_component_source *component, |
616 | const char *name) __BT_NOEXCEPT; | |
43c59509 PP |
617 | |
618 | /*! @} */ | |
619 | ||
620 | /*! | |
621 | @name Source component reference count | |
622 | @{ | |
623 | */ | |
624 | ||
625 | /*! | |
626 | @brief | |
627 | Increments the \ref api-fund-shared-object "reference count" of | |
628 | the \bt_src_comp \bt_p{component}. | |
629 | ||
630 | @param[in] component | |
631 | @parblock | |
632 | Source component of which to increment the reference count. | |
633 | ||
634 | Can be \c NULL. | |
635 | @endparblock | |
636 | ||
637 | @sa bt_component_source_put_ref() — | |
638 | Decrements the reference count of a source component. | |
639 | */ | |
640 | extern void bt_component_source_get_ref( | |
4c81a2b7 | 641 | const bt_component_source *component) __BT_NOEXCEPT; |
43c59509 PP |
642 | |
643 | /*! | |
644 | @brief | |
645 | Decrements the \ref api-fund-shared-object "reference count" of | |
646 | the \bt_src_comp \bt_p{component}. | |
647 | ||
648 | @param[in] component | |
649 | @parblock | |
650 | Source component of which to decrement the reference count. | |
651 | ||
652 | Can be \c NULL. | |
653 | @endparblock | |
654 | ||
655 | @sa bt_component_source_get_ref() — | |
656 | Increments the reference count of a source component. | |
657 | */ | |
658 | extern void bt_component_source_put_ref( | |
4c81a2b7 | 659 | const bt_component_source *component) __BT_NOEXCEPT; |
43c59509 PP |
660 | |
661 | /*! | |
662 | @brief | |
663 | Decrements the reference count of the \bt_src_comp | |
664 | \bt_p{_component}, and then sets \bt_p{_component} to \c NULL. | |
665 | ||
666 | @param _component | |
667 | @parblock | |
668 | Source component of which to decrement the reference count. | |
669 | ||
670 | Can contain \c NULL. | |
671 | @endparblock | |
672 | ||
673 | @bt_pre_assign_expr{_component} | |
674 | */ | |
675 | #define BT_COMPONENT_SOURCE_PUT_REF_AND_RESET(_component) \ | |
676 | do { \ | |
677 | bt_component_source_put_ref(_component); \ | |
678 | (_component) = NULL; \ | |
679 | } while (0) | |
680 | ||
681 | /*! | |
682 | @brief | |
683 | Decrements the reference count of the \bt_src_comp \bt_p{_dst}, sets | |
684 | \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL. | |
685 | ||
686 | This macro effectively moves a source component reference from the | |
687 | expression \bt_p{_src} to the expression \bt_p{_dst}, putting the | |
688 | existing \bt_p{_dst} reference. | |
689 | ||
690 | @param _dst | |
691 | @parblock | |
692 | Destination expression. | |
693 | ||
694 | Can contain \c NULL. | |
695 | @endparblock | |
696 | @param _src | |
697 | @parblock | |
698 | Source expression. | |
699 | ||
700 | Can contain \c NULL. | |
701 | @endparblock | |
702 | ||
703 | @bt_pre_assign_expr{_dst} | |
704 | @bt_pre_assign_expr{_src} | |
705 | */ | |
706 | #define BT_COMPONENT_SOURCE_MOVE_REF(_dst, _src) \ | |
707 | do { \ | |
708 | bt_component_source_put_ref(_dst); \ | |
709 | (_dst) = (_src); \ | |
710 | (_src) = NULL; \ | |
711 | } while (0) | |
712 | ||
713 | /*! @} */ | |
714 | ||
715 | /*! | |
716 | @name Filter component class access | |
717 | @{ | |
718 | */ | |
719 | ||
720 | /*! | |
721 | @brief | |
722 | Borrows the \ref api-comp-cls "class" of the \bt_flt_comp | |
723 | \bt_p{component}. | |
724 | ||
725 | @param[in] component | |
726 | Filter component of which to borrow the class. | |
727 | ||
728 | @returns | |
729 | \em Borrowed reference of the class of \bt_p{component}. | |
730 | ||
731 | @bt_pre_not_null{component} | |
732 | */ | |
733 | extern const bt_component_class_filter * | |
734 | bt_component_filter_borrow_class_const( | |
4c81a2b7 | 735 | const bt_component_filter *component) __BT_NOEXCEPT; |
43c59509 PP |
736 | |
737 | /*! @} */ | |
738 | ||
739 | /*! | |
740 | @name Filter component upcast | |
741 | @{ | |
742 | */ | |
743 | ||
744 | /*! | |
745 | @brief | |
746 | \ref api-fund-c-typing "Upcasts" the \bt_flt_comp \bt_p{component} | |
747 | to the common #bt_component type. | |
748 | ||
749 | @param[in] component | |
750 | @parblock | |
751 | Filter component to upcast. | |
752 | ||
753 | Can be \c NULL. | |
754 | @endparblock | |
755 | ||
756 | @returns | |
757 | \bt_p{component} as a common component. | |
758 | */ | |
759 | static inline | |
760 | const bt_component *bt_component_filter_as_component_const( | |
4c81a2b7 | 761 | const bt_component_filter *component) __BT_NOEXCEPT |
43c59509 PP |
762 | { |
763 | return __BT_UPCAST_CONST(bt_component, component); | |
764 | } | |
765 | ||
766 | /*! @} */ | |
767 | ||
768 | /*! | |
769 | @name Filter component port access | |
770 | @{ | |
771 | */ | |
772 | ||
773 | /*! | |
774 | @brief | |
775 | Returns the number of \bt_p_iport that the \bt_flt_comp | |
776 | \bt_p{component} has. | |
777 | ||
778 | @param[in] component | |
779 | Filter component of which to get the number of input ports. | |
780 | ||
781 | @returns | |
782 | Number of input ports that \bt_p{component} has. | |
783 | ||
784 | @bt_pre_not_null{component} | |
785 | */ | |
786 | extern uint64_t bt_component_filter_get_input_port_count( | |
4c81a2b7 | 787 | const bt_component_filter *component) __BT_NOEXCEPT; |
43c59509 PP |
788 | |
789 | /*! | |
790 | @brief | |
791 | Borrows the \bt_iport at index \bt_p{index} from the | |
792 | \bt_flt_comp \bt_p{component}. | |
793 | ||
794 | @param[in] component | |
795 | Filter component from which to borrow the input port at index | |
796 | \bt_p{index}. | |
797 | @param[in] index | |
798 | Index of the input port to borrow from \bt_p{component}. | |
799 | ||
800 | @returns | |
801 | @parblock | |
802 | \em Borrowed reference of the input port of | |
803 | \bt_p{component} at index \bt_p{index}. | |
804 | ||
805 | The returned pointer remains valid as long as \bt_p{component} | |
806 | exists. | |
807 | @endparblock | |
808 | ||
809 | @bt_pre_not_null{component} | |
810 | @pre | |
811 | \bt_p{index} is less than the number of input ports | |
812 | \bt_p{component} has (as returned by | |
813 | bt_component_filter_get_input_port_count()). | |
814 | ||
815 | @sa bt_component_filter_get_input_port_count() — | |
816 | Returns the number of input ports that a filter component has. | |
817 | */ | |
818 | extern const bt_port_input * | |
819 | bt_component_filter_borrow_input_port_by_index_const( | |
4c81a2b7 PP |
820 | const bt_component_filter *component, uint64_t index) |
821 | __BT_NOEXCEPT; | |
43c59509 PP |
822 | |
823 | /*! | |
824 | @brief | |
825 | Borrows the \bt_iport named \bt_p{name} from the \bt_flt_comp | |
826 | \bt_p{component}. | |
827 | ||
828 | If \bt_p{component} has no input port named \bt_p{name}, this function | |
829 | returns \c NULL. | |
830 | ||
831 | @param[in] component | |
832 | Filter component from which to borrow the input port | |
833 | named \bt_p{name}. | |
834 | @param[in] name | |
835 | Name of the input port to borrow from \bt_p{component}. | |
836 | ||
837 | @returns | |
838 | @parblock | |
839 | \em Borrowed reference of the input port of | |
840 | \bt_p{component} named \bt_p{name}, or \c NULL if none. | |
841 | ||
842 | The returned pointer remains valid as long as \bt_p{component} | |
843 | exists. | |
844 | @endparblock | |
845 | ||
846 | @bt_pre_not_null{component} | |
847 | @bt_pre_not_null{name} | |
848 | */ | |
849 | extern const bt_port_input * | |
850 | bt_component_filter_borrow_input_port_by_name_const( | |
4c81a2b7 PP |
851 | const bt_component_filter *component, const char *name) |
852 | __BT_NOEXCEPT; | |
43c59509 PP |
853 | |
854 | /*! | |
855 | @brief | |
856 | Returns the number of \bt_p_oport that the \bt_flt_comp | |
857 | \bt_p{component} has. | |
858 | ||
859 | @param[in] component | |
860 | Filter component of which to get the number of output ports. | |
861 | ||
862 | @returns | |
863 | Number of output ports that \bt_p{component} has. | |
864 | ||
865 | @bt_pre_not_null{component} | |
866 | */ | |
867 | extern uint64_t bt_component_filter_get_output_port_count( | |
4c81a2b7 | 868 | const bt_component_filter *component) __BT_NOEXCEPT; |
43c59509 PP |
869 | |
870 | /*! | |
871 | @brief | |
872 | Borrows the \bt_oport at index \bt_p{index} from the | |
873 | \bt_flt_comp \bt_p{component}. | |
874 | ||
875 | @param[in] component | |
876 | Filter component from which to borrow the output port at index | |
877 | \bt_p{index}. | |
878 | @param[in] index | |
879 | Index of the output port to borrow from \bt_p{component}. | |
880 | ||
881 | @returns | |
882 | @parblock | |
883 | \em Borrowed reference of the output port of | |
884 | \bt_p{component} at index \bt_p{index}. | |
885 | ||
886 | The returned pointer remains valid as long as \bt_p{component} | |
887 | exists. | |
888 | @endparblock | |
889 | ||
890 | @bt_pre_not_null{component} | |
891 | @pre | |
892 | \bt_p{index} is less than the number of output ports | |
893 | \bt_p{component} has (as returned by | |
894 | bt_component_filter_get_output_port_count()). | |
895 | ||
896 | @sa bt_component_filter_get_output_port_count() — | |
897 | Returns the number of output ports that a filter component has. | |
898 | */ | |
899 | extern const bt_port_output * | |
900 | bt_component_filter_borrow_output_port_by_index_const( | |
4c81a2b7 PP |
901 | const bt_component_filter *component, uint64_t index) |
902 | __BT_NOEXCEPT; | |
43c59509 PP |
903 | |
904 | /*! | |
905 | @brief | |
906 | Borrows the \bt_oport named \bt_p{name} from the \bt_flt_comp | |
907 | \bt_p{component}. | |
908 | ||
909 | If \bt_p{component} has no output port named \bt_p{name}, this function | |
910 | returns \c NULL. | |
911 | ||
912 | @param[in] component | |
913 | Filter component from which to borrow the output port | |
914 | named \bt_p{name}. | |
915 | @param[in] name | |
916 | Name of the output port to borrow from \bt_p{component}. | |
917 | ||
918 | @returns | |
919 | @parblock | |
920 | \em Borrowed reference of the output port of | |
921 | \bt_p{component} named \bt_p{name}, or \c NULL if none. | |
922 | ||
923 | The returned pointer remains valid as long as \bt_p{component} | |
924 | exists. | |
925 | @endparblock | |
926 | ||
927 | @bt_pre_not_null{component} | |
928 | @bt_pre_not_null{name} | |
929 | */ | |
930 | extern const bt_port_output * | |
931 | bt_component_filter_borrow_output_port_by_name_const( | |
4c81a2b7 PP |
932 | const bt_component_filter *component, const char *name) |
933 | __BT_NOEXCEPT; | |
43c59509 PP |
934 | |
935 | /*! @} */ | |
936 | ||
937 | /*! | |
938 | @name Filter component reference count | |
939 | @{ | |
940 | */ | |
941 | ||
942 | /*! | |
943 | @brief | |
944 | Increments the \ref api-fund-shared-object "reference count" of | |
945 | the \bt_flt_comp \bt_p{component}. | |
946 | ||
947 | @param[in] component | |
948 | @parblock | |
949 | Filter component of which to increment the reference count. | |
950 | ||
951 | Can be \c NULL. | |
952 | @endparblock | |
953 | ||
954 | @sa bt_component_filter_put_ref() — | |
955 | Decrements the reference count of a filter component. | |
956 | */ | |
957 | extern void bt_component_filter_get_ref( | |
4c81a2b7 | 958 | const bt_component_filter *component) __BT_NOEXCEPT; |
43c59509 PP |
959 | |
960 | /*! | |
961 | @brief | |
962 | Decrements the \ref api-fund-shared-object "reference count" of | |
963 | the \bt_flt_comp \bt_p{component}. | |
964 | ||
965 | @param[in] component | |
966 | @parblock | |
967 | Filter component of which to decrement the reference count. | |
968 | ||
969 | Can be \c NULL. | |
970 | @endparblock | |
971 | ||
972 | @sa bt_component_filter_get_ref() — | |
973 | Increments the reference count of a filter component. | |
974 | */ | |
975 | extern void bt_component_filter_put_ref( | |
4c81a2b7 | 976 | const bt_component_filter *component) __BT_NOEXCEPT; |
43c59509 PP |
977 | |
978 | /*! | |
979 | @brief | |
980 | Decrements the reference count of the \bt_flt_comp | |
981 | \bt_p{_component}, and then sets \bt_p{_component} to \c NULL. | |
982 | ||
983 | @param _component | |
984 | @parblock | |
985 | Filter component of which to decrement the reference count. | |
986 | ||
987 | Can contain \c NULL. | |
988 | @endparblock | |
989 | ||
990 | @bt_pre_assign_expr{_component} | |
991 | */ | |
992 | #define BT_COMPONENT_FILTER_PUT_REF_AND_RESET(_component) \ | |
993 | do { \ | |
994 | bt_component_filter_put_ref(_component); \ | |
995 | (_component) = NULL; \ | |
996 | } while (0) | |
997 | ||
998 | /*! | |
999 | @brief | |
1000 | Decrements the reference count of the \bt_flt_comp \bt_p{_dst}, sets | |
1001 | \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL. | |
1002 | ||
1003 | This macro effectively moves a filter component reference from the | |
1004 | expression \bt_p{_src} to the expression \bt_p{_dst}, putting the | |
1005 | existing \bt_p{_dst} reference. | |
1006 | ||
1007 | @param _dst | |
1008 | @parblock | |
1009 | Destination expression. | |
1010 | ||
1011 | Can contain \c NULL. | |
1012 | @endparblock | |
1013 | @param _src | |
1014 | @parblock | |
1015 | Source expression. | |
1016 | ||
1017 | Can contain \c NULL. | |
1018 | @endparblock | |
1019 | ||
1020 | @bt_pre_assign_expr{_dst} | |
1021 | @bt_pre_assign_expr{_src} | |
1022 | */ | |
1023 | #define BT_COMPONENT_FILTER_MOVE_REF(_dst, _src) \ | |
1024 | do { \ | |
1025 | bt_component_filter_put_ref(_dst); \ | |
1026 | (_dst) = (_src); \ | |
1027 | (_src) = NULL; \ | |
1028 | } while (0) | |
1029 | ||
1030 | /*! @} */ | |
1031 | ||
1032 | /*! | |
1033 | @name Sink component class access | |
1034 | @{ | |
1035 | */ | |
1036 | ||
1037 | /*! | |
1038 | @brief | |
1039 | Borrows the \ref api-comp-cls "class" of the \bt_sink_comp | |
1040 | \bt_p{component}. | |
1041 | ||
1042 | @param[in] component | |
1043 | Sink component of which to borrow the class. | |
1044 | ||
1045 | @returns | |
1046 | \em Borrowed reference of the class of \bt_p{component}. | |
1047 | ||
1048 | @bt_pre_not_null{component} | |
1049 | */ | |
1050 | extern const bt_component_class_sink * | |
1051 | bt_component_sink_borrow_class_const( | |
4c81a2b7 | 1052 | const bt_component_sink *component) __BT_NOEXCEPT; |
43c59509 PP |
1053 | |
1054 | /*! @} */ | |
1055 | ||
1056 | /*! | |
1057 | @name Sink component upcast | |
1058 | @{ | |
1059 | */ | |
1060 | ||
1061 | /*! | |
1062 | @brief | |
1063 | \ref api-fund-c-typing "Upcasts" the \bt_sink_comp \bt_p{component} | |
1064 | to the common #bt_component type. | |
1065 | ||
1066 | @param[in] component | |
1067 | @parblock | |
1068 | Sink component to upcast. | |
1069 | ||
1070 | Can be \c NULL. | |
1071 | @endparblock | |
1072 | ||
1073 | @returns | |
1074 | \bt_p{component} as a common component. | |
1075 | */ | |
1076 | static inline | |
1077 | const bt_component *bt_component_sink_as_component_const( | |
4c81a2b7 | 1078 | const bt_component_sink *component) __BT_NOEXCEPT |
43c59509 PP |
1079 | { |
1080 | return __BT_UPCAST_CONST(bt_component, component); | |
1081 | } | |
1082 | ||
1083 | /*! @} */ | |
1084 | ||
1085 | /*! | |
1086 | @name Sink component port access | |
1087 | @{ | |
1088 | */ | |
1089 | ||
1090 | /*! | |
1091 | @brief | |
1092 | Returns the number of \bt_p_iport that the \bt_sink_comp | |
1093 | \bt_p{component} has. | |
1094 | ||
1095 | @param[in] component | |
1096 | Sink component of which to get the number of input ports. | |
1097 | ||
1098 | @returns | |
1099 | Number of input ports that \bt_p{component} has. | |
1100 | ||
1101 | @bt_pre_not_null{component} | |
1102 | */ | |
1103 | extern uint64_t bt_component_sink_get_input_port_count( | |
4c81a2b7 | 1104 | const bt_component_sink *component) __BT_NOEXCEPT; |
43c59509 PP |
1105 | |
1106 | /*! | |
1107 | @brief | |
1108 | Borrows the \bt_iport at index \bt_p{index} from the | |
1109 | \bt_sink_comp \bt_p{component}. | |
1110 | ||
1111 | @param[in] component | |
1112 | Sink component from which to borrow the input port at index | |
1113 | \bt_p{index}. | |
1114 | @param[in] index | |
1115 | Index of the input port to borrow from \bt_p{component}. | |
1116 | ||
1117 | @returns | |
1118 | @parblock | |
1119 | \em Borrowed reference of the input port of | |
1120 | \bt_p{component} at index \bt_p{index}. | |
1121 | ||
1122 | The returned pointer remains valid as long as \bt_p{component} | |
1123 | exists. | |
1124 | @endparblock | |
1125 | ||
1126 | @bt_pre_not_null{component} | |
1127 | @pre | |
1128 | \bt_p{index} is less than the number of input ports | |
1129 | \bt_p{component} has (as returned by | |
1130 | bt_component_sink_get_input_port_count()). | |
1131 | ||
1132 | @sa bt_component_sink_get_input_port_count() — | |
1133 | Returns the number of input ports that a sink component has. | |
1134 | */ | |
1135 | extern const bt_port_input * | |
1136 | bt_component_sink_borrow_input_port_by_index_const( | |
4c81a2b7 PP |
1137 | const bt_component_sink *component, uint64_t index) |
1138 | __BT_NOEXCEPT; | |
43c59509 PP |
1139 | |
1140 | /*! | |
1141 | @brief | |
1142 | Borrows the \bt_oport named \bt_p{name} from the \bt_sink_comp | |
1143 | \bt_p{component}. | |
1144 | ||
1145 | If \bt_p{component} has no output port named \bt_p{name}, this function | |
1146 | returns \c NULL. | |
1147 | ||
1148 | @param[in] component | |
1149 | Sink component from which to borrow the output port | |
1150 | named \bt_p{name}. | |
1151 | @param[in] name | |
1152 | Name of the output port to borrow from \bt_p{component}. | |
1153 | ||
1154 | @returns | |
1155 | @parblock | |
1156 | \em Borrowed reference of the output port of | |
1157 | \bt_p{component} named \bt_p{name}, or \c NULL if none. | |
1158 | ||
1159 | The returned pointer remains valid as long as \bt_p{component} | |
1160 | exists. | |
1161 | @endparblock | |
1162 | ||
1163 | @bt_pre_not_null{component} | |
1164 | @bt_pre_not_null{name} | |
1165 | */ | |
1166 | extern const bt_port_input * | |
1167 | bt_component_sink_borrow_input_port_by_name_const( | |
4c81a2b7 PP |
1168 | const bt_component_sink *component, const char *name) |
1169 | __BT_NOEXCEPT; | |
43c59509 PP |
1170 | |
1171 | /*! @} */ | |
1172 | ||
1173 | /*! | |
1174 | @name Sink component reference count | |
1175 | @{ | |
1176 | */ | |
1177 | ||
1178 | /*! | |
1179 | @brief | |
1180 | Increments the \ref api-fund-shared-object "reference count" of | |
1181 | the \bt_sink_comp \bt_p{component}. | |
1182 | ||
1183 | @param[in] component | |
1184 | @parblock | |
1185 | Sink component of which to increment the reference count. | |
1186 | ||
1187 | Can be \c NULL. | |
1188 | @endparblock | |
1189 | ||
1190 | @sa bt_component_sink_put_ref() — | |
1191 | Decrements the reference count of a sink component. | |
1192 | */ | |
1193 | extern void bt_component_sink_get_ref( | |
4c81a2b7 | 1194 | const bt_component_sink *component) __BT_NOEXCEPT; |
43c59509 PP |
1195 | |
1196 | /*! | |
1197 | @brief | |
1198 | Decrements the \ref api-fund-shared-object "reference count" of | |
1199 | the \bt_sink_comp \bt_p{component}. | |
1200 | ||
1201 | @param[in] component | |
1202 | @parblock | |
1203 | Sink component of which to decrement the reference count. | |
1204 | ||
1205 | Can be \c NULL. | |
1206 | @endparblock | |
1207 | ||
1208 | @sa bt_component_sink_get_ref() — | |
1209 | Increments the reference count of a sink component. | |
1210 | */ | |
1211 | extern void bt_component_sink_put_ref( | |
4c81a2b7 | 1212 | const bt_component_sink *component) __BT_NOEXCEPT; |
43c59509 PP |
1213 | |
1214 | /*! | |
1215 | @brief | |
1216 | Decrements the reference count of the \bt_sink_comp | |
1217 | \bt_p{_component}, and then sets \bt_p{_component} to \c NULL. | |
1218 | ||
1219 | @param _component | |
1220 | @parblock | |
1221 | Sink component of which to decrement the reference count. | |
1222 | ||
1223 | Can contain \c NULL. | |
1224 | @endparblock | |
1225 | ||
1226 | @bt_pre_assign_expr{_component} | |
1227 | */ | |
1228 | #define BT_COMPONENT_SINK_PUT_REF_AND_RESET(_component) \ | |
1229 | do { \ | |
1230 | bt_component_sink_put_ref(_component); \ | |
1231 | (_component) = NULL; \ | |
1232 | } while (0) | |
1233 | ||
1234 | /*! | |
1235 | @brief | |
1236 | Decrements the reference count of the \bt_sink_comp \bt_p{_dst}, | |
1237 | sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to | |
1238 | \c NULL. | |
1239 | ||
1240 | This macro effectively moves a sink component reference from the | |
1241 | expression \bt_p{_src} to the expression \bt_p{_dst}, putting the | |
1242 | existing \bt_p{_dst} reference. | |
1243 | ||
1244 | @param _dst | |
1245 | @parblock | |
1246 | Destination expression. | |
1247 | ||
1248 | Can contain \c NULL. | |
1249 | @endparblock | |
1250 | @param _src | |
1251 | @parblock | |
1252 | Source expression. | |
1253 | ||
1254 | Can contain \c NULL. | |
1255 | @endparblock | |
1256 | ||
1257 | @bt_pre_assign_expr{_dst} | |
1258 | @bt_pre_assign_expr{_src} | |
1259 | */ | |
1260 | #define BT_COMPONENT_SINK_MOVE_REF(_dst, _src) \ | |
1261 | do { \ | |
1262 | bt_component_sink_put_ref(_dst); \ | |
1263 | (_dst) = (_src); \ | |
1264 | (_src) = NULL; \ | |
1265 | } while (0) | |
1266 | ||
1267 | /*! @} */ | |
1268 | ||
1269 | /*! @} */ | |
1270 | ||
1271 | #ifdef __cplusplus | |
1272 | } | |
1273 | #endif | |
1274 | ||
1275 | #endif /* BABELTRACE2_GRAPH_COMPONENT_H */ |