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
)
194 Adds an \bt_iport named \bt_p{name} and having the user data
195 \bt_p{user_data} to the \bt_flt_comp \bt_p{self_component},
196 and sets \bt_p{*self_component_port} to the resulting port.
199 You can only call this function from within the
200 \ref api-comp-cls-dev-meth-init "initialization",
201 \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
203 \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
206 @param[in] self_component
207 Filter component instance.
209 Name of the input port to add to \bt_p{self_component} (copied).
211 User data of the input port to add to \bt_p{self_component}.
212 @param[out] self_component_port
213 <strong>On success, if not \c NULL</strong>,
214 \bt_p{*self_component_port} is a \em borrowed reference of the
217 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
219 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
221 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
224 @bt_pre_not_null{self_component}
225 @bt_pre_not_null{name}
227 No other input port within \bt_p{self_component} has the name
230 extern bt_self_component_add_port_status
231 bt_self_component_filter_add_input_port(
232 bt_self_component_filter
*self_component
,
233 const char *name
, void *user_data
,
234 bt_self_component_port_input
**self_component_port
)
239 Adds an \bt_oport named \bt_p{name} and having the user data
240 \bt_p{user_data} to the \bt_flt_comp \bt_p{self_component},
241 and sets \bt_p{*self_component_port} to the resulting port.
244 You can only call this function from within the
245 \ref api-comp-cls-dev-meth-init "initialization",
246 \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
248 \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
251 @param[in] self_component
252 Filter component instance.
254 Name of the output port to add to \bt_p{self_component} (copied).
256 User data of the output port to add to \bt_p{self_component}.
257 @param[out] self_component_port
258 <strong>On success, if not \c NULL</strong>,
259 \bt_p{*self_component_port} is a \em borrowed reference of the
262 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
264 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
266 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
269 @bt_pre_not_null{self_component}
270 @bt_pre_not_null{name}
272 No other output port within \bt_p{self_component} has the name
275 extern bt_self_component_add_port_status
276 bt_self_component_filter_add_output_port(
277 bt_self_component_filter
*self_component
,
278 const char *name
, void *user_data
,
279 bt_self_component_port_output
**self_component_port
)
284 Adds an \bt_iport named \bt_p{name} and having the user data
285 \bt_p{user_data} to the \bt_sink_comp \bt_p{self_component},
286 and sets \bt_p{*self_component_port} to the resulting port.
289 You can only call this function from within the
290 \ref api-comp-cls-dev-meth-init "initialization",
291 \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
293 \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
296 @param[in] self_component
297 Sink component instance.
299 Name of the input port to add to \bt_p{self_component} (copied).
301 User data of the input port to add to \bt_p{self_component}.
302 @param[out] self_component_port
303 <strong>On success, if not \c NULL</strong>,
304 \bt_p{*self_component_port} is a \em borrowed reference of the
307 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
309 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
311 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
314 @bt_pre_not_null{self_component}
315 @bt_pre_not_null{name}
317 No other input port within \bt_p{self_component} has the name
321 extern bt_self_component_add_port_status
322 bt_self_component_sink_add_input_port(
323 bt_self_component_sink
*self_component
,
324 const char *name
, void *user_data
,
325 bt_self_component_port_input
**self_component_port
)
337 Borrows the \bt_self_comp_oport at index \bt_p{index} from the
338 \bt_src_comp \bt_p{self_component}.
340 @param[in] self_component
341 Source component instance.
343 Index of the output port to borrow from \bt_p{self_component}.
347 \em Borrowed reference of the output port of
348 \bt_p{self_component} at index \bt_p{index}.
350 The returned pointer remains valid as long as \bt_p{self_component}
354 @bt_pre_not_null{self_component}
356 \bt_p{index} is less than the number of output ports
357 \bt_p{self_component} has (as returned by
358 bt_component_source_get_output_port_count()).
360 @sa bt_component_source_get_output_port_count() —
361 Returns the number of output ports that a source component has.
363 extern bt_self_component_port_output
*
364 bt_self_component_source_borrow_output_port_by_index(
365 bt_self_component_source
*self_component
,
366 uint64_t index
) __BT_NOEXCEPT
;
370 Borrows the \bt_self_comp_iport at index \bt_p{index} from the
371 \bt_flt_comp \bt_p{self_component}.
373 @param[in] self_component
374 Filter component instance.
376 Index of the input port to borrow from \bt_p{self_component}.
380 \em Borrowed reference of the input port of
381 \bt_p{self_component} at index \bt_p{index}.
383 The returned pointer remains valid as long as \bt_p{self_component}
387 @bt_pre_not_null{self_component}
389 \bt_p{index} is less than the number of input ports
390 \bt_p{self_component} has (as returned by
391 bt_component_filter_get_input_port_count()).
393 @sa bt_component_filter_get_input_port_count() —
394 Returns the number of input ports that a filter component has.
396 extern bt_self_component_port_input
*
397 bt_self_component_filter_borrow_input_port_by_index(
398 bt_self_component_filter
*self_component
,
399 uint64_t index
) __BT_NOEXCEPT
;
403 Borrows the \bt_self_comp_oport at index \bt_p{index} from the
404 \bt_flt_comp \bt_p{self_component}.
406 @param[in] self_component
407 Filter component instance.
409 Index of the output port to borrow from \bt_p{self_component}.
413 \em Borrowed reference of the output port of
414 \bt_p{self_component} at index \bt_p{index}.
416 The returned pointer remains valid as long as \bt_p{self_component}
420 @bt_pre_not_null{self_component}
422 \bt_p{index} is less than the number of output ports
423 \bt_p{self_component} has (as returned by
424 bt_component_filter_get_output_port_count()).
426 @sa bt_component_filter_get_output_port_count() —
427 Returns the number of output ports that a filter component has.
429 extern bt_self_component_port_output
*
430 bt_self_component_filter_borrow_output_port_by_index(
431 bt_self_component_filter
*self_component
,
432 uint64_t index
) __BT_NOEXCEPT
;
436 Borrows the \bt_self_comp_iport at index \bt_p{index} from the
437 \bt_sink_comp \bt_p{self_component}.
439 @param[in] self_component
440 Sink component instance.
442 Index of the input port to borrow from \bt_p{self_component}.
446 \em Borrowed reference of the input port of
447 \bt_p{self_component} at index \bt_p{index}.
449 The returned pointer remains valid as long as \bt_p{self_component}
453 @bt_pre_not_null{self_component}
455 \bt_p{index} is less than the number of input ports
456 \bt_p{self_component} has (as returned by
457 bt_component_sink_get_input_port_count()).
459 @sa bt_component_sink_get_input_port_count() —
460 Returns the number of input ports that a sink component has.
462 extern bt_self_component_port_input
*
463 bt_self_component_sink_borrow_input_port_by_index(
464 bt_self_component_sink
*self_component
, uint64_t index
)
469 Borrows the \bt_self_comp_oport named \bt_p{name} from the
470 \bt_src_comp \bt_p{self_component}.
472 If \bt_p{self_component} has no output port named \bt_p{name}, this
473 function returns \c NULL.
475 @param[in] self_component
476 Source component instance.
478 Name of the output port to borrow from \bt_p{self_component}.
482 \em Borrowed reference of the output port of
483 \bt_p{self_component} named \bt_p{name}, or \c NULL if none.
485 The returned pointer remains valid as long as \bt_p{self_component}
489 @bt_pre_not_null{self_component}
490 @bt_pre_not_null{name}
492 extern bt_self_component_port_output
*
493 bt_self_component_source_borrow_output_port_by_name(
494 bt_self_component_source
*self_component
,
495 const char *name
) __BT_NOEXCEPT
;
499 Borrows the \bt_self_comp_iport named \bt_p{name} from the
500 \bt_flt_comp \bt_p{self_component}.
502 If \bt_p{self_component} has no input port named \bt_p{name}, this
503 function returns \c NULL.
505 @param[in] self_component
506 Filter component instance.
508 Name of the input port to borrow from \bt_p{self_component}.
512 \em Borrowed reference of the input port of
513 \bt_p{self_component} named \bt_p{name}, or \c NULL if none.
515 The returned pointer remains valid as long as \bt_p{self_component}
519 @bt_pre_not_null{self_component}
520 @bt_pre_not_null{name}
522 extern bt_self_component_port_input
*
523 bt_self_component_filter_borrow_input_port_by_name(
524 bt_self_component_filter
*self_component
,
525 const char *name
) __BT_NOEXCEPT
;
529 Borrows the \bt_self_comp_oport named \bt_p{name} from the
530 \bt_flt_comp \bt_p{self_component}.
532 If \bt_p{self_component} has no output port named \bt_p{name}, this
533 function returns \c NULL.
535 @param[in] self_component
536 Filter component instance.
538 Name of the output port to borrow from \bt_p{self_component}.
542 \em Borrowed reference of the output port of
543 \bt_p{self_component} named \bt_p{name}, or \c NULL if none.
545 The returned pointer remains valid as long as \bt_p{self_component}
549 @bt_pre_not_null{self_component}
550 @bt_pre_not_null{name}
552 extern bt_self_component_port_output
*
553 bt_self_component_filter_borrow_output_port_by_name(
554 bt_self_component_filter
*self_component
,
555 const char *name
) __BT_NOEXCEPT
;
559 Borrows the \bt_self_comp_iport named \bt_p{name} from the
560 \bt_sink_comp \bt_p{self_component}.
562 If \bt_p{self_component} has no input port named \bt_p{name}, this
563 function returns \c NULL.
565 @param[in] self_component
566 Sink component instance.
568 Name of the input port to borrow from \bt_p{self_component}.
572 \em Borrowed reference of the input port of
573 \bt_p{self_component} named \bt_p{name}, or \c NULL if none.
575 The returned pointer remains valid as long as \bt_p{self_component}
579 @bt_pre_not_null{self_component}
580 @bt_pre_not_null{name}
582 extern bt_self_component_port_input
*
583 bt_self_component_sink_borrow_input_port_by_name(
584 bt_self_component_sink
*self_component
,
585 const char *name
) __BT_NOEXCEPT
;
596 Sets the user data of the \bt_comp \bt_p{self_component} to
599 @param[in] self_component
602 New user data of \bt_p{self_component}.
604 @bt_pre_not_null{self_component}
606 @sa bt_self_component_get_data() —
607 Returns the user data of a component.
609 extern void bt_self_component_set_data(
610 bt_self_component
*self_component
, void *user_data
)
615 Returns the user data of the \bt_comp \bt_p{self_component}.
617 @param[in] self_component
621 User data of \bt_p{self_component}.
623 @bt_pre_not_null{self_component}
625 @sa bt_self_component_set_data() —
626 Sets the user data of a component.
628 extern void *bt_self_component_get_data(
629 const bt_self_component
*self_component
) __BT_NOEXCEPT
;
634 @name Trace processing graph's effective MIP version access
640 Returns the effective \bt_mip (MIP) version of the trace processing
641 \bt_graph which contains the \bt_comp \bt_p{self_component}.
644 As of \bt_name_version_min_maj, because bt_get_maximal_mip_version()
645 returns 0, this function always returns 0.
647 @param[in] self_component
651 Effective MIP version of the trace processing graph which
652 contains \bt_p{self_component}.
654 @bt_pre_not_null{self_component}
657 uint64_t bt_self_component_get_graph_mip_version(
658 bt_self_component
*self_component
) __BT_NOEXCEPT
;
663 @name Sink component's interruption query
669 Returns whether or not the \bt_sink_comp \bt_p{self_component}
670 is interrupted, that is, whether or not any of its \bt_p_intr
673 @param[in] self_component
677 #BT_TRUE if \bt_p{self_component} is interrupted (any of its
678 interrupters is set).
680 @bt_pre_not_null{self_component}
682 @sa bt_graph_borrow_default_interrupter() —
683 Borrows a trace processing graph's default interrupter.
684 @sa bt_graph_add_interrupter() —
685 Adds an interrupter to a graph.
687 extern bt_bool
bt_self_component_sink_is_interrupted(
688 const bt_self_component_sink
*self_component
) __BT_NOEXCEPT
;
693 @name Self to public upcast
699 \ref api-fund-c-typing "Upcasts" the self \bt_comp
700 \bt_p{self_component} to the public #bt_component type.
702 @param[in] self_component
710 \bt_p{self_component} as a public component.
713 const bt_component
*bt_self_component_as_component(
714 bt_self_component
*self_component
) __BT_NOEXCEPT
716 return __BT_UPCAST(bt_component
, self_component
);
721 \ref api-fund-c-typing "Upcasts" the self \bt_src_comp
722 \bt_p{self_component} to the public #bt_component_source
725 @param[in] self_component
727 Source component to upcast.
733 \bt_p{self_component} as a public source component.
736 const bt_component_source
*
737 bt_self_component_source_as_component_source(
738 bt_self_component_source
*self_component
) __BT_NOEXCEPT
740 return __BT_UPCAST_CONST(bt_component_source
, self_component
);
745 \ref api-fund-c-typing "Upcasts" the self \bt_flt_comp
746 \bt_p{self_component} to the public #bt_component_filter
749 @param[in] self_component
751 Filter component to upcast.
757 \bt_p{self_component} as a public filter component.
760 const bt_component_filter
*
761 bt_self_component_filter_as_component_filter(
762 bt_self_component_filter
*self_component
) __BT_NOEXCEPT
764 return __BT_UPCAST_CONST(bt_component_filter
, self_component
);
769 \ref api-fund-c-typing "Upcasts" the self \bt_sink_comp
770 \bt_p{self_component} to the public #bt_component_sink
773 @param[in] self_component
775 Sink component to upcast.
781 \bt_p{self_component} as a public sink component.
784 const bt_component_sink
*
785 bt_self_component_sink_as_component_sink(
786 bt_self_component_sink
*self_component
) __BT_NOEXCEPT
788 return __BT_UPCAST_CONST(bt_component_sink
, self_component
);
794 @name Self to common self upcast
800 \ref api-fund-c-typing "Upcasts" the self \bt_src_comp
801 \bt_p{self_component} to the common #bt_self_component
804 @param[in] self_component
806 Source component to upcast.
812 \bt_p{self_component} as a common self component.
815 bt_self_component
*bt_self_component_source_as_self_component(
816 bt_self_component_source
*self_component
) __BT_NOEXCEPT
818 return __BT_UPCAST(bt_self_component
, self_component
);
823 \ref api-fund-c-typing "Upcasts" the self \bt_flt_comp
824 \bt_p{self_component} to the common #bt_self_component
827 @param[in] self_component
829 Filter component to upcast.
835 \bt_p{self_component} as a common self component.
838 bt_self_component
*bt_self_component_filter_as_self_component(
839 bt_self_component_filter
*self_component
) __BT_NOEXCEPT
841 return __BT_UPCAST(bt_self_component
, self_component
);
846 \ref api-fund-c-typing "Upcasts" the self \bt_sink_comp
847 \bt_p{self_component} to the common #bt_self_component
850 @param[in] self_component
852 Sink component to upcast.
858 \bt_p{self_component} as a common self component.
861 bt_self_component
*bt_self_component_sink_as_self_component(
862 bt_self_component_sink
*self_component
) __BT_NOEXCEPT
864 return __BT_UPCAST(bt_self_component
, self_component
);
875 #endif /* BABELTRACE2_GRAPH_SELF_COMPONENT_H */