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( | |
243 | const bt_component *component); | |
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 | |
262 | bt_bool bt_component_is_source(const bt_component *component) | |
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 | |
285 | bt_bool bt_component_is_filter(const bt_component *component) | |
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 | |
308 | bt_bool bt_component_is_sink(const bt_component *component) | |
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( | |
335 | const bt_component *component); | |
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 | */ | |
363 | extern const char *bt_component_get_name(const bt_component *component); | |
364 | ||
365 | /*! | |
366 | @brief | |
367 | Returns the logging level of the component \bt_p{component} and its | |
368 | \bt_p_msg_iter, if any. | |
369 | ||
370 | See the \ref api-comp-prop-log-lvl "logging level" property. | |
371 | ||
372 | @param[in] component | |
373 | Component of which to get the logging level. | |
374 | ||
375 | @returns | |
376 | Logging level of \bt_p{component}. | |
377 | ||
378 | @bt_pre_not_null{component} | |
379 | */ | |
380 | extern bt_logging_level bt_component_get_logging_level( | |
381 | const bt_component *component); | |
382 | ||
383 | /*! @} */ | |
384 | ||
385 | /*! | |
386 | @name Common reference count | |
387 | @{ | |
388 | */ | |
389 | ||
390 | /*! | |
391 | @brief | |
392 | Increments the \ref api-fund-shared-object "reference count" of | |
393 | the component \bt_p{component}. | |
394 | ||
395 | @param[in] component | |
396 | @parblock | |
397 | Component of which to increment the reference count. | |
398 | ||
399 | Can be \c NULL. | |
400 | @endparblock | |
401 | ||
402 | @sa bt_component_put_ref() — | |
403 | Decrements the reference count of a component. | |
404 | */ | |
405 | extern void bt_component_get_ref(const bt_component *component); | |
406 | ||
407 | /*! | |
408 | @brief | |
409 | Decrements the \ref api-fund-shared-object "reference count" of | |
410 | the component \bt_p{component}. | |
411 | ||
412 | @param[in] component | |
413 | @parblock | |
414 | Component of which to decrement the reference count. | |
415 | ||
416 | Can be \c NULL. | |
417 | @endparblock | |
418 | ||
419 | @sa bt_component_get_ref() — | |
420 | Increments the reference count of a component. | |
421 | */ | |
422 | extern void bt_component_put_ref(const bt_component *component); | |
423 | ||
424 | /*! | |
425 | @brief | |
426 | Decrements the reference count of the component | |
427 | \bt_p{_component}, and then sets \bt_p{_component} to \c NULL. | |
428 | ||
429 | @param _component | |
430 | @parblock | |
431 | Component of which to decrement the reference count. | |
432 | ||
433 | Can contain \c NULL. | |
434 | @endparblock | |
435 | ||
436 | @bt_pre_assign_expr{_component} | |
437 | */ | |
438 | #define BT_COMPONENT_PUT_REF_AND_RESET(_component) \ | |
439 | do { \ | |
440 | bt_component_put_ref(_component); \ | |
441 | (_component) = NULL; \ | |
442 | } while (0) | |
443 | ||
444 | /*! | |
445 | @brief | |
446 | Decrements the reference count of the component \bt_p{_dst}, sets | |
447 | \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL. | |
448 | ||
449 | This macro effectively moves a component reference from the expression | |
450 | \bt_p{_src} to the expression \bt_p{_dst}, putting the existing | |
451 | \bt_p{_dst} reference. | |
452 | ||
453 | @param _dst | |
454 | @parblock | |
455 | Destination expression. | |
456 | ||
457 | Can contain \c NULL. | |
458 | @endparblock | |
459 | @param _src | |
460 | @parblock | |
461 | Source expression. | |
462 | ||
463 | Can contain \c NULL. | |
464 | @endparblock | |
465 | ||
466 | @bt_pre_assign_expr{_dst} | |
467 | @bt_pre_assign_expr{_src} | |
468 | */ | |
469 | #define BT_COMPONENT_MOVE_REF(_dst, _src) \ | |
470 | do { \ | |
471 | bt_component_put_ref(_dst); \ | |
472 | (_dst) = (_src); \ | |
473 | (_src) = NULL; \ | |
474 | } while (0) | |
475 | ||
476 | /*! @} */ | |
477 | ||
478 | /*! | |
479 | @name Source component class access | |
480 | @{ | |
481 | */ | |
482 | ||
483 | /*! | |
484 | @brief | |
485 | Borrows the \ref api-comp-cls "class" of the \bt_src_comp | |
486 | \bt_p{component}. | |
487 | ||
488 | @param[in] component | |
489 | Source component of which to borrow the class. | |
490 | ||
491 | @returns | |
492 | \em Borrowed reference of the class of \bt_p{component}. | |
493 | ||
494 | @bt_pre_not_null{component} | |
495 | */ | |
496 | extern const bt_component_class_source * | |
497 | bt_component_source_borrow_class_const( | |
498 | const bt_component_source *component); | |
499 | ||
500 | /*! @} */ | |
501 | ||
502 | /*! | |
503 | @name Source component upcast | |
504 | @{ | |
505 | */ | |
506 | ||
507 | /*! | |
508 | @brief | |
509 | \ref api-fund-c-typing "Upcasts" the \bt_src_comp \bt_p{component} | |
510 | to the common #bt_component type. | |
511 | ||
512 | @param[in] component | |
513 | @parblock | |
514 | Source component to upcast. | |
515 | ||
516 | Can be \c NULL. | |
517 | @endparblock | |
518 | ||
519 | @returns | |
520 | \bt_p{component} as a common component. | |
521 | */ | |
522 | static inline | |
523 | const bt_component *bt_component_source_as_component_const( | |
524 | const bt_component_source *component) | |
525 | { | |
526 | return __BT_UPCAST_CONST(bt_component, component); | |
527 | } | |
528 | ||
529 | /*! @} */ | |
530 | ||
531 | /*! | |
532 | @name Source component port access | |
533 | @{ | |
534 | */ | |
535 | ||
536 | /*! | |
537 | @brief | |
538 | Returns the number of \bt_p_oport that the \bt_src_comp | |
539 | \bt_p{component} has. | |
540 | ||
541 | @param[in] component | |
542 | Source component of which to get the number of output ports. | |
543 | ||
544 | @returns | |
545 | Number of output ports that \bt_p{component} has. | |
546 | ||
547 | @bt_pre_not_null{component} | |
548 | */ | |
549 | extern uint64_t bt_component_source_get_output_port_count( | |
550 | const bt_component_source *component); | |
551 | ||
552 | /*! | |
553 | @brief | |
554 | Borrows the \bt_oport at index \bt_p{index} from the | |
555 | \bt_src_comp \bt_p{component}. | |
556 | ||
557 | @param[in] component | |
558 | Source component from which to borrow the output port at index | |
559 | \bt_p{index}. | |
560 | @param[in] index | |
561 | Index of the output port to borrow from \bt_p{component}. | |
562 | ||
563 | @returns | |
564 | @parblock | |
565 | \em Borrowed reference of the output port of | |
566 | \bt_p{component} at index \bt_p{index}. | |
567 | ||
568 | The returned pointer remains valid as long as \bt_p{component} | |
569 | exists. | |
570 | @endparblock | |
571 | ||
572 | @bt_pre_not_null{component} | |
573 | @pre | |
574 | \bt_p{index} is less than the number of output ports | |
575 | \bt_p{component} has (as returned by | |
576 | bt_component_source_get_output_port_count()). | |
577 | ||
578 | @sa bt_component_source_get_output_port_count() — | |
579 | Returns the number of output ports that a source component has. | |
580 | */ | |
581 | extern const bt_port_output * | |
582 | bt_component_source_borrow_output_port_by_index_const( | |
583 | const bt_component_source *component, uint64_t index); | |
584 | ||
585 | /*! | |
586 | @brief | |
587 | Borrows the \bt_oport named \bt_p{name} from the \bt_src_comp | |
588 | \bt_p{component}. | |
589 | ||
590 | If \bt_p{component} has no output port named \bt_p{name}, this function | |
591 | returns \c NULL. | |
592 | ||
593 | @param[in] component | |
594 | Source component from which to borrow the output port | |
595 | named \bt_p{name}. | |
596 | @param[in] name | |
597 | Name of the output port to borrow from \bt_p{component}. | |
598 | ||
599 | @returns | |
600 | @parblock | |
601 | \em Borrowed reference of the output port of | |
602 | \bt_p{component} named \bt_p{name}, or \c NULL if none. | |
603 | ||
604 | The returned pointer remains valid as long as \bt_p{component} | |
605 | exists. | |
606 | @endparblock | |
607 | ||
608 | @bt_pre_not_null{component} | |
609 | @bt_pre_not_null{name} | |
610 | */ | |
611 | extern const bt_port_output * | |
612 | bt_component_source_borrow_output_port_by_name_const( | |
613 | const bt_component_source *component, const char *name); | |
614 | ||
615 | /*! @} */ | |
616 | ||
617 | /*! | |
618 | @name Source component reference count | |
619 | @{ | |
620 | */ | |
621 | ||
622 | /*! | |
623 | @brief | |
624 | Increments the \ref api-fund-shared-object "reference count" of | |
625 | the \bt_src_comp \bt_p{component}. | |
626 | ||
627 | @param[in] component | |
628 | @parblock | |
629 | Source component of which to increment the reference count. | |
630 | ||
631 | Can be \c NULL. | |
632 | @endparblock | |
633 | ||
634 | @sa bt_component_source_put_ref() — | |
635 | Decrements the reference count of a source component. | |
636 | */ | |
637 | extern void bt_component_source_get_ref( | |
638 | const bt_component_source *component); | |
639 | ||
640 | /*! | |
641 | @brief | |
642 | Decrements the \ref api-fund-shared-object "reference count" of | |
643 | the \bt_src_comp \bt_p{component}. | |
644 | ||
645 | @param[in] component | |
646 | @parblock | |
647 | Source component of which to decrement the reference count. | |
648 | ||
649 | Can be \c NULL. | |
650 | @endparblock | |
651 | ||
652 | @sa bt_component_source_get_ref() — | |
653 | Increments the reference count of a source component. | |
654 | */ | |
655 | extern void bt_component_source_put_ref( | |
656 | const bt_component_source *component); | |
657 | ||
658 | /*! | |
659 | @brief | |
660 | Decrements the reference count of the \bt_src_comp | |
661 | \bt_p{_component}, and then sets \bt_p{_component} to \c NULL. | |
662 | ||
663 | @param _component | |
664 | @parblock | |
665 | Source component of which to decrement the reference count. | |
666 | ||
667 | Can contain \c NULL. | |
668 | @endparblock | |
669 | ||
670 | @bt_pre_assign_expr{_component} | |
671 | */ | |
672 | #define BT_COMPONENT_SOURCE_PUT_REF_AND_RESET(_component) \ | |
673 | do { \ | |
674 | bt_component_source_put_ref(_component); \ | |
675 | (_component) = NULL; \ | |
676 | } while (0) | |
677 | ||
678 | /*! | |
679 | @brief | |
680 | Decrements the reference count of the \bt_src_comp \bt_p{_dst}, sets | |
681 | \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL. | |
682 | ||
683 | This macro effectively moves a source component reference from the | |
684 | expression \bt_p{_src} to the expression \bt_p{_dst}, putting the | |
685 | existing \bt_p{_dst} reference. | |
686 | ||
687 | @param _dst | |
688 | @parblock | |
689 | Destination expression. | |
690 | ||
691 | Can contain \c NULL. | |
692 | @endparblock | |
693 | @param _src | |
694 | @parblock | |
695 | Source expression. | |
696 | ||
697 | Can contain \c NULL. | |
698 | @endparblock | |
699 | ||
700 | @bt_pre_assign_expr{_dst} | |
701 | @bt_pre_assign_expr{_src} | |
702 | */ | |
703 | #define BT_COMPONENT_SOURCE_MOVE_REF(_dst, _src) \ | |
704 | do { \ | |
705 | bt_component_source_put_ref(_dst); \ | |
706 | (_dst) = (_src); \ | |
707 | (_src) = NULL; \ | |
708 | } while (0) | |
709 | ||
710 | /*! @} */ | |
711 | ||
712 | /*! | |
713 | @name Filter component class access | |
714 | @{ | |
715 | */ | |
716 | ||
717 | /*! | |
718 | @brief | |
719 | Borrows the \ref api-comp-cls "class" of the \bt_flt_comp | |
720 | \bt_p{component}. | |
721 | ||
722 | @param[in] component | |
723 | Filter component of which to borrow the class. | |
724 | ||
725 | @returns | |
726 | \em Borrowed reference of the class of \bt_p{component}. | |
727 | ||
728 | @bt_pre_not_null{component} | |
729 | */ | |
730 | extern const bt_component_class_filter * | |
731 | bt_component_filter_borrow_class_const( | |
732 | const bt_component_filter *component); | |
733 | ||
734 | /*! @} */ | |
735 | ||
736 | /*! | |
737 | @name Filter component upcast | |
738 | @{ | |
739 | */ | |
740 | ||
741 | /*! | |
742 | @brief | |
743 | \ref api-fund-c-typing "Upcasts" the \bt_flt_comp \bt_p{component} | |
744 | to the common #bt_component type. | |
745 | ||
746 | @param[in] component | |
747 | @parblock | |
748 | Filter component to upcast. | |
749 | ||
750 | Can be \c NULL. | |
751 | @endparblock | |
752 | ||
753 | @returns | |
754 | \bt_p{component} as a common component. | |
755 | */ | |
756 | static inline | |
757 | const bt_component *bt_component_filter_as_component_const( | |
758 | const bt_component_filter *component) | |
759 | { | |
760 | return __BT_UPCAST_CONST(bt_component, component); | |
761 | } | |
762 | ||
763 | /*! @} */ | |
764 | ||
765 | /*! | |
766 | @name Filter component port access | |
767 | @{ | |
768 | */ | |
769 | ||
770 | /*! | |
771 | @brief | |
772 | Returns the number of \bt_p_iport that the \bt_flt_comp | |
773 | \bt_p{component} has. | |
774 | ||
775 | @param[in] component | |
776 | Filter component of which to get the number of input ports. | |
777 | ||
778 | @returns | |
779 | Number of input ports that \bt_p{component} has. | |
780 | ||
781 | @bt_pre_not_null{component} | |
782 | */ | |
783 | extern uint64_t bt_component_filter_get_input_port_count( | |
784 | const bt_component_filter *component); | |
785 | ||
786 | /*! | |
787 | @brief | |
788 | Borrows the \bt_iport at index \bt_p{index} from the | |
789 | \bt_flt_comp \bt_p{component}. | |
790 | ||
791 | @param[in] component | |
792 | Filter component from which to borrow the input port at index | |
793 | \bt_p{index}. | |
794 | @param[in] index | |
795 | Index of the input port to borrow from \bt_p{component}. | |
796 | ||
797 | @returns | |
798 | @parblock | |
799 | \em Borrowed reference of the input port of | |
800 | \bt_p{component} at index \bt_p{index}. | |
801 | ||
802 | The returned pointer remains valid as long as \bt_p{component} | |
803 | exists. | |
804 | @endparblock | |
805 | ||
806 | @bt_pre_not_null{component} | |
807 | @pre | |
808 | \bt_p{index} is less than the number of input ports | |
809 | \bt_p{component} has (as returned by | |
810 | bt_component_filter_get_input_port_count()). | |
811 | ||
812 | @sa bt_component_filter_get_input_port_count() — | |
813 | Returns the number of input ports that a filter component has. | |
814 | */ | |
815 | extern const bt_port_input * | |
816 | bt_component_filter_borrow_input_port_by_index_const( | |
817 | const bt_component_filter *component, uint64_t index); | |
818 | ||
819 | /*! | |
820 | @brief | |
821 | Borrows the \bt_iport named \bt_p{name} from the \bt_flt_comp | |
822 | \bt_p{component}. | |
823 | ||
824 | If \bt_p{component} has no input port named \bt_p{name}, this function | |
825 | returns \c NULL. | |
826 | ||
827 | @param[in] component | |
828 | Filter component from which to borrow the input port | |
829 | named \bt_p{name}. | |
830 | @param[in] name | |
831 | Name of the input port to borrow from \bt_p{component}. | |
832 | ||
833 | @returns | |
834 | @parblock | |
835 | \em Borrowed reference of the input port of | |
836 | \bt_p{component} named \bt_p{name}, or \c NULL if none. | |
837 | ||
838 | The returned pointer remains valid as long as \bt_p{component} | |
839 | exists. | |
840 | @endparblock | |
841 | ||
842 | @bt_pre_not_null{component} | |
843 | @bt_pre_not_null{name} | |
844 | */ | |
845 | extern const bt_port_input * | |
846 | bt_component_filter_borrow_input_port_by_name_const( | |
847 | const bt_component_filter *component, const char *name); | |
848 | ||
849 | /*! | |
850 | @brief | |
851 | Returns the number of \bt_p_oport that the \bt_flt_comp | |
852 | \bt_p{component} has. | |
853 | ||
854 | @param[in] component | |
855 | Filter component of which to get the number of output ports. | |
856 | ||
857 | @returns | |
858 | Number of output ports that \bt_p{component} has. | |
859 | ||
860 | @bt_pre_not_null{component} | |
861 | */ | |
862 | extern uint64_t bt_component_filter_get_output_port_count( | |
863 | const bt_component_filter *component); | |
864 | ||
865 | /*! | |
866 | @brief | |
867 | Borrows the \bt_oport at index \bt_p{index} from the | |
868 | \bt_flt_comp \bt_p{component}. | |
869 | ||
870 | @param[in] component | |
871 | Filter component from which to borrow the output port at index | |
872 | \bt_p{index}. | |
873 | @param[in] index | |
874 | Index of the output port to borrow from \bt_p{component}. | |
875 | ||
876 | @returns | |
877 | @parblock | |
878 | \em Borrowed reference of the output port of | |
879 | \bt_p{component} at index \bt_p{index}. | |
880 | ||
881 | The returned pointer remains valid as long as \bt_p{component} | |
882 | exists. | |
883 | @endparblock | |
884 | ||
885 | @bt_pre_not_null{component} | |
886 | @pre | |
887 | \bt_p{index} is less than the number of output ports | |
888 | \bt_p{component} has (as returned by | |
889 | bt_component_filter_get_output_port_count()). | |
890 | ||
891 | @sa bt_component_filter_get_output_port_count() — | |
892 | Returns the number of output ports that a filter component has. | |
893 | */ | |
894 | extern const bt_port_output * | |
895 | bt_component_filter_borrow_output_port_by_index_const( | |
896 | const bt_component_filter *component, uint64_t index); | |
897 | ||
898 | /*! | |
899 | @brief | |
900 | Borrows the \bt_oport named \bt_p{name} from the \bt_flt_comp | |
901 | \bt_p{component}. | |
902 | ||
903 | If \bt_p{component} has no output port named \bt_p{name}, this function | |
904 | returns \c NULL. | |
905 | ||
906 | @param[in] component | |
907 | Filter component from which to borrow the output port | |
908 | named \bt_p{name}. | |
909 | @param[in] name | |
910 | Name of the output port to borrow from \bt_p{component}. | |
911 | ||
912 | @returns | |
913 | @parblock | |
914 | \em Borrowed reference of the output port of | |
915 | \bt_p{component} named \bt_p{name}, or \c NULL if none. | |
916 | ||
917 | The returned pointer remains valid as long as \bt_p{component} | |
918 | exists. | |
919 | @endparblock | |
920 | ||
921 | @bt_pre_not_null{component} | |
922 | @bt_pre_not_null{name} | |
923 | */ | |
924 | extern const bt_port_output * | |
925 | bt_component_filter_borrow_output_port_by_name_const( | |
926 | const bt_component_filter *component, const char *name); | |
927 | ||
928 | /*! @} */ | |
929 | ||
930 | /*! | |
931 | @name Filter component reference count | |
932 | @{ | |
933 | */ | |
934 | ||
935 | /*! | |
936 | @brief | |
937 | Increments the \ref api-fund-shared-object "reference count" of | |
938 | the \bt_flt_comp \bt_p{component}. | |
939 | ||
940 | @param[in] component | |
941 | @parblock | |
942 | Filter component of which to increment the reference count. | |
943 | ||
944 | Can be \c NULL. | |
945 | @endparblock | |
946 | ||
947 | @sa bt_component_filter_put_ref() — | |
948 | Decrements the reference count of a filter component. | |
949 | */ | |
950 | extern void bt_component_filter_get_ref( | |
951 | const bt_component_filter *component); | |
952 | ||
953 | /*! | |
954 | @brief | |
955 | Decrements the \ref api-fund-shared-object "reference count" of | |
956 | the \bt_flt_comp \bt_p{component}. | |
957 | ||
958 | @param[in] component | |
959 | @parblock | |
960 | Filter component of which to decrement the reference count. | |
961 | ||
962 | Can be \c NULL. | |
963 | @endparblock | |
964 | ||
965 | @sa bt_component_filter_get_ref() — | |
966 | Increments the reference count of a filter component. | |
967 | */ | |
968 | extern void bt_component_filter_put_ref( | |
969 | const bt_component_filter *component); | |
970 | ||
971 | /*! | |
972 | @brief | |
973 | Decrements the reference count of the \bt_flt_comp | |
974 | \bt_p{_component}, and then sets \bt_p{_component} to \c NULL. | |
975 | ||
976 | @param _component | |
977 | @parblock | |
978 | Filter component of which to decrement the reference count. | |
979 | ||
980 | Can contain \c NULL. | |
981 | @endparblock | |
982 | ||
983 | @bt_pre_assign_expr{_component} | |
984 | */ | |
985 | #define BT_COMPONENT_FILTER_PUT_REF_AND_RESET(_component) \ | |
986 | do { \ | |
987 | bt_component_filter_put_ref(_component); \ | |
988 | (_component) = NULL; \ | |
989 | } while (0) | |
990 | ||
991 | /*! | |
992 | @brief | |
993 | Decrements the reference count of the \bt_flt_comp \bt_p{_dst}, sets | |
994 | \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL. | |
995 | ||
996 | This macro effectively moves a filter component reference from the | |
997 | expression \bt_p{_src} to the expression \bt_p{_dst}, putting the | |
998 | existing \bt_p{_dst} reference. | |
999 | ||
1000 | @param _dst | |
1001 | @parblock | |
1002 | Destination expression. | |
1003 | ||
1004 | Can contain \c NULL. | |
1005 | @endparblock | |
1006 | @param _src | |
1007 | @parblock | |
1008 | Source expression. | |
1009 | ||
1010 | Can contain \c NULL. | |
1011 | @endparblock | |
1012 | ||
1013 | @bt_pre_assign_expr{_dst} | |
1014 | @bt_pre_assign_expr{_src} | |
1015 | */ | |
1016 | #define BT_COMPONENT_FILTER_MOVE_REF(_dst, _src) \ | |
1017 | do { \ | |
1018 | bt_component_filter_put_ref(_dst); \ | |
1019 | (_dst) = (_src); \ | |
1020 | (_src) = NULL; \ | |
1021 | } while (0) | |
1022 | ||
1023 | /*! @} */ | |
1024 | ||
1025 | /*! | |
1026 | @name Sink component class access | |
1027 | @{ | |
1028 | */ | |
1029 | ||
1030 | /*! | |
1031 | @brief | |
1032 | Borrows the \ref api-comp-cls "class" of the \bt_sink_comp | |
1033 | \bt_p{component}. | |
1034 | ||
1035 | @param[in] component | |
1036 | Sink component of which to borrow the class. | |
1037 | ||
1038 | @returns | |
1039 | \em Borrowed reference of the class of \bt_p{component}. | |
1040 | ||
1041 | @bt_pre_not_null{component} | |
1042 | */ | |
1043 | extern const bt_component_class_sink * | |
1044 | bt_component_sink_borrow_class_const( | |
1045 | const bt_component_sink *component); | |
1046 | ||
1047 | /*! @} */ | |
1048 | ||
1049 | /*! | |
1050 | @name Sink component upcast | |
1051 | @{ | |
1052 | */ | |
1053 | ||
1054 | /*! | |
1055 | @brief | |
1056 | \ref api-fund-c-typing "Upcasts" the \bt_sink_comp \bt_p{component} | |
1057 | to the common #bt_component type. | |
1058 | ||
1059 | @param[in] component | |
1060 | @parblock | |
1061 | Sink component to upcast. | |
1062 | ||
1063 | Can be \c NULL. | |
1064 | @endparblock | |
1065 | ||
1066 | @returns | |
1067 | \bt_p{component} as a common component. | |
1068 | */ | |
1069 | static inline | |
1070 | const bt_component *bt_component_sink_as_component_const( | |
1071 | const bt_component_sink *component) | |
1072 | { | |
1073 | return __BT_UPCAST_CONST(bt_component, component); | |
1074 | } | |
1075 | ||
1076 | /*! @} */ | |
1077 | ||
1078 | /*! | |
1079 | @name Sink component port access | |
1080 | @{ | |
1081 | */ | |
1082 | ||
1083 | /*! | |
1084 | @brief | |
1085 | Returns the number of \bt_p_iport that the \bt_sink_comp | |
1086 | \bt_p{component} has. | |
1087 | ||
1088 | @param[in] component | |
1089 | Sink component of which to get the number of input ports. | |
1090 | ||
1091 | @returns | |
1092 | Number of input ports that \bt_p{component} has. | |
1093 | ||
1094 | @bt_pre_not_null{component} | |
1095 | */ | |
1096 | extern uint64_t bt_component_sink_get_input_port_count( | |
1097 | const bt_component_sink *component); | |
1098 | ||
1099 | /*! | |
1100 | @brief | |
1101 | Borrows the \bt_iport at index \bt_p{index} from the | |
1102 | \bt_sink_comp \bt_p{component}. | |
1103 | ||
1104 | @param[in] component | |
1105 | Sink component from which to borrow the input port at index | |
1106 | \bt_p{index}. | |
1107 | @param[in] index | |
1108 | Index of the input port to borrow from \bt_p{component}. | |
1109 | ||
1110 | @returns | |
1111 | @parblock | |
1112 | \em Borrowed reference of the input port of | |
1113 | \bt_p{component} at index \bt_p{index}. | |
1114 | ||
1115 | The returned pointer remains valid as long as \bt_p{component} | |
1116 | exists. | |
1117 | @endparblock | |
1118 | ||
1119 | @bt_pre_not_null{component} | |
1120 | @pre | |
1121 | \bt_p{index} is less than the number of input ports | |
1122 | \bt_p{component} has (as returned by | |
1123 | bt_component_sink_get_input_port_count()). | |
1124 | ||
1125 | @sa bt_component_sink_get_input_port_count() — | |
1126 | Returns the number of input ports that a sink component has. | |
1127 | */ | |
1128 | extern const bt_port_input * | |
1129 | bt_component_sink_borrow_input_port_by_index_const( | |
1130 | const bt_component_sink *component, uint64_t index); | |
1131 | ||
1132 | /*! | |
1133 | @brief | |
1134 | Borrows the \bt_oport named \bt_p{name} from the \bt_sink_comp | |
1135 | \bt_p{component}. | |
1136 | ||
1137 | If \bt_p{component} has no output port named \bt_p{name}, this function | |
1138 | returns \c NULL. | |
1139 | ||
1140 | @param[in] component | |
1141 | Sink component from which to borrow the output port | |
1142 | named \bt_p{name}. | |
1143 | @param[in] name | |
1144 | Name of the output port to borrow from \bt_p{component}. | |
1145 | ||
1146 | @returns | |
1147 | @parblock | |
1148 | \em Borrowed reference of the output port of | |
1149 | \bt_p{component} named \bt_p{name}, or \c NULL if none. | |
1150 | ||
1151 | The returned pointer remains valid as long as \bt_p{component} | |
1152 | exists. | |
1153 | @endparblock | |
1154 | ||
1155 | @bt_pre_not_null{component} | |
1156 | @bt_pre_not_null{name} | |
1157 | */ | |
1158 | extern const bt_port_input * | |
1159 | bt_component_sink_borrow_input_port_by_name_const( | |
1160 | const bt_component_sink *component, const char *name); | |
1161 | ||
1162 | /*! @} */ | |
1163 | ||
1164 | /*! | |
1165 | @name Sink component reference count | |
1166 | @{ | |
1167 | */ | |
1168 | ||
1169 | /*! | |
1170 | @brief | |
1171 | Increments the \ref api-fund-shared-object "reference count" of | |
1172 | the \bt_sink_comp \bt_p{component}. | |
1173 | ||
1174 | @param[in] component | |
1175 | @parblock | |
1176 | Sink component of which to increment the reference count. | |
1177 | ||
1178 | Can be \c NULL. | |
1179 | @endparblock | |
1180 | ||
1181 | @sa bt_component_sink_put_ref() — | |
1182 | Decrements the reference count of a sink component. | |
1183 | */ | |
1184 | extern void bt_component_sink_get_ref( | |
1185 | const bt_component_sink *component); | |
1186 | ||
1187 | /*! | |
1188 | @brief | |
1189 | Decrements the \ref api-fund-shared-object "reference count" of | |
1190 | the \bt_sink_comp \bt_p{component}. | |
1191 | ||
1192 | @param[in] component | |
1193 | @parblock | |
1194 | Sink component of which to decrement the reference count. | |
1195 | ||
1196 | Can be \c NULL. | |
1197 | @endparblock | |
1198 | ||
1199 | @sa bt_component_sink_get_ref() — | |
1200 | Increments the reference count of a sink component. | |
1201 | */ | |
1202 | extern void bt_component_sink_put_ref( | |
1203 | const bt_component_sink *component); | |
1204 | ||
1205 | /*! | |
1206 | @brief | |
1207 | Decrements the reference count of the \bt_sink_comp | |
1208 | \bt_p{_component}, and then sets \bt_p{_component} to \c NULL. | |
1209 | ||
1210 | @param _component | |
1211 | @parblock | |
1212 | Sink component of which to decrement the reference count. | |
1213 | ||
1214 | Can contain \c NULL. | |
1215 | @endparblock | |
1216 | ||
1217 | @bt_pre_assign_expr{_component} | |
1218 | */ | |
1219 | #define BT_COMPONENT_SINK_PUT_REF_AND_RESET(_component) \ | |
1220 | do { \ | |
1221 | bt_component_sink_put_ref(_component); \ | |
1222 | (_component) = NULL; \ | |
1223 | } while (0) | |
1224 | ||
1225 | /*! | |
1226 | @brief | |
1227 | Decrements the reference count of the \bt_sink_comp \bt_p{_dst}, | |
1228 | sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to | |
1229 | \c NULL. | |
1230 | ||
1231 | This macro effectively moves a sink component reference from the | |
1232 | expression \bt_p{_src} to the expression \bt_p{_dst}, putting the | |
1233 | existing \bt_p{_dst} reference. | |
1234 | ||
1235 | @param _dst | |
1236 | @parblock | |
1237 | Destination expression. | |
1238 | ||
1239 | Can contain \c NULL. | |
1240 | @endparblock | |
1241 | @param _src | |
1242 | @parblock | |
1243 | Source expression. | |
1244 | ||
1245 | Can contain \c NULL. | |
1246 | @endparblock | |
1247 | ||
1248 | @bt_pre_assign_expr{_dst} | |
1249 | @bt_pre_assign_expr{_src} | |
1250 | */ | |
1251 | #define BT_COMPONENT_SINK_MOVE_REF(_dst, _src) \ | |
1252 | do { \ | |
1253 | bt_component_sink_put_ref(_dst); \ | |
1254 | (_dst) = (_src); \ | |
1255 | (_src) = NULL; \ | |
1256 | } while (0) | |
1257 | ||
1258 | /*! @} */ | |
1259 | ||
1260 | /*! @} */ | |
1261 | ||
1262 | #ifdef __cplusplus | |
1263 | } | |
1264 | #endif | |
1265 | ||
1266 | #endif /* BABELTRACE2_GRAPH_COMPONENT_H */ |