include: add IWYU pragmas in private header files
[babeltrace.git] / include / babeltrace2 / graph / component.h
CommitLineData
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
21extern "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
32A <strong><em>component</em></strong> is a node within a trace
33processing \bt_graph:
34
35@image html component.png
36
37A component is \bt_comp_cls instance. Borrow the class of a
38component with bt_component_borrow_class_const(),
39bt_component_source_borrow_class_const(),
40bt_component_filter_borrow_class_const(), and
41bt_component_sink_borrow_class_const().
42
43A component is a \ref api-fund-shared-object "shared object": get a new
44reference with bt_component_get_ref() and put an existing reference with
45bt_component_put_ref().
46
47The common C&nbsp;type of a port is #bt_component.
48
49There are three types of components, which come from the three types
50of 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
134Get a component's class type enumerator with
135bt_component_get_class_type(). You can also use the
136bt_component_is_source(), bt_component_is_filter(), and
137bt_component_is_sink() helper functions.
138
139You 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
142the <code>bt_graph_add_*_component*()</code> functions. Those functions
143also return a borrowed reference of the created component through their
144\bt_p{component} parameter.
145
146<h1>Properties</h1>
147
148A 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() &mdash;
236 Returns whether or not a component is a \bt_src_comp.
237@sa bt_component_is_filter() &mdash;
238 Returns whether or not a component is a \bt_flt_comp.
239@sa bt_component_is_sink() &mdash;
240 Returns whether or not a component is a \bt_sink_comp.
241*/
242extern 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() &mdash;
259 Returns the type enumerator of a component's class.
260*/
261static inline
262bt_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() &mdash;
282 Returns the type enumerator of a component's class.
283*/
284static inline
285bt_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() &mdash;
305 Returns the type enumerator of a component's class.
306*/
307static inline
308bt_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*/
334extern 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
348See 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*/
363extern 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
370See 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*/
380extern 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() &mdash;
403 Decrements the reference count of a component.
404*/
405extern 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() &mdash;
420 Increments the reference count of a component.
421*/
422extern 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
449This 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*/
496extern const bt_component_class_source *
497bt_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*/
522static inline
523const 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*/
549extern 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() &mdash;
579 Returns the number of output ports that a source component has.
580*/
581extern const bt_port_output *
582bt_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
590If \bt_p{component} has no output port named \bt_p{name}, this function
591returns \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*/
611extern const bt_port_output *
612bt_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() &mdash;
635 Decrements the reference count of a source component.
636*/
637extern 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() &mdash;
653 Increments the reference count of a source component.
654*/
655extern 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
683This macro effectively moves a source component reference from the
684expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
685existing \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*/
730extern const bt_component_class_filter *
731bt_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*/
756static inline
757const 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*/
783extern 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() &mdash;
813 Returns the number of input ports that a filter component has.
814*/
815extern const bt_port_input *
816bt_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
824If \bt_p{component} has no input port named \bt_p{name}, this function
825returns \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*/
845extern const bt_port_input *
846bt_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*/
862extern 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() &mdash;
892 Returns the number of output ports that a filter component has.
893*/
894extern const bt_port_output *
895bt_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
903If \bt_p{component} has no output port named \bt_p{name}, this function
904returns \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*/
924extern const bt_port_output *
925bt_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() &mdash;
948 Decrements the reference count of a filter component.
949*/
950extern 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() &mdash;
966 Increments the reference count of a filter component.
967*/
968extern 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
996This macro effectively moves a filter component reference from the
997expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
998existing \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*/
1043extern const bt_component_class_sink *
1044bt_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*/
1069static inline
1070const 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*/
1096extern 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() &mdash;
1126 Returns the number of input ports that a sink component has.
1127*/
1128extern const bt_port_input *
1129bt_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
1137If \bt_p{component} has no output port named \bt_p{name}, this function
1138returns \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*/
1158extern const bt_port_input *
1159bt_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() &mdash;
1182 Decrements the reference count of a sink component.
1183*/
1184extern 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() &mdash;
1200 Increments the reference count of a sink component.
1201*/
1202extern 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
1231This macro effectively moves a sink component reference from the
1232expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
1233existing \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 */
This page took 0.084599 seconds and 4 git commands to generate.