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