2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_GRAPH_SELF_COMPONENT_H
8 #define BABELTRACE2_GRAPH_SELF_COMPONENT_H
10 #ifndef __BT_IN_BABELTRACE_H
11 # error "Please include <babeltrace2/babeltrace.h> instead."
14 #include <babeltrace2/types.h>
21 @defgroup api-self-comp Self components
22 @ingroup api-comp-cls-dev
25 Private views of \bt_p_comp for instance methods.
27 The #bt_self_component, #bt_self_component_source,
28 #bt_self_component_filter, #bt_self_component_sink types are
29 private views of a \bt_comp from within a component class
30 \ref api-comp-cls-dev-instance-meth "instance method".
32 Add a \bt_port to a component with
33 bt_self_component_source_add_output_port(),
34 bt_self_component_filter_add_input_port(),
35 bt_self_component_filter_add_output_port(), and
36 bt_self_component_sink_add_input_port().
38 When you add a port to a component, you can attach custom user data
39 to it (\bt_voidp). You can retrieve this user data
40 afterwards with bt_self_component_port_get_data().
42 Borrow a \bt_self_comp_port from a component by index with
43 bt_self_component_source_borrow_output_port_by_index(),
44 bt_self_component_filter_borrow_input_port_by_index(),
45 bt_self_component_filter_borrow_output_port_by_index(), and
46 bt_self_component_sink_borrow_input_port_by_index().
48 Borrow a \bt_self_comp_port from a component by name with
49 bt_self_component_source_borrow_output_port_by_name(),
50 bt_self_component_filter_borrow_input_port_by_name(),
51 bt_self_component_filter_borrow_output_port_by_name(), and
52 bt_self_component_sink_borrow_input_port_by_name().
54 Set and get user data attached to a component with
55 bt_self_component_set_data() and bt_self_component_get_data().
57 Get a component's owning trace processing \bt_graph's effective
58 \bt_mip version with bt_self_component_get_graph_mip_version().
60 Check whether or not a \bt_sink_comp is interrupted with
61 bt_self_component_sink_is_interrupted().
63 \ref api-fund-c-typing "Upcast" the "self" (private) types to the
64 public and common self component types with the
65 <code>bt_self_component*_as_component*()</code> and
66 <code>bt_self_component_*_as_self_component()</code> functions.
75 @typedef struct bt_self_component bt_self_component;
80 @typedef struct bt_self_component_source bt_self_component_source;
85 @typedef struct bt_self_component_filter bt_self_component_filter;
90 @typedef struct bt_self_component_sink bt_self_component_sink;
95 @typedef struct bt_self_component_source_configuration bt_self_component_source_configuration;
98 Self \bt_src_comp configuration.
100 @typedef struct bt_self_component_filter_configuration bt_self_component_filter_configuration;
103 Self \bt_flt_comp configuration.
105 @typedef struct bt_self_component_sink_configuration bt_self_component_sink_configuration;
108 Self \bt_sink_comp configuration.
120 Status codes for bt_self_component_source_add_output_port(),
121 bt_self_component_filter_add_input_port(),
122 bt_self_component_filter_add_output_port(), and
123 bt_self_component_sink_add_input_port().
125 typedef enum bt_self_component_add_port_status
{
130 BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
= __BT_FUNC_STATUS_OK
,
136 BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
142 BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
143 } bt_self_component_add_port_status
;
147 Adds an \bt_oport named \bt_p{name} and having the user data
148 \bt_p{user_data} to the \bt_src_comp \bt_p{self_component},
149 and sets \bt_p{*self_component_port} to the resulting port.
152 You can only call this function from within the
153 \ref api-comp-cls-dev-meth-init "initialization",
154 \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
156 \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
159 @param[in] self_component
160 Source component instance.
162 Name of the output port to add to \bt_p{self_component} (copied).
164 User data of the output port to add to \bt_p{self_component}.
165 @param[out] self_component_port
166 <strong>On success, if not \c NULL</strong>,
167 \bt_p{*self_component_port} is a \em borrowed reference of the
170 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
172 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
174 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
177 @bt_pre_not_null{self_component}
178 @bt_pre_not_null{name}
180 No other output port within \bt_p{self_component} has the name
183 extern bt_self_component_add_port_status
184 bt_self_component_source_add_output_port(
185 bt_self_component_source
*self_component
,
186 const char *name
, void *user_data
,
187 bt_self_component_port_output
**self_component_port
);
191 Adds an \bt_iport named \bt_p{name} and having the user data
192 \bt_p{user_data} to the \bt_flt_comp \bt_p{self_component},
193 and sets \bt_p{*self_component_port} to the resulting port.
196 You can only call this function from within the
197 \ref api-comp-cls-dev-meth-init "initialization",
198 \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
200 \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
203 @param[in] self_component
204 Filter component instance.
206 Name of the input port to add to \bt_p{self_component} (copied).
208 User data of the input port to add to \bt_p{self_component}.
209 @param[out] self_component_port
210 <strong>On success, if not \c NULL</strong>,
211 \bt_p{*self_component_port} is a \em borrowed reference of the
214 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
216 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
218 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
221 @bt_pre_not_null{self_component}
222 @bt_pre_not_null{name}
224 No other input port within \bt_p{self_component} has the name
227 extern bt_self_component_add_port_status
228 bt_self_component_filter_add_input_port(
229 bt_self_component_filter
*self_component
,
230 const char *name
, void *user_data
,
231 bt_self_component_port_input
**self_component_port
);
235 Adds an \bt_oport named \bt_p{name} and having the user data
236 \bt_p{user_data} to the \bt_flt_comp \bt_p{self_component},
237 and sets \bt_p{*self_component_port} to the resulting port.
240 You can only call this function from within the
241 \ref api-comp-cls-dev-meth-init "initialization",
242 \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
244 \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
247 @param[in] self_component
248 Filter component instance.
250 Name of the output port to add to \bt_p{self_component} (copied).
252 User data of the output port to add to \bt_p{self_component}.
253 @param[out] self_component_port
254 <strong>On success, if not \c NULL</strong>,
255 \bt_p{*self_component_port} is a \em borrowed reference of the
258 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
260 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
262 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
265 @bt_pre_not_null{self_component}
266 @bt_pre_not_null{name}
268 No other output port within \bt_p{self_component} has the name
271 extern bt_self_component_add_port_status
272 bt_self_component_filter_add_output_port(
273 bt_self_component_filter
*self_component
,
274 const char *name
, void *user_data
,
275 bt_self_component_port_output
**self_component_port
);
279 Adds an \bt_iport named \bt_p{name} and having the user data
280 \bt_p{user_data} to the \bt_sink_comp \bt_p{self_component},
281 and sets \bt_p{*self_component_port} to the resulting port.
284 You can only call this function from within the
285 \ref api-comp-cls-dev-meth-init "initialization",
286 \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
288 \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
291 @param[in] self_component
292 Sink component instance.
294 Name of the input port to add to \bt_p{self_component} (copied).
296 User data of the input port to add to \bt_p{self_component}.
297 @param[out] self_component_port
298 <strong>On success, if not \c NULL</strong>,
299 \bt_p{*self_component_port} is a \em borrowed reference of the
302 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
304 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
306 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
309 @bt_pre_not_null{self_component}
310 @bt_pre_not_null{name}
312 No other input port within \bt_p{self_component} has the name
316 extern bt_self_component_add_port_status
317 bt_self_component_sink_add_input_port(
318 bt_self_component_sink
*self_component
,
319 const char *name
, void *user_data
,
320 bt_self_component_port_input
**self_component_port
);
331 Borrows the \bt_self_comp_oport at index \bt_p{index} from the
332 \bt_src_comp \bt_p{self_component}.
334 @param[in] self_component
335 Source component instance.
337 Index of the output port to borrow from \bt_p{self_component}.
341 \em Borrowed reference of the output port of
342 \bt_p{self_component} at index \bt_p{index}.
344 The returned pointer remains valid as long as \bt_p{self_component}
348 @bt_pre_not_null{self_component}
350 \bt_p{index} is less than the number of output ports
351 \bt_p{self_component} has (as returned by
352 bt_component_source_get_output_port_count()).
354 @sa bt_component_source_get_output_port_count() —
355 Returns the number of output ports that a source component has.
357 extern bt_self_component_port_output
*
358 bt_self_component_source_borrow_output_port_by_index(
359 bt_self_component_source
*self_component
,
364 Borrows the \bt_self_comp_iport at index \bt_p{index} from the
365 \bt_flt_comp \bt_p{self_component}.
367 @param[in] self_component
368 Filter component instance.
370 Index of the input port to borrow from \bt_p{self_component}.
374 \em Borrowed reference of the input port of
375 \bt_p{self_component} at index \bt_p{index}.
377 The returned pointer remains valid as long as \bt_p{self_component}
381 @bt_pre_not_null{self_component}
383 \bt_p{index} is less than the number of input ports
384 \bt_p{self_component} has (as returned by
385 bt_component_filter_get_input_port_count()).
387 @sa bt_component_filter_get_input_port_count() —
388 Returns the number of input ports that a filter component has.
390 extern bt_self_component_port_input
*
391 bt_self_component_filter_borrow_input_port_by_index(
392 bt_self_component_filter
*self_component
,
397 Borrows the \bt_self_comp_oport at index \bt_p{index} from the
398 \bt_flt_comp \bt_p{self_component}.
400 @param[in] self_component
401 Filter component instance.
403 Index of the output port to borrow from \bt_p{self_component}.
407 \em Borrowed reference of the output port of
408 \bt_p{self_component} at index \bt_p{index}.
410 The returned pointer remains valid as long as \bt_p{self_component}
414 @bt_pre_not_null{self_component}
416 \bt_p{index} is less than the number of output ports
417 \bt_p{self_component} has (as returned by
418 bt_component_filter_get_output_port_count()).
420 @sa bt_component_filter_get_output_port_count() —
421 Returns the number of output ports that a filter component has.
423 extern bt_self_component_port_output
*
424 bt_self_component_filter_borrow_output_port_by_index(
425 bt_self_component_filter
*self_component
,
430 Borrows the \bt_self_comp_iport at index \bt_p{index} from the
431 \bt_sink_comp \bt_p{self_component}.
433 @param[in] self_component
434 Sink component instance.
436 Index of the input port to borrow from \bt_p{self_component}.
440 \em Borrowed reference of the input port of
441 \bt_p{self_component} at index \bt_p{index}.
443 The returned pointer remains valid as long as \bt_p{self_component}
447 @bt_pre_not_null{self_component}
449 \bt_p{index} is less than the number of input ports
450 \bt_p{self_component} has (as returned by
451 bt_component_sink_get_input_port_count()).
453 @sa bt_component_sink_get_input_port_count() —
454 Returns the number of input ports that a sink component has.
456 extern bt_self_component_port_input
*
457 bt_self_component_sink_borrow_input_port_by_index(
458 bt_self_component_sink
*self_component
, uint64_t index
);
462 Borrows the \bt_self_comp_oport named \bt_p{name} from the
463 \bt_src_comp \bt_p{self_component}.
465 If \bt_p{self_component} has no output port named \bt_p{name}, this
466 function returns \c NULL.
468 @param[in] self_component
469 Source component instance.
471 Name of the output port to borrow from \bt_p{self_component}.
475 \em Borrowed reference of the output port of
476 \bt_p{self_component} named \bt_p{name}, or \c NULL if none.
478 The returned pointer remains valid as long as \bt_p{self_component}
482 @bt_pre_not_null{self_component}
483 @bt_pre_not_null{name}
485 extern bt_self_component_port_output
*
486 bt_self_component_source_borrow_output_port_by_name(
487 bt_self_component_source
*self_component
,
492 Borrows the \bt_self_comp_iport named \bt_p{name} from the
493 \bt_flt_comp \bt_p{self_component}.
495 If \bt_p{self_component} has no input port named \bt_p{name}, this
496 function returns \c NULL.
498 @param[in] self_component
499 Filter component instance.
501 Name of the input port to borrow from \bt_p{self_component}.
505 \em Borrowed reference of the input port of
506 \bt_p{self_component} named \bt_p{name}, or \c NULL if none.
508 The returned pointer remains valid as long as \bt_p{self_component}
512 @bt_pre_not_null{self_component}
513 @bt_pre_not_null{name}
515 extern bt_self_component_port_input
*
516 bt_self_component_filter_borrow_input_port_by_name(
517 bt_self_component_filter
*self_component
,
522 Borrows the \bt_self_comp_oport named \bt_p{name} from the
523 \bt_flt_comp \bt_p{self_component}.
525 If \bt_p{self_component} has no output port named \bt_p{name}, this
526 function returns \c NULL.
528 @param[in] self_component
529 Filter component instance.
531 Name of the output port to borrow from \bt_p{self_component}.
535 \em Borrowed reference of the output port of
536 \bt_p{self_component} named \bt_p{name}, or \c NULL if none.
538 The returned pointer remains valid as long as \bt_p{self_component}
542 @bt_pre_not_null{self_component}
543 @bt_pre_not_null{name}
545 extern bt_self_component_port_output
*
546 bt_self_component_filter_borrow_output_port_by_name(
547 bt_self_component_filter
*self_component
,
552 Borrows the \bt_self_comp_iport named \bt_p{name} from the
553 \bt_sink_comp \bt_p{self_component}.
555 If \bt_p{self_component} has no input port named \bt_p{name}, this
556 function returns \c NULL.
558 @param[in] self_component
559 Sink component instance.
561 Name of the input port to borrow from \bt_p{self_component}.
565 \em Borrowed reference of the input port of
566 \bt_p{self_component} named \bt_p{name}, or \c NULL if none.
568 The returned pointer remains valid as long as \bt_p{self_component}
572 @bt_pre_not_null{self_component}
573 @bt_pre_not_null{name}
575 extern bt_self_component_port_input
*
576 bt_self_component_sink_borrow_input_port_by_name(
577 bt_self_component_sink
*self_component
,
589 Sets the user data of the \bt_comp \bt_p{self_component} to
592 @param[in] self_component
595 New user data of \bt_p{self_component}.
597 @bt_pre_not_null{self_component}
599 @sa bt_self_component_get_data() —
600 Returns the user data of a component.
602 extern void bt_self_component_set_data(
603 bt_self_component
*self_component
, void *user_data
);
607 Returns the user data of the \bt_comp \bt_p{self_component}.
609 @param[in] self_component
613 User data of \bt_p{self_component}.
615 @bt_pre_not_null{self_component}
617 @sa bt_self_component_set_data() —
618 Sets the user data of a component.
620 extern void *bt_self_component_get_data(
621 const bt_self_component
*self_component
);
626 @name Trace processing graph's effective MIP version access
632 Returns the effective \bt_mip (MIP) version of the trace processing
633 \bt_graph which contains the \bt_comp \bt_p{self_component}.
636 As of \bt_name_version_min_maj, because bt_get_maximal_mip_version()
637 returns 0, this function always returns 0.
639 @param[in] self_component
643 Effective MIP version of the trace processing graph which
644 contains \bt_p{self_component}.
646 @bt_pre_not_null{self_component}
649 uint64_t bt_self_component_get_graph_mip_version(
650 bt_self_component
*self_component
);
655 @name Sink component's interruption query
661 Returns whether or not the \bt_sink_comp \bt_p{self_component}
662 is interrupted, that is, whether or not any of its \bt_p_intr
665 @param[in] self_component
669 #BT_TRUE if \bt_p{self_component} is interrupted (any of its
670 interrupters is set).
672 @bt_pre_not_null{self_component}
674 @sa bt_graph_borrow_default_interrupter() —
675 Borrows a trace processing graph's default interrupter.
676 @sa bt_graph_add_interrupter() —
677 Adds an interrupter to a graph.
679 extern bt_bool
bt_self_component_sink_is_interrupted(
680 const bt_self_component_sink
*self_component
);
685 @name Self to public upcast
691 \ref api-fund-c-typing "Upcasts" the self \bt_comp
692 \bt_p{self_component} to the public #bt_component type.
694 @param[in] self_component
702 \bt_p{self_component} as a public component.
705 const bt_component
*bt_self_component_as_component(
706 bt_self_component
*self_component
)
708 return __BT_UPCAST(bt_component
, self_component
);
713 \ref api-fund-c-typing "Upcasts" the self \bt_src_comp
714 \bt_p{self_component} to the public #bt_component_source
717 @param[in] self_component
719 Source component to upcast.
725 \bt_p{self_component} as a public source component.
728 const bt_component_source
*
729 bt_self_component_source_as_component_source(
730 bt_self_component_source
*self_component
)
732 return __BT_UPCAST_CONST(bt_component_source
, self_component
);
737 \ref api-fund-c-typing "Upcasts" the self \bt_flt_comp
738 \bt_p{self_component} to the public #bt_component_filter
741 @param[in] self_component
743 Filter component to upcast.
749 \bt_p{self_component} as a public filter component.
752 const bt_component_filter
*
753 bt_self_component_filter_as_component_filter(
754 bt_self_component_filter
*self_component
)
756 return __BT_UPCAST_CONST(bt_component_filter
, self_component
);
761 \ref api-fund-c-typing "Upcasts" the self \bt_sink_comp
762 \bt_p{self_component} to the public #bt_component_sink
765 @param[in] self_component
767 Sink component to upcast.
773 \bt_p{self_component} as a public sink component.
776 const bt_component_sink
*
777 bt_self_component_sink_as_component_sink(
778 bt_self_component_sink
*self_component
)
780 return __BT_UPCAST_CONST(bt_component_sink
, self_component
);
786 @name Self to common self upcast
792 \ref api-fund-c-typing "Upcasts" the self \bt_src_comp
793 \bt_p{self_component} to the common #bt_self_component
796 @param[in] self_component
798 Source component to upcast.
804 \bt_p{self_component} as a common self component.
807 bt_self_component
*bt_self_component_source_as_self_component(
808 bt_self_component_source
*self_component
)
810 return __BT_UPCAST(bt_self_component
, self_component
);
815 \ref api-fund-c-typing "Upcasts" the self \bt_flt_comp
816 \bt_p{self_component} to the common #bt_self_component
819 @param[in] self_component
821 Filter component to upcast.
827 \bt_p{self_component} as a common self component.
830 bt_self_component
*bt_self_component_filter_as_self_component(
831 bt_self_component_filter
*self_component
)
833 return __BT_UPCAST(bt_self_component
, self_component
);
838 \ref api-fund-c-typing "Upcasts" the self \bt_sink_comp
839 \bt_p{self_component} to the common #bt_self_component
842 @param[in] self_component
844 Sink component to upcast.
850 \bt_p{self_component} as a common self component.
853 bt_self_component
*bt_self_component_sink_as_self_component(
854 bt_self_component_sink
*self_component
)
856 return __BT_UPCAST(bt_self_component
, self_component
);
867 #endif /* BABELTRACE2_GRAPH_SELF_COMPONENT_H */