1 #ifndef BABELTRACE2_GRAPH_SELF_COMPONENT_H
2 #define BABELTRACE2_GRAPH_SELF_COMPONENT_H
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to deal
9 * in the Software without restriction, including without limitation the rights
10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
30 #include <babeltrace2/types.h>
37 @defgroup api-self-comp Self components
38 @ingroup api-comp-cls-dev
41 Private views of \bt_p_comp for instance methods.
43 The #bt_self_component, #bt_self_component_source,
44 #bt_self_component_filter, #bt_self_component_sink types are
45 private views of a \bt_comp from within a component class
46 \ref api-comp-cls-dev-instance-meth "instance method".
48 Add a \bt_port to a component with
49 bt_self_component_source_add_output_port(),
50 bt_self_component_filter_add_input_port(),
51 bt_self_component_filter_add_output_port(), and
52 bt_self_component_sink_add_input_port().
54 When you add a port to a component, you can attach custom user data
55 to it (\bt_voidp). You can retrieve this user data
56 afterwards with bt_self_component_port_get_data().
58 Borrow a \bt_self_comp_port from a component by index with
59 bt_self_component_source_borrow_output_port_by_index(),
60 bt_self_component_filter_borrow_input_port_by_index(),
61 bt_self_component_filter_borrow_output_port_by_index(), and
62 bt_self_component_sink_borrow_input_port_by_index().
64 Borrow a \bt_self_comp_port from a component by name with
65 bt_self_component_source_borrow_output_port_by_name(),
66 bt_self_component_filter_borrow_input_port_by_name(),
67 bt_self_component_filter_borrow_output_port_by_name(), and
68 bt_self_component_sink_borrow_input_port_by_name().
70 Set and get user data attached to a component with
71 bt_self_component_set_data() and bt_self_component_get_data().
73 Get a component's owning trace processing \bt_graph's effective
74 \bt_mip version with bt_self_component_get_graph_mip_version().
76 Check whether or not a \bt_sink_comp is interrupted with
77 bt_self_component_sink_is_interrupted().
79 \ref api-fund-c-typing "Upcast" the "self" (private) types to the
80 public and common self component types with the
81 <code>bt_self_component*_as_component*()</code> and
82 <code>bt_self_component_*_as_self_component()</code> functions.
91 @typedef struct bt_self_component bt_self_component;
96 @typedef struct bt_self_component_source bt_self_component_source;
101 @typedef struct bt_self_component_filter bt_self_component_filter;
106 @typedef struct bt_self_component_sink bt_self_component_sink;
111 @typedef struct bt_self_component_source_configuration bt_self_component_source_configuration;
114 Self \bt_src_comp configuration.
116 @typedef struct bt_self_component_filter_configuration bt_self_component_filter_configuration;
119 Self \bt_flt_comp configuration.
121 @typedef struct bt_self_component_sink_configuration bt_self_component_sink_configuration;
124 Self \bt_sink_comp configuration.
136 Status codes for bt_self_component_source_add_output_port(),
137 bt_self_component_filter_add_input_port(),
138 bt_self_component_filter_add_output_port(), and
139 bt_self_component_sink_add_input_port().
141 typedef enum bt_self_component_add_port_status
{
146 BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
= __BT_FUNC_STATUS_OK
,
152 BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
158 BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
159 } bt_self_component_add_port_status
;
163 Adds an \bt_oport named \bt_p{name} and having the user data
164 \bt_p{user_data} to the \bt_src_comp \bt_p{self_component},
165 and sets \bt_p{*self_component_port} to the resulting port.
168 You can only call this function from within the
169 \ref api-comp-cls-dev-meth-init "initialization",
170 \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
172 \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
175 @param[in] self_component
176 Source component instance.
178 Name of the output port to add to \bt_p{self_component} (copied).
180 User data of the output port to add to \bt_p{self_component}.
181 @param[out] self_component_port
182 <strong>On success, if not \c NULL</strong>,
183 \bt_p{*self_component_port} is a \em borrowed reference of the
186 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
188 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
190 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
193 @bt_pre_not_null{self_component}
194 @bt_pre_not_null{name}
196 No other output port within \bt_p{self_component} has the name
199 extern bt_self_component_add_port_status
200 bt_self_component_source_add_output_port(
201 bt_self_component_source
*self_component
,
202 const char *name
, void *user_data
,
203 bt_self_component_port_output
**self_component_port
);
207 Adds an \bt_iport named \bt_p{name} and having the user data
208 \bt_p{user_data} to the \bt_flt_comp \bt_p{self_component},
209 and sets \bt_p{*self_component_port} to the resulting port.
212 You can only call this function from within the
213 \ref api-comp-cls-dev-meth-init "initialization",
214 \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
216 \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
219 @param[in] self_component
220 Filter component instance.
222 Name of the input port to add to \bt_p{self_component} (copied).
224 User data of the input port to add to \bt_p{self_component}.
225 @param[out] self_component_port
226 <strong>On success, if not \c NULL</strong>,
227 \bt_p{*self_component_port} is a \em borrowed reference of the
230 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
232 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
234 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
237 @bt_pre_not_null{self_component}
238 @bt_pre_not_null{name}
240 No other input port within \bt_p{self_component} has the name
243 extern bt_self_component_add_port_status
244 bt_self_component_filter_add_input_port(
245 bt_self_component_filter
*self_component
,
246 const char *name
, void *user_data
,
247 bt_self_component_port_input
**self_component_port
);
251 Adds an \bt_oport named \bt_p{name} and having the user data
252 \bt_p{user_data} to the \bt_flt_comp \bt_p{self_component},
253 and sets \bt_p{*self_component_port} to the resulting port.
256 You can only call this function from within the
257 \ref api-comp-cls-dev-meth-init "initialization",
258 \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
260 \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
263 @param[in] self_component
264 Filter component instance.
266 Name of the output port to add to \bt_p{self_component} (copied).
268 User data of the output port to add to \bt_p{self_component}.
269 @param[out] self_component_port
270 <strong>On success, if not \c NULL</strong>,
271 \bt_p{*self_component_port} is a \em borrowed reference of the
274 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
276 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
278 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
281 @bt_pre_not_null{self_component}
282 @bt_pre_not_null{name}
284 No other output port within \bt_p{self_component} has the name
287 extern bt_self_component_add_port_status
288 bt_self_component_filter_add_output_port(
289 bt_self_component_filter
*self_component
,
290 const char *name
, void *user_data
,
291 bt_self_component_port_output
**self_component_port
);
295 Adds an \bt_iport named \bt_p{name} and having the user data
296 \bt_p{user_data} to the \bt_sink_comp \bt_p{self_component},
297 and sets \bt_p{*self_component_port} to the resulting port.
300 You can only call this function from within the
301 \ref api-comp-cls-dev-meth-init "initialization",
302 \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
304 \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
307 @param[in] self_component
308 Sink component instance.
310 Name of the input port to add to \bt_p{self_component} (copied).
312 User data of the input port to add to \bt_p{self_component}.
313 @param[out] self_component_port
314 <strong>On success, if not \c NULL</strong>,
315 \bt_p{*self_component_port} is a \em borrowed reference of the
318 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
320 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
322 @retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
325 @bt_pre_not_null{self_component}
326 @bt_pre_not_null{name}
328 No other input port within \bt_p{self_component} has the name
332 extern bt_self_component_add_port_status
333 bt_self_component_sink_add_input_port(
334 bt_self_component_sink
*self_component
,
335 const char *name
, void *user_data
,
336 bt_self_component_port_input
**self_component_port
);
347 Borrows the \bt_self_comp_oport at index \bt_p{index} from the
348 \bt_src_comp \bt_p{self_component}.
350 @param[in] self_component
351 Source component instance.
353 Index of the output port to borrow from \bt_p{self_component}.
357 \em Borrowed reference of the output port of
358 \bt_p{self_component} at index \bt_p{index}.
360 The returned pointer remains valid as long as \bt_p{self_component}
364 @bt_pre_not_null{self_component}
366 \bt_p{index} is less than the number of output ports
367 \bt_p{self_component} has (as returned by
368 bt_component_source_get_output_port_count()).
370 @sa bt_component_source_get_output_port_count() —
371 Returns the number of output ports that a source component has.
373 extern bt_self_component_port_output
*
374 bt_self_component_source_borrow_output_port_by_index(
375 bt_self_component_source
*self_component
,
380 Borrows the \bt_self_comp_iport at index \bt_p{index} from the
381 \bt_flt_comp \bt_p{self_component}.
383 @param[in] self_component
384 Filter component instance.
386 Index of the input port to borrow from \bt_p{self_component}.
390 \em Borrowed reference of the input port of
391 \bt_p{self_component} at index \bt_p{index}.
393 The returned pointer remains valid as long as \bt_p{self_component}
397 @bt_pre_not_null{self_component}
399 \bt_p{index} is less than the number of input ports
400 \bt_p{self_component} has (as returned by
401 bt_component_filter_get_input_port_count()).
403 @sa bt_component_filter_get_input_port_count() —
404 Returns the number of input ports that a filter component has.
406 extern bt_self_component_port_input
*
407 bt_self_component_filter_borrow_input_port_by_index(
408 bt_self_component_filter
*self_component
,
413 Borrows the \bt_self_comp_oport at index \bt_p{index} from the
414 \bt_flt_comp \bt_p{self_component}.
416 @param[in] self_component
417 Filter component instance.
419 Index of the output port to borrow from \bt_p{self_component}.
423 \em Borrowed reference of the output port of
424 \bt_p{self_component} at index \bt_p{index}.
426 The returned pointer remains valid as long as \bt_p{self_component}
430 @bt_pre_not_null{self_component}
432 \bt_p{index} is less than the number of output ports
433 \bt_p{self_component} has (as returned by
434 bt_component_filter_get_output_port_count()).
436 @sa bt_component_filter_get_output_port_count() —
437 Returns the number of output ports that a filter component has.
439 extern bt_self_component_port_output
*
440 bt_self_component_filter_borrow_output_port_by_index(
441 bt_self_component_filter
*self_component
,
446 Borrows the \bt_self_comp_iport at index \bt_p{index} from the
447 \bt_sink_comp \bt_p{self_component}.
449 @param[in] self_component
450 Sink component instance.
452 Index of the input port to borrow from \bt_p{self_component}.
456 \em Borrowed reference of the input port of
457 \bt_p{self_component} at index \bt_p{index}.
459 The returned pointer remains valid as long as \bt_p{self_component}
463 @bt_pre_not_null{self_component}
465 \bt_p{index} is less than the number of input ports
466 \bt_p{self_component} has (as returned by
467 bt_component_sink_get_input_port_count()).
469 @sa bt_component_sink_get_input_port_count() —
470 Returns the number of input ports that a sink component has.
472 extern bt_self_component_port_input
*
473 bt_self_component_sink_borrow_input_port_by_index(
474 bt_self_component_sink
*self_component
, uint64_t index
);
478 Borrows the \bt_self_comp_oport named \bt_p{name} from the
479 \bt_src_comp \bt_p{self_component}.
481 If \bt_p{self_component} has no output port named \bt_p{name}, this
482 function returns \c NULL.
484 @param[in] self_component
485 Source component instance.
487 Name of the output port to borrow from \bt_p{self_component}.
491 \em Borrowed reference of the output port of
492 \bt_p{self_component} named \bt_p{name}, or \c NULL if none.
494 The returned pointer remains valid as long as \bt_p{self_component}
498 @bt_pre_not_null{self_component}
499 @bt_pre_not_null{name}
501 extern bt_self_component_port_output
*
502 bt_self_component_source_borrow_output_port_by_name(
503 bt_self_component_source
*self_component
,
508 Borrows the \bt_self_comp_iport named \bt_p{name} from the
509 \bt_flt_comp \bt_p{self_component}.
511 If \bt_p{self_component} has no input port named \bt_p{name}, this
512 function returns \c NULL.
514 @param[in] self_component
515 Filter component instance.
517 Name of the input port to borrow from \bt_p{self_component}.
521 \em Borrowed reference of the input port of
522 \bt_p{self_component} named \bt_p{name}, or \c NULL if none.
524 The returned pointer remains valid as long as \bt_p{self_component}
528 @bt_pre_not_null{self_component}
529 @bt_pre_not_null{name}
531 extern bt_self_component_port_input
*
532 bt_self_component_filter_borrow_input_port_by_name(
533 bt_self_component_filter
*self_component
,
538 Borrows the \bt_self_comp_oport named \bt_p{name} from the
539 \bt_flt_comp \bt_p{self_component}.
541 If \bt_p{self_component} has no output port named \bt_p{name}, this
542 function returns \c NULL.
544 @param[in] self_component
545 Filter component instance.
547 Name of the output port to borrow from \bt_p{self_component}.
551 \em Borrowed reference of the output port of
552 \bt_p{self_component} named \bt_p{name}, or \c NULL if none.
554 The returned pointer remains valid as long as \bt_p{self_component}
558 @bt_pre_not_null{self_component}
559 @bt_pre_not_null{name}
561 extern bt_self_component_port_output
*
562 bt_self_component_filter_borrow_output_port_by_name(
563 bt_self_component_filter
*self_component
,
568 Borrows the \bt_self_comp_iport named \bt_p{name} from the
569 \bt_sink_comp \bt_p{self_component}.
571 If \bt_p{self_component} has no input port named \bt_p{name}, this
572 function returns \c NULL.
574 @param[in] self_component
575 Sink component instance.
577 Name of the input port to borrow from \bt_p{self_component}.
581 \em Borrowed reference of the input port of
582 \bt_p{self_component} named \bt_p{name}, or \c NULL if none.
584 The returned pointer remains valid as long as \bt_p{self_component}
588 @bt_pre_not_null{self_component}
589 @bt_pre_not_null{name}
591 extern bt_self_component_port_input
*
592 bt_self_component_sink_borrow_input_port_by_name(
593 bt_self_component_sink
*self_component
,
605 Sets the user data of the \bt_comp \bt_p{self_component} to
608 @param[in] self_component
611 New user data of \bt_p{self_component}.
613 @bt_pre_not_null{self_component}
615 @sa bt_self_component_get_data() —
616 Returns the user data of a component.
618 extern void bt_self_component_set_data(
619 bt_self_component
*self_component
, void *user_data
);
623 Returns the user data of the \bt_comp \bt_p{self_component}.
625 @param[in] self_component
629 User data of \bt_p{self_component}.
631 @bt_pre_not_null{self_component}
633 @sa bt_self_component_set_data() —
634 Sets the user data of a component.
636 extern void *bt_self_component_get_data(
637 const bt_self_component
*self_component
);
642 @name Trace processing graph's effective MIP version access
648 Returns the effective \bt_mip (MIP) version of the trace processing
649 \bt_graph which contains the \bt_comp \bt_p{self_component}.
652 As of \bt_name_version_min_maj, because bt_get_maximal_mip_version()
653 returns 0, this function always returns 0.
655 @param[in] self_component
659 Effective MIP version of the trace processing graph which
660 contains \bt_p{self_component}.
662 @bt_pre_not_null{self_component}
665 uint64_t bt_self_component_get_graph_mip_version(
666 bt_self_component
*self_component
);
671 @name Sink component's interruption query
677 Returns whether or not the \bt_sink_comp \bt_p{self_component}
678 is interrupted, that is, whether or not any of its \bt_p_intr
681 @param[in] self_component
685 #BT_TRUE if \bt_p{self_component} is interrupted (any of its
686 interrupters is set).
688 @bt_pre_not_null{self_component}
690 @sa bt_graph_borrow_default_interrupter() —
691 Borrows a trace processing graph's default interrupter.
692 @sa bt_graph_add_interrupter() —
693 Adds an interrupter to a graph.
695 extern bt_bool
bt_self_component_sink_is_interrupted(
696 const bt_self_component_sink
*self_component
);
701 @name Self to public upcast
707 \ref api-fund-c-typing "Upcasts" the self \bt_comp
708 \bt_p{self_component} to the public #bt_component type.
710 @param[in] self_component
718 \bt_p{self_component} as a public component.
721 const bt_component
*bt_self_component_as_component(
722 bt_self_component
*self_component
)
724 return __BT_UPCAST(bt_component
, self_component
);
729 \ref api-fund-c-typing "Upcasts" the self \bt_src_comp
730 \bt_p{self_component} to the public #bt_component_source
733 @param[in] self_component
735 Source component to upcast.
741 \bt_p{self_component} as a public source component.
744 const bt_component_source
*
745 bt_self_component_source_as_component_source(
746 bt_self_component_source
*self_component
)
748 return __BT_UPCAST_CONST(bt_component_source
, self_component
);
753 \ref api-fund-c-typing "Upcasts" the self \bt_flt_comp
754 \bt_p{self_component} to the public #bt_component_filter
757 @param[in] self_component
759 Filter component to upcast.
765 \bt_p{self_component} as a public filter component.
768 const bt_component_filter
*
769 bt_self_component_filter_as_component_filter(
770 bt_self_component_filter
*self_component
)
772 return __BT_UPCAST_CONST(bt_component_filter
, self_component
);
777 \ref api-fund-c-typing "Upcasts" the self \bt_sink_comp
778 \bt_p{self_component} to the public #bt_component_sink
781 @param[in] self_component
783 Sink component to upcast.
789 \bt_p{self_component} as a public sink component.
792 const bt_component_sink
*
793 bt_self_component_sink_as_component_sink(
794 bt_self_component_sink
*self_component
)
796 return __BT_UPCAST_CONST(bt_component_sink
, self_component
);
802 @name Self to common self upcast
808 \ref api-fund-c-typing "Upcasts" the self \bt_src_comp
809 \bt_p{self_component} to the common #bt_self_component
812 @param[in] self_component
814 Source component to upcast.
820 \bt_p{self_component} as a common self component.
823 bt_self_component
*bt_self_component_source_as_self_component(
824 bt_self_component_source
*self_component
)
826 return __BT_UPCAST(bt_self_component
, self_component
);
831 \ref api-fund-c-typing "Upcasts" the self \bt_flt_comp
832 \bt_p{self_component} to the common #bt_self_component
835 @param[in] self_component
837 Filter component to upcast.
843 \bt_p{self_component} as a common self component.
846 bt_self_component
*bt_self_component_filter_as_self_component(
847 bt_self_component_filter
*self_component
)
849 return __BT_UPCAST(bt_self_component
, self_component
);
854 \ref api-fund-c-typing "Upcasts" the self \bt_sink_comp
855 \bt_p{self_component} to the common #bt_self_component
858 @param[in] self_component
860 Sink component to upcast.
866 \bt_p{self_component} as a common self component.
869 bt_self_component
*bt_self_component_sink_as_self_component(
870 bt_self_component_sink
*self_component
)
872 return __BT_UPCAST(bt_self_component
, self_component
);
883 #endif /* BABELTRACE2_GRAPH_SELF_COMPONENT_H */