2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_GRAPH_GRAPH_H
8 #define BABELTRACE2_GRAPH_GRAPH_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>
17 #include <babeltrace2/logging.h>
24 @defgroup api-graph Graph
27 Trace processing graph.
29 A <strong><em>trace processing graph</em></strong> is a specialized
30 <a href="https://en.wikipedia.org/wiki/Filter_graph">filter graph</a>
31 to manipulate one or more traces.
33 Whereas the nodes of a multimedia filter graph typically exchange
34 video frames and audio samples, the nodes, or \bt_p_comp, of a trace
35 processing graph exchange immutable \bt_p_msg containing trace data.
37 The following illustration shows a basic trace processing graph which
38 converts many traces to a single log of pretty-printed lines:
40 @image html basic-convert-graph.png "Basic trace processing graph (conversion graph)."
42 In the illustrations above, notice that:
44 - The graph (blue) contains five components.
46 - Three source components (green) are connected to a single filter
49 There are five \bt_p_conn, from five \bt_p_oport
52 - The filter component is connected to a single sink component (red).
54 There's a single connection.
56 - Source components read external resources while the sink component
57 writes to the standard output or to a file.
59 - There are two source components having the same
60 \ref api-tir-comp-cls "class": <code>source.ctf.fs</code>.
62 - All components are instances of \bt_plugin-provided classes:
63 <code>babeltrace2-plugin-ctf.so</code>,
64 <code>user-plugin.so</code>,
65 <code>babeltrace2-plugin-utils.so</code>, and
66 <code>babeltrace2-plugin-text.so</code>.
68 Of course the topology can be much more complex if needed:
70 @image html complex-graph.png "Complex trace processing graph."
72 In a trace processing graph, \bt_p_comp are instances of \bt_p_comp_cls.
74 A \bt_plugin can provide a component class, but you can also create one
75 dynamically (see \ref api-comp-cls-dev).
77 The connections between component ports in a trace processing graph
78 indicate the needed topology to achieve a trace processing task. That
80 \bt_p_msg do not flow within connections. Instead, a source-to-sink
81 or filter-to-sink connection makes it
82 possible for a sink component to create a \bt_msg_iter on its end of
83 the connection (an \bt_iport). In turn, a filter component message
84 iterator can create other message iterators on one or more of the
85 component's input ports. For a single connection, there can exist
86 multiple message iterators.
88 A trace processing graph is a
89 \ref api-fund-shared-object "shared object": get a new reference with
90 bt_graph_get_ref() and put an existing reference with
93 The type of a trace processing graph is #bt_graph.
95 Create a default trace processing graph with bt_graph_create(). You need
96 to pass a \bt_mip (MIP) version number when you call this function.
98 \ref api-graph-lc "Trace processing graph life cycle"
99 to learn how to add components to the graph, connect their ports, and
102 To interrupt a \ref api-graph-lc-run "running" trace processing graph,
105 - Borrow the graph's default \bt_intr with
106 bt_graph_borrow_default_interrupter() and set it with
107 bt_interrupter_set().
109 When you call bt_graph_create(), the returned trace processing
110 graph has a default interrupter.
112 - Add your own interrupter with bt_graph_add_interrupter() \em before
113 you run the graph with bt_graph_run() or bt_graph_run_once().
115 Then, set the interrupter with bt_interrupter_set().
117 <h1>\anchor api-graph-lc Trace processing graph life cycle</h1>
119 The following diagram shows the life cycle of a trace processing
122 @image html graph-lifetime.png "Trace processing graph lifecycle."
124 After you create a default (empty) trace processing graph with
125 bt_graph_create(), there are three steps to make the trace processing
128 -# \ref api-graph-lc-add "Add components" to the graph.
129 -# \ref api-graph-lc-connect "Connect component ports".
130 -# \ref api-graph-lc-run "Run the graph".
132 You can repeat steps 1 and 2 before step 3, as connecting a
133 component \bt_port can make this \bt_comp create a new port:
134 you might want to add a component in reaction to this event
135 (see \ref api-graph-listeners "Listeners").
137 Steps 1 and 2 constitute the \em configuration phase of the trace
138 processing graph. The first time you call bt_graph_run() or
139 bt_graph_run_once() for a given graph (step 3), the graph becomes
140 <em>configured</em>, and it notifies the sink components as such so that
141 they can create their \bt_p_msg_iter.
143 Once a trace processing graph becomes configured:
145 - You cannot \ref api-graph-lc-add "add a component" to it.
147 - You cannot \ref api-graph-lc-connect "connect component ports".
149 - Components cannot add ports.
151 In general, as of \bt_name_version_min_maj:
153 - You cannot remove a component from a trace processing graph.
155 - You cannot end (remove) a port \bt_conn.
157 - Components cannot remove ports.
159 If \em any error occurs (a function returns a status code which ends
160 with <code>ERROR</code>) during step 1 or 2, the trace processing
161 graph is considered <strong>faulty</strong>: you cannot use it anymore.
162 The only functions you can call with a faulty graph are
163 bt_graph_get_ref() and bt_graph_put_ref().
165 <h2>\anchor api-graph-lc-add Add components</h2>
167 Adding a \bt_comp to a trace processing graph is also known as
168 <em>instantiating a \bt_comp_cls</em> because the graph must first
169 create the component from its class before adding it.
171 Because component and component class C types are
172 \ref api-fund-c-typing "highly specific", there are six functions
173 to add a component to a trace processing graph:
176 <dt>Source component</dt>
179 <dt>Without initialization method data</dt>
180 <dd>bt_graph_add_source_component()</dd>
182 <dt>With initialization method data</dt>
183 <dd>bt_graph_add_source_component_with_initialize_method_data()</dd>
187 <dt>Filter component</dt>
190 <dt>Without initialization method data</dt>
191 <dd>bt_graph_add_filter_component()</dd>
193 <dt>With initialization method data</dt>
194 <dd>bt_graph_add_filter_component_with_initialize_method_data()</dd>
198 <dt>Sink component</dt>
201 <dt>Without initialization method data</dt>
202 <dd>bt_graph_add_sink_component()</dd>
204 <dt>With initialization method data</dt>
205 <dd>bt_graph_add_sink_component_with_initialize_method_data()</dd>
210 The <code>*_with_initialize_method_data()</code> versions can pass a
211 custom, \bt_voidp pointer to the component's
212 \ref api-comp-cls-dev-meth-init "initialization method".
213 The other versions pass \c NULL as this parameter.
215 All the functions above accept the same parameters:
218 Trace processing graph to which to add the created component.
219 @param[in] component_class
220 Class to instantiate within \bt_p{graph}.
222 Unique name of the component to add within \bt_p{graph}.
224 Initialization parameters to use when creating the component.
225 @param[in] logging_level
226 Initial logging level of the component to create.
227 @param[out] component
228 <strong>On success</strong>, \bt_p{*component} is the created
231 Once you have the created and added component (\bt_p{*component}),
232 you can borrow its \bt_p_port to
233 \ref api-graph-lc-connect "connect them".
235 You can add as many components as needed to a trace processing graph,
236 but they must all have a unique name.
238 <h3>\anchor api-graph-lc-add-ss Add a simple sink component</h3>
240 To add a very basic \bt_sink_comp which has a single \bt_iport and
241 creates a single \bt_msg_iter when the trace processing graph becomes
242 configured, use bt_graph_add_simple_sink_component(). When you call
243 this function, you pass three user functions:
246 <dt>\bt_dt_opt Initialization</dt>
248 Called when the trace processing graph becomes
249 configured and when the sink component created its single
252 You can do an initial action with the message iterator such as
253 making it seek a specific point in time or getting messages.
258 Called every time the sink component's
259 \ref api-comp-cls-dev-meth-consume "consuming method" is called.
261 You can get the next messages from the component's message
262 iterator and process them.
265 <dt>\bt_dt_opt Finalization</dt>
267 Called when the sink component is finalized.
271 The three functions above receive, as their last parameter, the user
272 data you passed to bt_graph_add_simple_sink_component() .
274 <h2>\anchor api-graph-lc-connect Connect component ports</h2>
276 When you \ref api-graph-lc-add "add a component" to a trace processing
277 graph with one of the <code>bt_graph_add_*_component*()</code>
278 functions, the function sets \bt_p{*component} to the
279 created and added component.
281 With such a \bt_comp, you can borrow one of its \bt_p_port by index or
284 Connect two component ports within a trace processing graph with
285 bt_graph_connect_ports().
287 After you connect component ports, you can still
288 \ref api-graph-lc-add "add" more components to the graph, and then
291 You don't need to connect all the available ports of a given component,
292 depending on the trace processing task you need to perform. However,
293 when you \ref api-graph-lc-run "run" the trace processing graph:
295 - At least one \bt_oport of any \bt_src_comp must be connected.
296 - At least one \bt_iport and one output port of any \bt_flt_comp must
298 - At least one input port of any \bt_sink_comp must be connected.
300 <h2>\anchor api-graph-lc-run Run</h2>
302 When you are done configuring a trace processing graph, you can run it
305 bt_graph_run() does \em not return until one of:
307 - All the sink components are ended: bt_graph_run() returns
308 #BT_GRAPH_RUN_STATUS_OK.
310 - One of the sink component returns an error:
311 bt_graph_run() returns #BT_GRAPH_RUN_STATUS_ERROR or
312 #BT_GRAPH_RUN_STATUS_MEMORY_ERROR.
314 - One of the sink component returns "try again":
315 bt_graph_run() returns #BT_GRAPH_RUN_STATUS_AGAIN.
317 In that case, you can call bt_graph_run() again later, usually after
318 waiting for some time.
320 This feature exists to allow blocking operations within components
321 to be postponed until they don't block. The graph user can perform
322 other tasks instead of the graph's thread blocking.
324 - The trace processing graph is interrupted (see
325 bt_graph_borrow_default_interrupter() and bt_graph_add_interrupter()):
326 bt_graph_run() returns #BT_GRAPH_RUN_STATUS_AGAIN.
328 Check the \bt_intr's state with bt_interrupter_is_set() to
329 distinguish between a sink component returning "try again" and
330 the trace processing graph getting interrupted.
332 If you want to make a single sink component consume and process a few
333 \bt_p_msg before controlling the thread again, use bt_graph_run_once()
334 instead of bt_graph_run().
336 <h1>Standard \bt_name component classes</h1>
338 The \bt_name project ships with project \bt_p_plugin which provide
339 "standard" \bt_p_comp_cls.
341 Those standard component classes can be useful in many trace processing
342 graph topologies. They are:
345 <dt>\c ctf plugin</dt>
348 <dt>\c fs source component class</dt>
351 <a href="https://diamon.org/ctf/">CTF</a> trace on the file
352 system and emits the \bt_p_msg of their data stream files.
354 See \bt_man{babeltrace2-source.ctf.fs,7}.
357 <dt>\c lttng-live source component class</dt>
359 Connects to an <a href="https://lttng.org/">LTTng</a> relay
360 daemon and emits the messages of the received CTF data streams.
362 See \bt_man{babeltrace2-source.ctf.lttng-live,7}.
365 <dt>\c fs sink component class</dt>
367 Writes the consumed messages as one or more CTF traces on the
370 See \bt_man{babeltrace2-sink.ctf.fs,7}.
375 <dt>\c lttng-utils plugin</dt>
378 <dt>\c debug-info filter component class</dt>
380 Adds debugging information to compatible LTTng event messages.
382 This component class is only available if the project was
383 built with the <code>\-\-enable-debug-info</code>
384 configuration option.
386 See \bt_man{babeltrace2-filter.lttng-utils.debug-info,7}.
391 <dt>\c text plugin</dt>
394 <dt>\c dmesg source component class</dt>
396 Reads the lines of a Linux kernel ring buffer, that is, the
398 <a href="http://man7.org/linux/man-pages/man1/dmesg.1.html"><code>dmesg</code></a>
399 tool, and emits each line as an \bt_ev_msg.
401 See \bt_man{babeltrace2-source.text.dmesg,7}.
404 <dt>\c details sink component class</dt>
406 Deterministically prints the messages it consumes with details
407 to the standard output.
409 See \bt_man{babeltrace2-sink.text.details,7}.
412 <dt>\c pretty sink component class</dt>
414 Pretty-prints the messages it consumes to the standard output or
417 This is equivalent to the \c text output format of the
418 <a href="https://manpages.debian.org/stretch/babeltrace/babeltrace.1.en.html">Babeltrace 1
419 command-line tool</a>.
421 See \bt_man{babeltrace2-sink.text.pretty,7}.
426 <dt>\c utils plugin</dt>
429 <dt>\c muxer filter component class</dt>
431 Muxes messages by time.
433 See \bt_man{babeltrace2-filter.utils.muxer,7}.
436 <dt>\c trimmer filter component class</dt>
438 Discards all the consumed messages with a time outside a given
439 time range, effectively "cutting" \bt_p_stream.
441 See \bt_man{babeltrace2-filter.utils.trimmer,7}.
444 <dt>\c counter sink component class</dt>
446 Prints the number of consumed messages, either once at the end
447 or periodically, to the standard output.
449 See \bt_man{babeltrace2-sink.utils.counter,7}.
452 <dt>\c dummy sink component class</dt>
454 Consumes messages and discards them (does nothing with them).
456 This is useful for testing and benchmarking a trace processing
457 graph application, for example.
459 See \bt_man{babeltrace2-sink.utils.dummy,7}.
465 To access such a component class, get its plugin by name with
466 bt_plugin_find() and then borrow the component class by name
467 with bt_plugin_borrow_source_component_class_by_name_const(),
468 bt_plugin_borrow_filter_component_class_by_name_const(), or
469 bt_plugin_borrow_sink_component_class_by_name_const().
474 const bt_plugin *plugin;
476 if (bt_plugin_find("utils", BT_TRUE, BT_TRUE, BT_TRUE, BT_TRUE, BT_TRUE,
477 &plugin) != BT_PLUGIN_FIND_STATUS_OK) {
481 const bt_component_class_filter *muxer_component_class =
482 bt_plugin_borrow_filter_component_class_by_name_const(plugin, "muxer");
484 if (!muxer_component_class) {
489 <h1>\anchor api-graph-listeners Listeners</h1>
491 A \bt_comp can add a \bt_port:
493 - At initialization time, that is, when you call one of the
494 <code>bt_graph_add_*_component*()</code> functions.
496 - When one of its ports gets connected, that is, when you call
497 bt_graph_connect_ports().
499 To get notified when any component of a given trace processing
500 graph adds a port, add one or more "port
501 added" listeners to the graph with:
503 - bt_graph_add_source_component_output_port_added_listener()
504 - bt_graph_add_filter_component_input_port_added_listener()
505 - bt_graph_add_filter_component_output_port_added_listener()
506 - bt_graph_add_sink_component_input_port_added_listener()
508 Within a "port added" listener function, you can
509 \ref api-graph-lc-add "add more components"
510 and \ref api-graph-lc-connect "connect more component ports".
519 @typedef struct bt_graph bt_graph;
522 Trace processing graph.
534 Creates a default, empty trace processing graph honouring version
535 \bt_p{mip_version} of the \bt_mip.
537 On success, the returned graph contains no components (see
538 \ref api-graph-lc-add "Add components").
540 The graph is configured as operating following version
541 \bt_p{mip_version} of the Message Interchange Protocol, so that
542 bt_self_component_get_graph_mip_version() returns this version when
546 As of \bt_name_version_min_maj, the only available MIP version is 0.
548 The returned graph has a default \bt_intr. Any \bt_comp you add with the
549 <code>bt_graph_add_*_component*()</code> functions and all their
550 \bt_p_msg_iter also have this same default interrupter. Borrow the graph's
551 default interrupter with bt_graph_borrow_default_interrupter().
553 @param[in] mip_version
554 Version of the Message Interchange Protocol to use within the
558 New trace processing graph reference, or \c NULL on memory error.
561 \bt_p{mip_version} is 0.
563 extern bt_graph
*bt_graph_create(uint64_t mip_version
);
568 @name Component adding
575 <code>bt_graph_add_*_component*()</code> functions.
577 typedef enum bt_graph_add_component_status
{
582 BT_GRAPH_ADD_COMPONENT_STATUS_OK
= __BT_FUNC_STATUS_OK
,
588 BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
594 BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
595 } bt_graph_add_component_status
;
599 Alias of bt_graph_add_source_component_with_initialize_method_data()
600 with the \bt_p{initialize_method_data} parameter set to \c NULL.
602 extern bt_graph_add_component_status
603 bt_graph_add_source_component(bt_graph
*graph
,
604 const bt_component_class_source
*component_class
,
605 const char *name
, const bt_value
*params
,
606 bt_logging_level logging_level
,
607 const bt_component_source
**component
);
611 Creates a \bt_src_comp from the
612 \ref api-tir-comp-cls "class" \bt_p{component_class}
613 with the initialization parameters \bt_p{params}, the initialization
614 user data \bt_p{initialize_method_data}, and the initial
615 logging level \bt_p{logging_level}, adds it to the trace processing
616 graph \bt_p{graph} with the name \bt_p{name}, and sets
617 \bt_p{*component} to the resulting component.
619 See \ref api-graph-lc-add "Add components" to learn more about adding
620 components to a trace processing graph.
622 This function calls the source component's
623 \ref api-comp-cls-dev-meth-init "initialization method" after
626 The created source component's initialization method receives:
628 - \bt_p{params} as its own \bt_p{params} parameter (or an empty
629 \bt_map_val if \bt_p{params} is \c NULL).
631 - \bt_p{initialize_method_data} as its own \bt_p{initialize_method_data}
634 The created source component can get its logging level
635 (\bt_p{logging_level}) with bt_component_get_logging_level().
638 Trace processing graph to which to add the created source component.
639 @param[in] component_class
640 Class to instantiate within \bt_p{graph}.
642 Unique name, within \bt_p{graph}, of the component to create.
645 Initialization parameters to use when creating the source component.
647 Can be \c NULL, in which case the created source component's
648 initialization method receives an empty \bt_map_val as its
649 \bt_p{params} parameter.
651 @param[in] initialize_method_data
652 User data passed as is to the created source component's
653 initialization method.
654 @param[in] logging_level
655 Initial logging level of the source component to create.
656 @param[out] component
657 <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
658 a \em borrowed reference of the created source component.
660 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
662 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
664 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
665 Other error, for example, the created source component's
666 initialization method failed.
668 @bt_pre_not_null{graph}
669 @bt_pre_graph_not_configured{graph}
670 @bt_pre_graph_not_faulty{graph}
671 @bt_pre_not_null{component_class}
672 @bt_pre_not_null{name}
674 No other component within \bt_p{graph} has the name \bt_p{name}.
676 \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
679 @bt_post_success_frozen{component_class}
680 @bt_post_success_frozen{params}
682 extern bt_graph_add_component_status
683 bt_graph_add_source_component_with_initialize_method_data(
685 const bt_component_class_source
*component_class
,
686 const char *name
, const bt_value
*params
,
687 void *initialize_method_data
, bt_logging_level logging_level
,
688 const bt_component_source
**component
);
692 Alias of bt_graph_add_filter_component_with_initialize_method_data()
693 with the \bt_p{initialize_method_data} parameter set to \c NULL.
695 extern bt_graph_add_component_status
696 bt_graph_add_filter_component(bt_graph
*graph
,
697 const bt_component_class_filter
*component_class
,
698 const char *name
, const bt_value
*params
,
699 bt_logging_level logging_level
,
700 const bt_component_filter
**component
);
704 Creates a \bt_flt_comp from the
705 \ref api-tir-comp-cls "class" \bt_p{component_class}
706 with the initialization parameters \bt_p{params}, the initialization
707 user data \bt_p{initialize_method_data}, and the initial
708 logging level \bt_p{logging_level}, adds it to the trace processing
709 graph \bt_p{graph} with the name \bt_p{name}, and sets
710 \bt_p{*component} to the resulting component.
712 See \ref api-graph-lc-add "Add components" to learn more about adding
713 components to a trace processing graph.
715 This function calls the filter component's
716 \ref api-comp-cls-dev-meth-init "initialization method" after
719 The created filter component's initialization method receives:
721 - \bt_p{params} as its own \bt_p{params} parameter (or an empty
722 \bt_map_val if \bt_p{params} is \c NULL).
724 - \bt_p{initialize_method_data} as its own \bt_p{initialize_method_data}
727 The created filter component can get its logging level
728 (\bt_p{logging_level}) with bt_component_get_logging_level().
731 Trace processing graph to which to add the created filter component.
732 @param[in] component_class
733 Class to instantiate within \bt_p{graph}.
735 Unique name, within \bt_p{graph}, of the component to create.
738 Initialization parameters to use when creating the filter component.
740 Can be \c NULL, in which case the created filter component's
741 initialization method receives an empty \bt_map_val as its
742 \bt_p{params} parameter.
744 @param[in] initialize_method_data
745 User data passed as is to the created filter component's
746 initialization method.
747 @param[in] logging_level
748 Initial logging level of the filter component to create.
749 @param[out] component
750 <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
751 a \em borrowed reference of the created filter component.
753 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
755 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
757 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
758 Other error, for example, the created filter component's
759 initialization method failed.
761 @bt_pre_not_null{graph}
762 @bt_pre_graph_not_configured{graph}
763 @bt_pre_graph_not_faulty{graph}
764 @bt_pre_not_null{component_class}
765 @bt_pre_not_null{name}
767 No other component within \bt_p{graph} has the name \bt_p{name}.
769 \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
772 @bt_post_success_frozen{component_class}
773 @bt_post_success_frozen{params}
775 extern bt_graph_add_component_status
776 bt_graph_add_filter_component_with_initialize_method_data(
778 const bt_component_class_filter
*component_class
,
779 const char *name
, const bt_value
*params
,
780 void *initialize_method_data
, bt_logging_level logging_level
,
781 const bt_component_filter
**component
);
785 Alias of bt_graph_add_sink_component_with_initialize_method_data()
786 with the \bt_p{initialize_method_data} parameter set to \c NULL.
788 extern bt_graph_add_component_status
789 bt_graph_add_sink_component(
790 bt_graph
*graph
, const bt_component_class_sink
*component_class
,
791 const char *name
, const bt_value
*params
,
792 bt_logging_level logging_level
,
793 const bt_component_sink
**component
);
797 Creates a \bt_sink_comp from the
798 \ref api-tir-comp-cls "class" \bt_p{component_class}
799 with the initialization parameters \bt_p{params}, the initialization
800 user data \bt_p{initialize_method_data}, and the initial
801 logging level \bt_p{logging_level}, adds it to the trace processing
802 graph \bt_p{graph} with the name \bt_p{name}, and sets
803 \bt_p{*component} to the resulting component.
805 See \ref api-graph-lc-add "Add components" to learn more about adding
806 components to a trace processing graph.
808 This function calls the sink component's
809 \ref api-comp-cls-dev-meth-init "initialization method" after
812 The created sink component's initialization method receives:
814 - \bt_p{params} as its own \bt_p{params} parameter (or an empty
815 \bt_map_val if \bt_p{params} is \c NULL).
817 - \bt_p{initialize_method_data} as its own \bt_p{initialize_method_data}
820 The created sink component can get its logging level
821 (\bt_p{logging_level}) with bt_component_get_logging_level().
824 Trace processing graph to which to add the created sink component.
825 @param[in] component_class
826 Class to instantiate within \bt_p{graph}.
828 Unique name, within \bt_p{graph}, of the component to create.
831 Initialization parameters to use when creating the sink component.
833 Can be \c NULL, in which case the created sink component's
834 initialization method receives an empty \bt_map_val as its
835 \bt_p{params} parameter.
837 @param[in] initialize_method_data
838 User data passed as is to the created sink component's
839 initialization method.
840 @param[in] logging_level
841 Initial logging level of the sink component to create.
842 @param[out] component
843 <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
844 a \em borrowed reference of the created sink component.
846 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
848 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
850 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
851 Other error, for example, the created sink component's
852 initialization method failed.
854 @bt_pre_not_null{graph}
855 @bt_pre_graph_not_configured{graph}
856 @bt_pre_graph_not_faulty{graph}
857 @bt_pre_not_null{component_class}
858 @bt_pre_not_null{name}
860 No other component within \bt_p{graph} has the name \bt_p{name}.
862 \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
865 @bt_post_success_frozen{component_class}
866 @bt_post_success_frozen{params}
868 extern bt_graph_add_component_status
869 bt_graph_add_sink_component_with_initialize_method_data(
870 bt_graph
*graph
, const bt_component_class_sink
*component_class
,
871 const char *name
, const bt_value
*params
,
872 void *initialize_method_data
, bt_logging_level logging_level
,
873 const bt_component_sink
**component
);
878 @name Simple sink component adding
884 Status codes for the #bt_graph_simple_sink_component_initialize_func
887 typedef enum bt_graph_simple_sink_component_initialize_func_status
{
892 BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_OK
= __BT_FUNC_STATUS_OK
,
898 BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
904 BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
905 } bt_graph_simple_sink_component_initialize_func_status
;
909 User initialization function for
910 bt_graph_add_simple_sink_component().
912 Such an initialization function is called when the trace processing
913 graph becomes configured and when the simple sink component has created
914 its single \bt_msg_iter. This occurs the first time you call
915 bt_graph_run() or bt_graph_run_once() on the trace processing graph.
917 See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
918 about adding a simple component to a trace processing graph.
920 @param[in] message_iterator
922 Simple sink component's upstream message iterator.
924 This user function is free to get the message iterator's next
925 message or to make it seek.
928 User data, as passed as the \bt_p{user_data} parameter of
929 bt_graph_add_simple_sink_component().
931 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_OK
933 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_MEMORY_ERROR
935 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_ERROR
938 @bt_pre_not_null{message_iterator}
941 The reference count of \bt_p{message_iterator} is not changed.
943 @sa bt_graph_add_simple_sink_component() —
944 Creates and adds a simple sink component to a trace processing
947 typedef bt_graph_simple_sink_component_initialize_func_status
948 (*bt_graph_simple_sink_component_initialize_func
)(
949 bt_message_iterator
*message_iterator
,
954 Status codes for the #bt_graph_simple_sink_component_consume_func
957 typedef enum bt_graph_simple_sink_component_consume_func_status
{
962 BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK
= __BT_FUNC_STATUS_OK
,
968 BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END
= __BT_FUNC_STATUS_END
,
974 BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
980 BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
986 BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
987 } bt_graph_simple_sink_component_consume_func_status
;
991 User consuming function for bt_graph_add_simple_sink_component().
993 Such a consuming function is called when the simple sink component's own
994 \ref api-comp-cls-dev-meth-consume "consuming method" is called. This
995 occurs in a loop within bt_graph_run() or when it's this sink
996 component's turn to consume in
999 See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
1000 about adding a simple component to a trace processing graph.
1002 If you are not done consuming messages, return
1003 #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK.
1005 If you are done consuming messages, return
1006 #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END.
1008 If you wish to avoid a blocking operation and make
1009 bt_graph_run() or bt_graph_run_once() aware, return
1010 #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN.
1012 @param[in] message_iterator
1014 Simple sink component's upstream message iterator.
1016 This user function is free to get the message iterator's next
1017 message or to make it seek.
1019 @param[in] user_data
1020 User data, as passed as the \bt_p{user_data} parameter of
1021 bt_graph_add_simple_sink_component().
1023 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK
1025 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END
1027 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN
1029 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_MEMORY_ERROR
1031 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_ERROR
1034 @bt_pre_not_null{message_iterator}
1037 The reference count of \bt_p{message_iterator} is not changed.
1039 @sa bt_graph_add_simple_sink_component() —
1040 Creates and adds a simple sink component to a trace processing
1043 typedef bt_graph_simple_sink_component_consume_func_status
1044 (*bt_graph_simple_sink_component_consume_func
)(
1045 bt_message_iterator
*message_iterator
,
1050 User finalization function for bt_graph_add_simple_sink_component().
1052 Such a finalization function is called when the simple sink component
1053 is finalized. This occurs when the trace processing graph is destroyed
1054 (you put its last strong \ref api-fund-shared-object "reference"
1055 with bt_graph_put_ref()).
1057 See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
1058 about adding a simple component to a trace processing graph.
1060 @param[in] user_data
1061 User data, as passed as the \bt_p{user_data} parameter of
1062 bt_graph_add_simple_sink_component().
1066 @sa bt_graph_add_simple_sink_component() —
1067 Creates and adds a simple sink component to a trace processing
1070 typedef void (*bt_graph_simple_sink_component_finalize_func
)(void *user_data
);
1074 Creates a simple \bt_sink_comp, adds it to the trace processing
1075 graph \bt_p{graph} with the name \bt_p{name}, and sets
1076 \bt_p{*component} to the resulting component.
1078 See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
1079 about adding a simple component to a trace processing graph.
1081 \bt_p{initialize_func} (if not \c NULL), \bt_p{consume_func},
1082 and \bt_p{finalize_func} (if not \c NULL) receive \bt_p{user_data}
1083 as their own \bt_p{user_data} parameter.
1086 Trace processing graph to which to add the created simple sink
1089 Unique name, within \bt_p{graph}, of the component to create.
1090 @param[in] initialize_func
1092 User initialization function.
1096 @param[in] consume_func
1097 User consuming function.
1098 @param[in] finalize_func
1100 User finalization function.
1104 @param[in] user_data
1105 User data to pass as the \bt_p{user_data} parameter of
1106 \bt_p{initialize_func}, \bt_p{consume_func}, and
1107 \bt_p{finalize_func}.
1108 @param[out] component
1109 <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
1110 a \em borrowed reference of the created simple sink component.
1112 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
1114 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
1116 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
1117 Other error, for example, the created sink component's
1118 \ref api-comp-cls-dev-meth-init "initialization method" failed.
1120 @bt_pre_not_null{graph}
1121 @bt_pre_graph_not_configured{graph}
1122 @bt_pre_graph_not_faulty{graph}
1123 @bt_pre_not_null{name}
1125 No other component within \bt_p{graph} has the name \bt_p{name}.
1126 @bt_pre_not_null{consume_func}
1128 extern bt_graph_add_component_status
1129 bt_graph_add_simple_sink_component(bt_graph
*graph
, const char *name
,
1130 bt_graph_simple_sink_component_initialize_func initialize_func
,
1131 bt_graph_simple_sink_component_consume_func consume_func
,
1132 bt_graph_simple_sink_component_finalize_func finalize_func
,
1133 void *user_data
, const bt_component_sink
**component
);
1138 @name Component port connection
1144 Status codes for bt_graph_connect_ports().
1146 typedef enum bt_graph_connect_ports_status
{
1151 BT_GRAPH_CONNECT_PORTS_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1157 BT_GRAPH_CONNECT_PORTS_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1163 BT_GRAPH_CONNECT_PORTS_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1164 } bt_graph_connect_ports_status
;
1168 Connects the \bt_oport \bt_p{upstream_port} to the \bt_iport
1169 \bt_p{downstream_port} within the trace processing graph
1170 \bt_p{graph}, and sets \bt_p{*connection} to the resulting
1173 See \ref api-graph-lc-connect "Connect component ports" to learn more
1174 about connecting ports within a trace processing graph.
1176 Both \bt_p{upstream_port} and \bt_p{downstream_port} must be
1177 unconnected (bt_port_is_connected() returns #BT_FALSE) when you call
1181 Trace processing graph containing the \bt_p_comp to which belong
1182 \bt_p{upstream_port} and \bt_p{downstream_port}.
1183 @param[in] upstream_port
1184 \bt_c_oport to connect to \bt_p{downstream_port}.
1185 @param[in] downstream_port
1186 \bt_c_iport to connect to \bt_p{upstream_port}.
1187 @param[in] connection
1188 <strong>On success, if not \c NULL</strong>, \bt_p{*connection} is
1189 a \em borrowed reference of the resulting \bt_conn.
1191 @retval #BT_GRAPH_CONNECT_PORTS_STATUS_OK
1193 @retval #BT_GRAPH_CONNECT_PORTS_STATUS_MEMORY_ERROR
1195 @retval #BT_GRAPH_CONNECT_PORTS_STATUS_ERROR
1198 @bt_pre_not_null{graph}
1199 @bt_pre_graph_not_configured{graph}
1200 @bt_pre_graph_not_faulty{graph}
1201 @bt_pre_not_null{upstream_port}
1203 \bt_p{graph} contains the component of \bt_p{upstream_port},
1204 as returned by bt_port_borrow_component_const().
1206 \bt_p{upstream_port} is unconnected
1207 (bt_port_is_connected() returns #BT_FALSE).
1208 @bt_pre_not_null{downstream_port}
1210 \bt_p{graph} contains the component of \bt_p{downstream_port},
1211 as returned by bt_port_borrow_component_const().
1213 \bt_p{downstream_port} is unconnected
1214 (bt_port_is_connected() returns #BT_FALSE).
1216 Connecting \bt_p{upstream_port} to \bt_p{downstream_port} does not
1217 form a connection cycle within \bt_p{graph}.
1219 extern bt_graph_connect_ports_status
bt_graph_connect_ports(bt_graph
*graph
,
1220 const bt_port_output
*upstream_port
,
1221 const bt_port_input
*downstream_port
,
1222 const bt_connection
**connection
);
1233 Status codes for bt_graph_run().
1235 typedef enum bt_graph_run_status
{
1240 BT_GRAPH_RUN_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1246 BT_GRAPH_RUN_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
1252 BT_GRAPH_RUN_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1258 BT_GRAPH_RUN_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1259 } bt_graph_run_status
;
1263 Runs the trace processing graph \bt_p{graph}, calling each
1265 \ref api-comp-cls-dev-meth-consume "consuming method" in a round
1266 robin fashion until they are all done consuming or an exception
1269 See \ref api-graph-lc-run "Run" to learn more about running a trace
1272 This function does \em not return until one of:
1274 - All the sink components are ended, in which case this function
1275 returns #BT_GRAPH_RUN_STATUS_OK.
1277 - One of the sink component returns an error, in which case this
1278 function returns #BT_GRAPH_RUN_STATUS_ERROR or
1279 #BT_GRAPH_RUN_STATUS_MEMORY_ERROR.
1281 - One of the sink component returns "try again", in which case
1282 this function returns #BT_GRAPH_RUN_STATUS_AGAIN.
1284 In that case, you can call this function again later, usually after
1285 waiting for some time.
1287 This feature exists to allow blocking operations within components
1288 to be postponed until they don't block. The graph user can perform
1289 other tasks instead of the graph's thread blocking.
1291 - \bt_p{graph} is interrupted (see bt_graph_borrow_default_interrupter()
1292 and bt_graph_add_interrupter()), in which case this function returns
1293 #BT_GRAPH_RUN_STATUS_AGAIN.
1295 Check the \bt_intr's state with bt_interrupter_is_set() to
1296 distinguish between a sink component returning "try again" and
1297 \bt_p{graph} getting interrupted.
1299 To make a single sink component consume, then get the thread's control
1300 back, use bt_graph_run_once().
1302 When you call this function or bt_graph_run_once() for the first time,
1303 \bt_p{graph} becomes <em>configured</em>. See
1304 \ref api-graph-lc "Trace processing graph life cycle"
1305 to learn what happens when a trace processing graph becomes configured,
1306 and what you can and cannot do with a configured graph.
1309 Trace processing graph to run.
1311 @retval #BT_GRAPH_RUN_STATUS_OK
1313 @retval #BT_GRAPH_RUN_STATUS_AGAIN
1315 @retval #BT_GRAPH_RUN_STATUS_MEMORY_ERROR
1317 @retval #BT_GRAPH_RUN_STATUS_ERROR
1320 @bt_pre_not_null{graph}
1321 @bt_pre_graph_not_faulty{graph}
1323 For each \bt_src_comp within \bt_p{graph}, at least one \bt_oport
1326 For each \bt_flt_comp within \bt_p{graph}, at least one \bt_iport
1327 and one \bt_iport are connected.
1329 For each \bt_sink_comp within \bt_p{graph}, at least one \bt_iport
1332 \bt_p{graph} contains at least one sink component.
1334 @sa bt_graph_run_once() —
1335 Calls a single trace processing graph's sink component's consuming
1338 extern bt_graph_run_status
bt_graph_run(bt_graph
*graph
);
1342 Status codes for bt_graph_run().
1344 typedef enum bt_graph_run_once_status
{
1349 BT_GRAPH_RUN_ONCE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1353 All sink components are finished processing.
1355 BT_GRAPH_RUN_ONCE_STATUS_END
= __BT_FUNC_STATUS_END
,
1361 BT_GRAPH_RUN_ONCE_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
1367 BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1373 BT_GRAPH_RUN_ONCE_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1374 } bt_graph_run_once_status
;
1378 Calls the \ref api-comp-cls-dev-meth-consume "consuming method" of
1379 the next non-ended \bt_sink_comp to make consume within the trace
1380 processing graph \bt_p{graph}.
1382 See \ref api-graph-lc-run "Run" to learn more about running a trace
1385 This function makes the \em next non-ended sink component consume. For
1386 example, if \bt_p{graph} has two non-ended sink components A and B:
1388 - Calling bt_graph_run_once() makes sink component A consume.
1389 - Calling bt_graph_run_once() again makes sink component B consume.
1390 - Calling bt_graph_run_once() again makes sink component A consume.
1393 Considering this, if \bt_p{graph} contains a single non-ended sink
1394 component, this function \em always makes this sink component consume.
1396 If the sink component's consuming method:
1400 <dd>This function returns #BT_GRAPH_RUN_ONCE_STATUS_OK.</dd>
1402 <dt>Returns "try again"</dt>
1403 <dd>This function returns #BT_GRAPH_RUN_ONCE_STATUS_AGAIN.</dd>
1407 This function returns #BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR
1408 or #BT_GRAPH_RUN_ONCE_STATUS_ERROR.
1412 When all the sink components of \bt_p{graph} are finished processing
1413 (ended), this function returns #BT_GRAPH_RUN_ONCE_STATUS_END.
1415 bt_graph_run() calls this function in a loop until are the sink
1416 components are ended or an exception occurs.
1418 When you call this function or bt_graph_run() for the first time,
1419 \bt_p{graph} becomes <em>configured</em>. See
1420 \ref api-graph-lc "Trace processing graph life cycle"
1421 to learn what happens when a trace processing graph becomes configured,
1422 and what you can and cannot do with a configured graph.
1425 Trace processing graph of which to make the next sink component
1428 @retval #BT_GRAPH_RUN_ONCE_STATUS_OK
1430 @retval #BT_GRAPH_RUN_ONCE_STATUS_END
1431 All sink components are finished processing.
1432 @retval #BT_GRAPH_RUN_ONCE_STATUS_AGAIN
1434 @retval #BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR
1436 @retval #BT_GRAPH_RUN_ONCE_STATUS_ERROR
1439 @bt_pre_not_null{graph}
1440 @bt_pre_graph_not_faulty{graph}
1442 @sa bt_graph_run() —
1443 Runs a trace processing graph, making all its sink components
1444 consume in a round robin fashion.
1446 extern bt_graph_run_once_status
bt_graph_run_once(bt_graph
*graph
);
1457 Status codes for bt_graph_add_interrupter().
1459 typedef enum bt_graph_add_interrupter_status
{
1464 BT_GRAPH_ADD_INTERRUPTER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1470 BT_GRAPH_ADD_INTERRUPTER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1471 } bt_graph_add_interrupter_status
;
1475 Adds the \bt_intr \bt_p{interrupter} to all the current and future
1476 \bt_p_sink_comp and \bt_p_msg_iter of the trace processing graph
1477 \bt_p{graph}, as well as to the graph itself.
1479 Sink components can check whether or not they are interrupted
1480 with bt_self_component_sink_is_interrupted().
1482 Message iterators can check whether or not they are interrupted
1483 with bt_self_message_iterator_is_interrupted().
1485 The bt_graph_run() loop intermittently checks whether or not any of the
1486 graph's interrupters is set. If so, bt_graph_run() returns
1487 #BT_GRAPH_RUN_STATUS_AGAIN.
1491 bt_graph_create() returns a trace processing graph which comes
1492 with its own <em>default interrupter</em>.
1494 Instead of adding your own interrupter to \bt_p{graph}, you can
1495 set its default interrupter with
1498 bt_interrupter_set(bt_graph_borrow_default_interrupter());
1503 Trace processing graph to which to add \bt_p{interrupter}.
1504 @param[in] interrupter
1505 Interrupter to add to \bt_p{graph}.
1507 @retval #BT_GRAPH_ADD_INTERRUPTER_STATUS_OK
1509 @retval #BT_GRAPH_ADD_INTERRUPTER_STATUS_MEMORY_ERROR
1512 @bt_pre_not_null{graph}
1513 @bt_pre_graph_not_faulty{graph}
1514 @bt_pre_not_null{interrupter}
1516 @sa bt_graph_borrow_default_interrupter() —
1517 Borrows the default interrupter from a trace processing graph.
1519 extern bt_graph_add_interrupter_status
bt_graph_add_interrupter(bt_graph
*graph
,
1520 const bt_interrupter
*interrupter
);
1524 Borrows the default \bt_intr from the trace processing graph
1528 Trace processing graph from which to borrow the default interrupter.
1532 \em Borrowed reference of the default interrupter of \bt_p{graph}.
1534 The returned pointer remains valid as long as \bt_p{graph} exists.
1537 @bt_pre_not_null{graph}
1539 @sa bt_graph_add_interrupter() —
1540 Adds an interrupter to a trace processing graph.
1542 extern bt_interrupter
*bt_graph_borrow_default_interrupter(bt_graph
*graph
);
1553 Status codes for the
1554 <code>bt_graph_add_*_component_*_port_added_listener()</code>
1557 typedef enum bt_graph_add_listener_status
{
1562 BT_GRAPH_ADD_LISTENER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1568 BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1569 } bt_graph_add_listener_status
;
1573 Status codes for the
1574 <code>bt_graph_*_component_*_port_added_listener_func()</code>
1577 typedef enum bt_graph_listener_func_status
{
1582 BT_GRAPH_LISTENER_FUNC_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1588 BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1594 BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1595 } bt_graph_listener_func_status
;
1600 bt_graph_add_filter_component_input_port_added_listener().
1602 Such a function is called whenever a \bt_flt_comp within a trace
1603 processing graph adds an \bt_iport during the graph
1604 \ref api-graph-lc "configuration" phase.
1606 See \ref api-graph-listeners "Listeners" to learn more.
1608 @param[in] component
1609 Filter component which added \bt_p{port}.
1611 Input port added by \bt_p{component}.
1612 @param[in] user_data
1613 User data, as passed as the \bt_p{user_data} parameter of
1614 bt_graph_add_filter_component_input_port_added_listener().
1616 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
1618 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
1620 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
1623 @bt_pre_not_null{component}
1624 @bt_pre_not_null{port}
1626 @sa bt_graph_add_filter_component_input_port_added_listener() —
1627 Adds a "filter component input port added" listener to a trace
1630 typedef bt_graph_listener_func_status
1631 (*bt_graph_filter_component_input_port_added_listener_func
)(
1632 const bt_component_filter
*component
,
1633 const bt_port_input
*port
, void *user_data
);
1637 Adds a \"\bt_flt_comp \bt_iport added\" listener to the trace
1638 processing graph \bt_p{graph}.
1640 Once this function returns, \bt_p{user_func} is called whenever a
1641 filter component adds an input port within \bt_p{graph}.
1643 See \ref api-graph-listeners "Listeners" to learn more.
1646 Trace processing graph to add the "filter component input port
1648 @param[in] user_func
1649 User function of the "filter component input port added" listener to
1650 add to \bt_p{graph}.
1651 @param[in] user_data
1652 User data to pass as the \bt_p{user_data} parameter of
1654 @param[out] listener_id
1655 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
1656 is the ID of the added listener within \bt_p{graph}.
1658 @retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
1660 @retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
1663 @bt_pre_not_null{graph}
1664 @bt_pre_graph_not_faulty{graph}
1665 @bt_pre_not_null{user_func}
1667 extern bt_graph_add_listener_status
1668 bt_graph_add_filter_component_input_port_added_listener(
1670 bt_graph_filter_component_input_port_added_listener_func user_func
,
1671 void *user_data
, bt_listener_id
*listener_id
);
1676 bt_graph_add_sink_component_input_port_added_listener().
1678 Such a function is called whenever a \bt_sink_comp within a trace
1679 processing graph adds an \bt_iport during the graph
1680 \ref api-graph-lc "configuration" phase.
1682 See \ref api-graph-listeners "Listeners" to learn more.
1684 @param[in] component
1685 Filter component which added \bt_p{port}.
1687 Input port added by \bt_p{component}.
1688 @param[in] user_data
1689 User data, as passed as the \bt_p{user_data} parameter of
1690 bt_graph_add_sink_component_input_port_added_listener().
1692 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
1694 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
1696 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
1699 @bt_pre_not_null{component}
1700 @bt_pre_not_null{port}
1702 @sa bt_graph_add_sink_component_input_port_added_listener() —
1703 Adds a "sink component input port added" listener to a trace
1706 typedef bt_graph_listener_func_status
1707 (*bt_graph_sink_component_input_port_added_listener_func
)(
1708 const bt_component_sink
*component
,
1709 const bt_port_input
*port
, void *user_data
);
1713 Adds a \"\bt_sink_comp \bt_iport added\" listener to the trace
1714 processing graph \bt_p{graph}.
1716 Once this function returns, \bt_p{user_func} is called whenever a
1717 sink component adds an input port within \bt_p{graph}.
1719 See \ref api-graph-listeners "Listeners" to learn more.
1722 Trace processing graph to add the "sink component input port
1724 @param[in] user_func
1725 User function of the "sink component input port added" listener to
1726 add to \bt_p{graph}.
1727 @param[in] user_data
1728 User data to pass as the \bt_p{user_data} parameter of
1730 @param[out] listener_id
1731 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
1732 is the ID of the added listener within \bt_p{graph}.
1734 @retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
1736 @retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
1739 @bt_pre_not_null{graph}
1740 @bt_pre_graph_not_faulty{graph}
1741 @bt_pre_not_null{user_func}
1743 extern bt_graph_add_listener_status
1744 bt_graph_add_sink_component_input_port_added_listener(
1746 bt_graph_sink_component_input_port_added_listener_func user_func
,
1747 void *user_data
, bt_listener_id
*listener_id
);
1752 bt_graph_add_source_component_output_port_added_listener().
1754 Such a function is called whenever a \bt_src_comp within a trace
1755 processing graph adds an \bt_oport during the graph
1756 \ref api-graph-lc "configuration" phase.
1758 See \ref api-graph-listeners "Listeners" to learn more.
1760 @param[in] component
1761 Filter component which added \bt_p{port}.
1763 Input port added by \bt_p{component}.
1764 @param[in] user_data
1765 User data, as passed as the \bt_p{user_data} parameter of
1766 bt_graph_add_source_component_output_port_added_listener().
1768 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
1770 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
1772 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
1775 @bt_pre_not_null{component}
1776 @bt_pre_not_null{port}
1778 @sa bt_graph_add_source_component_output_port_added_listener() —
1779 Adds a "source component output port added" listener to a trace
1782 typedef bt_graph_listener_func_status
1783 (*bt_graph_source_component_output_port_added_listener_func
)(
1784 const bt_component_source
*component
,
1785 const bt_port_output
*port
, void *user_data
);
1789 Adds a \"\bt_src_comp \bt_oport added\" listener to the trace
1790 processing graph \bt_p{graph}.
1792 Once this function returns, \bt_p{user_func} is called whenever a
1793 source component adds an output port within \bt_p{graph}.
1795 See \ref api-graph-listeners "Listeners" to learn more.
1798 Trace processing graph to add the "source component output port
1800 @param[in] user_func
1801 User function of the "source component output port added" listener
1802 to add to \bt_p{graph}.
1803 @param[in] user_data
1804 User data to pass as the \bt_p{user_data} parameter of
1806 @param[out] listener_id
1807 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
1808 is the ID of the added listener within \bt_p{graph}.
1810 @retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
1812 @retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
1815 @bt_pre_not_null{graph}
1816 @bt_pre_graph_not_faulty{graph}
1817 @bt_pre_not_null{user_func}
1819 extern bt_graph_add_listener_status
1820 bt_graph_add_source_component_output_port_added_listener(
1822 bt_graph_source_component_output_port_added_listener_func user_func
,
1823 void *user_data
, bt_listener_id
*listener_id
);
1828 bt_graph_add_filter_component_output_port_added_listener().
1830 Such a function is called whenever a \bt_flt_comp within a trace
1831 processing graph adds an \bt_oport during the graph
1832 \ref api-graph-lc "configuration" phase.
1834 See \ref api-graph-listeners "Listeners" to learn more.
1836 @param[in] component
1837 Filter component which added \bt_p{port}.
1839 Input port added by \bt_p{component}.
1840 @param[in] user_data
1841 User data, as passed as the \bt_p{user_data} parameter of
1842 bt_graph_add_filter_component_output_port_added_listener().
1844 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
1846 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
1848 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
1851 @bt_pre_not_null{component}
1852 @bt_pre_not_null{port}
1854 @sa bt_graph_add_filter_component_output_port_added_listener() —
1855 Adds a "filter component output port added" listener to a trace
1858 typedef bt_graph_listener_func_status
1859 (*bt_graph_filter_component_output_port_added_listener_func
)(
1860 const bt_component_filter
*component
,
1861 const bt_port_output
*port
, void *user_data
);
1865 Adds a \"\bt_flt_comp \bt_oport added\" listener to the trace
1866 processing graph \bt_p{graph}.
1868 Once this function returns, \bt_p{user_func} is called whenever a
1869 filter component adds an output port within \bt_p{graph}.
1871 See \ref api-graph-listeners "Listeners" to learn more.
1874 Trace processing graph to add the "filter component output port
1876 @param[in] user_func
1877 User function of the "filter component output port added" listener
1878 to add to \bt_p{graph}.
1879 @param[in] user_data
1880 User data to pass as the \bt_p{user_data} parameter of
1882 @param[out] listener_id
1883 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
1884 is the ID of the added listener within \bt_p{graph}.
1886 @retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
1888 @retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
1891 @bt_pre_not_null{graph}
1892 @bt_pre_graph_not_faulty{graph}
1893 @bt_pre_not_null{user_func}
1895 extern bt_graph_add_listener_status
1896 bt_graph_add_filter_component_output_port_added_listener(
1898 bt_graph_filter_component_output_port_added_listener_func user_func
,
1899 void *user_data
, bt_listener_id
*listener_id
);
1904 @name Reference count
1910 Increments the \ref api-fund-shared-object "reference count" of
1911 the trace processing graph \bt_p{graph}.
1915 Trace processing graph of which to increment the reference count.
1920 @sa bt_graph_put_ref() —
1921 Decrements the reference count of a trace processing graph.
1923 extern void bt_graph_get_ref(const bt_graph
*graph
);
1927 Decrements the \ref api-fund-shared-object "reference count" of
1928 the trace processing graph \bt_p{graph}.
1932 Trace processing graph of which to decrement the reference count.
1937 @sa bt_graph_get_ref() —
1938 Increments the reference count of a trace processing graph.
1940 extern void bt_graph_put_ref(const bt_graph
*graph
);
1944 Decrements the reference count of the trace processing graph
1945 \bt_p{_graph}, and then sets \bt_p{_graph} to \c NULL.
1949 Trace processing graph of which to decrement the reference count.
1951 Can contain \c NULL.
1954 @bt_pre_assign_expr{_graph}
1956 #define BT_GRAPH_PUT_REF_AND_RESET(_graph) \
1958 bt_graph_put_ref(_graph); \
1964 Decrements the reference count of the trace processing graph
1965 \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets
1966 \bt_p{_src} to \c NULL.
1968 This macro effectively moves a trace processing graph reference from the
1969 expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
1970 existing \bt_p{_dst} reference.
1974 Destination expression.
1976 Can contain \c NULL.
1982 Can contain \c NULL.
1985 @bt_pre_assign_expr{_dst}
1986 @bt_pre_assign_expr{_src}
1988 #define BT_GRAPH_MOVE_REF(_dst, _src) \
1990 bt_graph_put_ref(_dst); \
2003 #endif /* BABELTRACE2_GRAPH_GRAPH_H */