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