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 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
16 #include <babeltrace2/types.h>
23 @defgroup api-self-comp Self components
24 @ingroup api-comp-cls-dev
27 Private views of \bt_p_comp for instance methods.
29 The #bt_self_component, #bt_self_component_source,
30 #bt_self_component_filter, #bt_self_component_sink types are
31 private views of a \bt_comp from within a component class
32 \ref api-comp-cls-dev-instance-meth "instance method".
34 Add a \bt_port to a component with
35 bt_self_component_source_add_output_port(),
36 bt_self_component_filter_add_input_port(),
37 bt_self_component_filter_add_output_port(), and
38 bt_self_component_sink_add_input_port().
40 When you add a port to a component, you can attach custom user data
41 to it (\bt_voidp). You can retrieve this user data
42 afterwards with bt_self_component_port_get_data().
44 Borrow a \bt_self_comp_port from a component by index with
45 bt_self_component_source_borrow_output_port_by_index(),
46 bt_self_component_filter_borrow_input_port_by_index(),
47 bt_self_component_filter_borrow_output_port_by_index(), and
48 bt_self_component_sink_borrow_input_port_by_index().
50 Borrow a \bt_self_comp_port from a component by name with
51 bt_self_component_source_borrow_output_port_by_name(),
52 bt_self_component_filter_borrow_input_port_by_name(),
53 bt_self_component_filter_borrow_output_port_by_name(), and
54 bt_self_component_sink_borrow_input_port_by_name().
56 Set and get user data attached to a component with
57 bt_self_component_set_data() and bt_self_component_get_data().
59 Get a component's owning trace processing \bt_graph's effective
60 \bt_mip version with bt_self_component_get_graph_mip_version().
62 Check whether or not a \bt_sink_comp is interrupted with
63 bt_self_component_sink_is_interrupted().
65 \ref api-fund-c-typing "Upcast" the "self" (private) types to the
66 public and common self component types with the
67 <code>bt_self_component*_as_component*()</code> and
68 <code>bt_self_component_*_as_self_component()</code> functions.
77 @typedef struct bt_self_component bt_self_component;
82 @typedef struct bt_self_component_source bt_self_component_source;
87 @typedef struct bt_self_component_filter bt_self_component_filter;
92 @typedef struct bt_self_component_sink bt_self_component_sink;
97 @typedef struct bt_self_component_source_configuration bt_self_component_source_configuration;
100 Self \bt_src_comp configuration.
102 @typedef struct bt_self_component_filter_configuration bt_self_component_filter_configuration;
105 Self \bt_flt_comp configuration.
107 @typedef struct bt_self_component_sink_configuration bt_self_component_sink_configuration;
110 Self \bt_sink_comp configuration.
122 Status codes for bt_self_component_source_add_output_port(),
123 bt_self_component_filter_add_input_port(),
124 bt_self_component_filter_add_output_port(), and
125 bt_self_component_sink_add_input_port().
127 typedef enum bt_self_component_add_port_status
{
132 BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
= __BT_FUNC_STATUS_OK
,
138 BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
144 BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
145 } bt_self_component_add_port_status
;
149 Adds an \bt_oport named \bt_p{name} and having the user data
150 \bt_p{user_data} to the \bt_src_comp \bt_p{self_component},
151 and sets \bt_p{*self_component_port} to the resulting port.
154 You can only call this function from within the
155 \ref api-comp-cls-dev-meth-init "initialization",
156 \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
158 \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
161 @param[in] self_component
162 Source component instance.
164 Name of the output port to add to \bt_p{self_component} (copied).
166 User data of the output port to add to \bt_p{self_component}.
167 @param[out] self_component_port
168 <strong>On success, if not \c NULL</strong>,
169 \bt_p{*self_component_port} is a \em borrowed reference of the
172 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
174 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
176 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
179 @bt_pre_not_null{self_component}
180 @bt_pre_not_null{name}
182 No other output port within \bt_p{self_component} has the name
185 extern bt_self_component_add_port_status
186 bt_self_component_source_add_output_port(
187 bt_self_component_source
*self_component
,
188 const char *name
, void *user_data
,
189 bt_self_component_port_output
**self_component_port
);
193 Adds an \bt_iport named \bt_p{name} and having the user data
194 \bt_p{user_data} to the \bt_flt_comp \bt_p{self_component},
195 and sets \bt_p{*self_component_port} to the resulting port.
198 You can only call this function from within the
199 \ref api-comp-cls-dev-meth-init "initialization",
200 \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
202 \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
205 @param[in] self_component
206 Filter component instance.
208 Name of the input port to add to \bt_p{self_component} (copied).
210 User data of the input port to add to \bt_p{self_component}.
211 @param[out] self_component_port
212 <strong>On success, if not \c NULL</strong>,
213 \bt_p{*self_component_port} is a \em borrowed reference of the
216 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
218 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
220 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
223 @bt_pre_not_null{self_component}
224 @bt_pre_not_null{name}
226 No other input port within \bt_p{self_component} has the name
229 extern bt_self_component_add_port_status
230 bt_self_component_filter_add_input_port(
231 bt_self_component_filter
*self_component
,
232 const char *name
, void *user_data
,
233 bt_self_component_port_input
**self_component_port
);
237 Adds an \bt_oport named \bt_p{name} and having the user data
238 \bt_p{user_data} to the \bt_flt_comp \bt_p{self_component},
239 and sets \bt_p{*self_component_port} to the resulting port.
242 You can only call this function from within the
243 \ref api-comp-cls-dev-meth-init "initialization",
244 \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
246 \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
249 @param[in] self_component
250 Filter component instance.
252 Name of the output port to add to \bt_p{self_component} (copied).
254 User data of the output port to add to \bt_p{self_component}.
255 @param[out] self_component_port
256 <strong>On success, if not \c NULL</strong>,
257 \bt_p{*self_component_port} is a \em borrowed reference of the
260 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
262 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
264 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
267 @bt_pre_not_null{self_component}
268 @bt_pre_not_null{name}
270 No other output port within \bt_p{self_component} has the name
273 extern bt_self_component_add_port_status
274 bt_self_component_filter_add_output_port(
275 bt_self_component_filter
*self_component
,
276 const char *name
, void *user_data
,
277 bt_self_component_port_output
**self_component_port
);
281 Adds an \bt_iport named \bt_p{name} and having the user data
282 \bt_p{user_data} to the \bt_sink_comp \bt_p{self_component},
283 and sets \bt_p{*self_component_port} to the resulting port.
286 You can only call this function from within the
287 \ref api-comp-cls-dev-meth-init "initialization",
288 \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
290 \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
293 @param[in] self_component
294 Sink component instance.
296 Name of the input port to add to \bt_p{self_component} (copied).
298 User data of the input port to add to \bt_p{self_component}.
299 @param[out] self_component_port
300 <strong>On success, if not \c NULL</strong>,
301 \bt_p{*self_component_port} is a \em borrowed reference of the
304 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
306 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
308 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
311 @bt_pre_not_null{self_component}
312 @bt_pre_not_null{name}
314 No other input port within \bt_p{self_component} has the name
318 extern bt_self_component_add_port_status
319 bt_self_component_sink_add_input_port(
320 bt_self_component_sink
*self_component
,
321 const char *name
, void *user_data
,
322 bt_self_component_port_input
**self_component_port
);
333 Borrows the \bt_self_comp_oport at index \bt_p{index} from the
334 \bt_src_comp \bt_p{self_component}.
336 @param[in] self_component
337 Source component instance.
339 Index of the output port to borrow from \bt_p{self_component}.
343 \em Borrowed reference of the output port of
344 \bt_p{self_component} at index \bt_p{index}.
346 The returned pointer remains valid as long as \bt_p{self_component}
350 @bt_pre_not_null{self_component}
352 \bt_p{index} is less than the number of output ports
353 \bt_p{self_component} has (as returned by
354 bt_component_source_get_output_port_count()).
356 @sa bt_component_source_get_output_port_count() —
357 Returns the number of output ports that a source component has.
359 extern bt_self_component_port_output
*
360 bt_self_component_source_borrow_output_port_by_index(
361 bt_self_component_source
*self_component
,
366 Borrows the \bt_self_comp_iport at index \bt_p{index} from the
367 \bt_flt_comp \bt_p{self_component}.
369 @param[in] self_component
370 Filter component instance.
372 Index of the input port to borrow from \bt_p{self_component}.
376 \em Borrowed reference of the input port of
377 \bt_p{self_component} at index \bt_p{index}.
379 The returned pointer remains valid as long as \bt_p{self_component}
383 @bt_pre_not_null{self_component}
385 \bt_p{index} is less than the number of input ports
386 \bt_p{self_component} has (as returned by
387 bt_component_filter_get_input_port_count()).
389 @sa bt_component_filter_get_input_port_count() —
390 Returns the number of input ports that a filter component has.
392 extern bt_self_component_port_input
*
393 bt_self_component_filter_borrow_input_port_by_index(
394 bt_self_component_filter
*self_component
,
399 Borrows the \bt_self_comp_oport at index \bt_p{index} from the
400 \bt_flt_comp \bt_p{self_component}.
402 @param[in] self_component
403 Filter component instance.
405 Index of the output port to borrow from \bt_p{self_component}.
409 \em Borrowed reference of the output port of
410 \bt_p{self_component} at index \bt_p{index}.
412 The returned pointer remains valid as long as \bt_p{self_component}
416 @bt_pre_not_null{self_component}
418 \bt_p{index} is less than the number of output ports
419 \bt_p{self_component} has (as returned by
420 bt_component_filter_get_output_port_count()).
422 @sa bt_component_filter_get_output_port_count() —
423 Returns the number of output ports that a filter component has.
425 extern bt_self_component_port_output
*
426 bt_self_component_filter_borrow_output_port_by_index(
427 bt_self_component_filter
*self_component
,
432 Borrows the \bt_self_comp_iport at index \bt_p{index} from the
433 \bt_sink_comp \bt_p{self_component}.
435 @param[in] self_component
436 Sink component instance.
438 Index of the input port to borrow from \bt_p{self_component}.
442 \em Borrowed reference of the input port of
443 \bt_p{self_component} at index \bt_p{index}.
445 The returned pointer remains valid as long as \bt_p{self_component}
449 @bt_pre_not_null{self_component}
451 \bt_p{index} is less than the number of input ports
452 \bt_p{self_component} has (as returned by
453 bt_component_sink_get_input_port_count()).
455 @sa bt_component_sink_get_input_port_count() —
456 Returns the number of input ports that a sink component has.
458 extern bt_self_component_port_input
*
459 bt_self_component_sink_borrow_input_port_by_index(
460 bt_self_component_sink
*self_component
, uint64_t index
);
464 Borrows the \bt_self_comp_oport named \bt_p{name} from the
465 \bt_src_comp \bt_p{self_component}.
467 If \bt_p{self_component} has no output port named \bt_p{name}, this
468 function returns \c NULL.
470 @param[in] self_component
471 Source component instance.
473 Name of the output port to borrow from \bt_p{self_component}.
477 \em Borrowed reference of the output port of
478 \bt_p{self_component} named \bt_p{name}, or \c NULL if none.
480 The returned pointer remains valid as long as \bt_p{self_component}
484 @bt_pre_not_null{self_component}
485 @bt_pre_not_null{name}
487 extern bt_self_component_port_output
*
488 bt_self_component_source_borrow_output_port_by_name(
489 bt_self_component_source
*self_component
,
494 Borrows the \bt_self_comp_iport named \bt_p{name} from the
495 \bt_flt_comp \bt_p{self_component}.
497 If \bt_p{self_component} has no input port named \bt_p{name}, this
498 function returns \c NULL.
500 @param[in] self_component
501 Filter component instance.
503 Name of the input port to borrow from \bt_p{self_component}.
507 \em Borrowed reference of the input port of
508 \bt_p{self_component} named \bt_p{name}, or \c NULL if none.
510 The returned pointer remains valid as long as \bt_p{self_component}
514 @bt_pre_not_null{self_component}
515 @bt_pre_not_null{name}
517 extern bt_self_component_port_input
*
518 bt_self_component_filter_borrow_input_port_by_name(
519 bt_self_component_filter
*self_component
,
524 Borrows the \bt_self_comp_oport named \bt_p{name} from the
525 \bt_flt_comp \bt_p{self_component}.
527 If \bt_p{self_component} has no output port named \bt_p{name}, this
528 function returns \c NULL.
530 @param[in] self_component
531 Filter component instance.
533 Name of the output port to borrow from \bt_p{self_component}.
537 \em Borrowed reference of the output port of
538 \bt_p{self_component} named \bt_p{name}, or \c NULL if none.
540 The returned pointer remains valid as long as \bt_p{self_component}
544 @bt_pre_not_null{self_component}
545 @bt_pre_not_null{name}
547 extern bt_self_component_port_output
*
548 bt_self_component_filter_borrow_output_port_by_name(
549 bt_self_component_filter
*self_component
,
554 Borrows the \bt_self_comp_iport named \bt_p{name} from the
555 \bt_sink_comp \bt_p{self_component}.
557 If \bt_p{self_component} has no input port named \bt_p{name}, this
558 function returns \c NULL.
560 @param[in] self_component
561 Sink component instance.
563 Name of the input port to borrow from \bt_p{self_component}.
567 \em Borrowed reference of the input port of
568 \bt_p{self_component} named \bt_p{name}, or \c NULL if none.
570 The returned pointer remains valid as long as \bt_p{self_component}
574 @bt_pre_not_null{self_component}
575 @bt_pre_not_null{name}
577 extern bt_self_component_port_input
*
578 bt_self_component_sink_borrow_input_port_by_name(
579 bt_self_component_sink
*self_component
,
591 Sets the user data of the \bt_comp \bt_p{self_component} to
594 @param[in] self_component
597 New user data of \bt_p{self_component}.
599 @bt_pre_not_null{self_component}
601 @sa bt_self_component_get_data() —
602 Returns the user data of a component.
604 extern void bt_self_component_set_data(
605 bt_self_component
*self_component
, void *user_data
);
609 Returns the user data of the \bt_comp \bt_p{self_component}.
611 @param[in] self_component
615 User data of \bt_p{self_component}.
617 @bt_pre_not_null{self_component}
619 @sa bt_self_component_set_data() —
620 Sets the user data of a component.
622 extern void *bt_self_component_get_data(
623 const bt_self_component
*self_component
);
628 @name Trace processing graph's effective MIP version access
634 Returns the effective \bt_mip (MIP) version of the trace processing
635 \bt_graph which contains the \bt_comp \bt_p{self_component}.
638 As of \bt_name_version_min_maj, because bt_get_maximal_mip_version()
639 returns 0, this function always returns 0.
641 @param[in] self_component
645 Effective MIP version of the trace processing graph which
646 contains \bt_p{self_component}.
648 @bt_pre_not_null{self_component}
651 uint64_t bt_self_component_get_graph_mip_version(
652 bt_self_component
*self_component
);
657 @name Sink component's interruption query
663 Returns whether or not the \bt_sink_comp \bt_p{self_component}
664 is interrupted, that is, whether or not any of its \bt_p_intr
667 @param[in] self_component
671 #BT_TRUE if \bt_p{self_component} is interrupted (any of its
672 interrupters is set).
674 @bt_pre_not_null{self_component}
676 @sa bt_graph_borrow_default_interrupter() —
677 Borrows a trace processing graph's default interrupter.
678 @sa bt_graph_add_interrupter() —
679 Adds an interrupter to a graph.
681 extern bt_bool
bt_self_component_sink_is_interrupted(
682 const bt_self_component_sink
*self_component
);
687 @name Self to public upcast
693 \ref api-fund-c-typing "Upcasts" the self \bt_comp
694 \bt_p{self_component} to the public #bt_component type.
696 @param[in] self_component
704 \bt_p{self_component} as a public component.
707 const bt_component
*bt_self_component_as_component(
708 bt_self_component
*self_component
)
710 return __BT_UPCAST(bt_component
, self_component
);
715 \ref api-fund-c-typing "Upcasts" the self \bt_src_comp
716 \bt_p{self_component} to the public #bt_component_source
719 @param[in] self_component
721 Source component to upcast.
727 \bt_p{self_component} as a public source component.
730 const bt_component_source
*
731 bt_self_component_source_as_component_source(
732 bt_self_component_source
*self_component
)
734 return __BT_UPCAST_CONST(bt_component_source
, self_component
);
739 \ref api-fund-c-typing "Upcasts" the self \bt_flt_comp
740 \bt_p{self_component} to the public #bt_component_filter
743 @param[in] self_component
745 Filter component to upcast.
751 \bt_p{self_component} as a public filter component.
754 const bt_component_filter
*
755 bt_self_component_filter_as_component_filter(
756 bt_self_component_filter
*self_component
)
758 return __BT_UPCAST_CONST(bt_component_filter
, self_component
);
763 \ref api-fund-c-typing "Upcasts" the self \bt_sink_comp
764 \bt_p{self_component} to the public #bt_component_sink
767 @param[in] self_component
769 Sink component to upcast.
775 \bt_p{self_component} as a public sink component.
778 const bt_component_sink
*
779 bt_self_component_sink_as_component_sink(
780 bt_self_component_sink
*self_component
)
782 return __BT_UPCAST_CONST(bt_component_sink
, self_component
);
788 @name Self to common self upcast
794 \ref api-fund-c-typing "Upcasts" the self \bt_src_comp
795 \bt_p{self_component} to the common #bt_self_component
798 @param[in] self_component
800 Source component to upcast.
806 \bt_p{self_component} as a common self component.
809 bt_self_component
*bt_self_component_source_as_self_component(
810 bt_self_component_source
*self_component
)
812 return __BT_UPCAST(bt_self_component
, self_component
);
817 \ref api-fund-c-typing "Upcasts" the self \bt_flt_comp
818 \bt_p{self_component} to the common #bt_self_component
821 @param[in] self_component
823 Filter component to upcast.
829 \bt_p{self_component} as a common self component.
832 bt_self_component
*bt_self_component_filter_as_self_component(
833 bt_self_component_filter
*self_component
)
835 return __BT_UPCAST(bt_self_component
, self_component
);
840 \ref api-fund-c-typing "Upcasts" the self \bt_sink_comp
841 \bt_p{self_component} to the common #bt_self_component
844 @param[in] self_component
846 Sink component to upcast.
852 \bt_p{self_component} as a common self component.
855 bt_self_component
*bt_self_component_sink_as_self_component(
856 bt_self_component_sink
*self_component
)
858 return __BT_UPCAST(bt_self_component
, self_component
);
869 #endif /* BABELTRACE2_GRAPH_SELF_COMPONENT_H */