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 #ifndef __BT_IN_BABELTRACE_H
11 # error "Please include <babeltrace2/babeltrace.h> instead."
14 #include <babeltrace2/types.h>
15 #include <babeltrace2/logging.h>
22 @defgroup api-graph Graph
25 Trace processing graph.
27 A <strong><em>trace processing graph</em></strong> is a specialized
28 <a href="https://en.wikipedia.org/wiki/Filter_graph">filter graph</a>
29 to manipulate one or more traces.
31 Whereas the nodes of a multimedia filter graph typically exchange
32 video frames and audio samples, the nodes, or \bt_p_comp, of a trace
33 processing graph exchange immutable \bt_p_msg containing trace data.
35 The following illustration shows a basic trace processing graph which
36 converts many traces to a single log of pretty-printed lines:
38 @image html basic-convert-graph.png "Basic trace processing graph (conversion graph)."
40 In the illustrations above, notice that:
42 - The graph (blue) contains five components.
44 - Three source components (green) are connected to a single filter
47 There are five \bt_p_conn, from five \bt_p_oport
50 - The filter component is connected to a single sink component (red).
52 There's a single connection.
54 - Source components read external resources while the sink component
55 writes to the standard output or to a file.
57 - There are two source components having the same
58 \ref api-tir-comp-cls "class": <code>source.ctf.fs</code>.
60 - All components are instances of \bt_plugin-provided classes:
61 <code>babeltrace2-plugin-ctf.so</code>,
62 <code>user-plugin.so</code>,
63 <code>babeltrace2-plugin-utils.so</code>, and
64 <code>babeltrace2-plugin-text.so</code>.
66 Of course the topology can be much more complex if needed:
68 @image html complex-graph.png "Complex trace processing graph."
70 In a trace processing graph, \bt_p_comp are instances of \bt_p_comp_cls.
72 A \bt_plugin can provide a component class, but you can also create one
73 dynamically (see \ref api-comp-cls-dev).
75 The connections between component ports in a trace processing graph
76 indicate the needed topology to achieve a trace processing task. That
78 \bt_p_msg do not flow within connections. Instead, a source-to-sink
79 or filter-to-sink connection makes it
80 possible for a sink component to create a \bt_msg_iter on its end of
81 the connection (an \bt_iport). In turn, a filter component message
82 iterator can create other message iterators on one or more of the
83 component's input ports. For a single connection, there can exist
84 multiple message iterators.
86 A trace processing graph is a
87 \ref api-fund-shared-object "shared object": get a new reference with
88 bt_graph_get_ref() and put an existing reference with
91 The type of a trace processing graph is #bt_graph.
93 Create a default trace processing graph with bt_graph_create(). You need
94 to pass a \bt_mip (MIP) version number when you call this function.
96 \ref api-graph-lc "Trace processing graph life cycle"
97 to learn how to add components to the graph, connect their ports, and
100 To interrupt a \ref api-graph-lc-run "running" trace processing graph,
103 - Borrow the graph's default \bt_intr with
104 bt_graph_borrow_default_interrupter() and set it with
105 bt_interrupter_set().
107 When you call bt_graph_create(), the returned trace processing
108 graph has a default interrupter.
110 - Add your own interrupter with bt_graph_add_interrupter() \em before
111 you run the graph with bt_graph_run() or bt_graph_run_once().
113 Then, set the interrupter with bt_interrupter_set().
115 <h1>\anchor api-graph-lc Trace processing graph life cycle</h1>
117 The following diagram shows the life cycle of a trace processing
120 @image html graph-lifetime.png "Trace processing graph lifecycle."
122 After you create a default (empty) trace processing graph with
123 bt_graph_create(), there are three steps to make the trace processing
126 -# \ref api-graph-lc-add "Add components" to the graph.
127 -# \ref api-graph-lc-connect "Connect component ports".
128 -# \ref api-graph-lc-run "Run the graph".
130 You can repeat steps 1 and 2 before step 3, as connecting a
131 component \bt_port can make this \bt_comp create a new port:
132 you might want to add a component in reaction to this event
133 (see \ref api-graph-listeners "Listeners").
135 Steps 1 and 2 constitute the \em configuration phase of the trace
136 processing graph. The first time you call bt_graph_run() or
137 bt_graph_run_once() for a given graph (step 3), the graph becomes
138 <em>configured</em>, and it notifies the sink components as such so that
139 they can create their \bt_p_msg_iter.
141 Once a trace processing graph becomes configured:
143 - You cannot \ref api-graph-lc-add "add a component" to it.
145 - You cannot \ref api-graph-lc-connect "connect component ports".
147 - Components cannot add ports.
149 In general, as of \bt_name_version_min_maj:
151 - You cannot remove a component from a trace processing graph.
153 - You cannot end (remove) a port \bt_conn.
155 - Components cannot remove ports.
157 If \em any error occurs (a function returns a status code which ends
158 with <code>ERROR</code>) during step 1 or 2, the trace processing
159 graph is considered <strong>faulty</strong>: you cannot use it anymore.
160 The only functions you can call with a faulty graph are
161 bt_graph_get_ref() and bt_graph_put_ref().
163 <h2>\anchor api-graph-lc-add Add components</h2>
165 Adding a \bt_comp to a trace processing graph is also known as
166 <em>instantiating a \bt_comp_cls</em> because the graph must first
167 create the component from its class before adding it.
169 Because component and component class C types are
170 \ref api-fund-c-typing "highly specific", there are six functions
171 to add a component to a trace processing graph:
174 <dt>Source component</dt>
177 <dt>Without initialization method data</dt>
178 <dd>bt_graph_add_source_component()</dd>
180 <dt>With initialization method data</dt>
181 <dd>bt_graph_add_source_component_with_initialize_method_data()</dd>
185 <dt>Filter component</dt>
188 <dt>Without initialization method data</dt>
189 <dd>bt_graph_add_filter_component()</dd>
191 <dt>With initialization method data</dt>
192 <dd>bt_graph_add_filter_component_with_initialize_method_data()</dd>
196 <dt>Sink component</dt>
199 <dt>Without initialization method data</dt>
200 <dd>bt_graph_add_sink_component()</dd>
202 <dt>With initialization method data</dt>
203 <dd>bt_graph_add_sink_component_with_initialize_method_data()</dd>
208 The <code>*_with_initialize_method_data()</code> versions can pass a
209 custom, \bt_voidp pointer to the component's
210 \ref api-comp-cls-dev-meth-init "initialization method".
211 The other versions pass \c NULL as this parameter.
213 All the functions above accept the same parameters:
216 Trace processing graph to which to add the created component.
217 @param[in] component_class
218 Class to instantiate within \bt_p{graph}.
220 Unique name of the component to add within \bt_p{graph}.
222 Initialization parameters to use when creating the component.
223 @param[in] logging_level
224 Initial logging level of the component to create.
225 @param[out] component
226 <strong>On success</strong>, \bt_p{*component} is the created
229 Once you have the created and added component (\bt_p{*component}),
230 you can borrow its \bt_p_port to
231 \ref api-graph-lc-connect "connect them".
233 You can add as many components as needed to a trace processing graph,
234 but they must all have a unique name.
236 <h3>\anchor api-graph-lc-add-ss Add a simple sink component</h3>
238 To add a very basic \bt_sink_comp which has a single \bt_iport and
239 creates a single \bt_msg_iter when the trace processing graph becomes
240 configured, use bt_graph_add_simple_sink_component(). When you call
241 this function, you pass three user functions:
244 <dt>\bt_dt_opt Initialization</dt>
246 Called when the trace processing graph becomes
247 configured and when the sink component created its single
250 You can do an initial action with the message iterator such as
251 making it seek a specific point in time or getting messages.
256 Called every time the sink component's
257 \ref api-comp-cls-dev-meth-consume "consuming method" is called.
259 You can get the next messages from the component's message
260 iterator and process them.
263 <dt>\bt_dt_opt Finalization</dt>
265 Called when the sink component is finalized.
269 The three functions above receive, as their last parameter, the user
270 data you passed to bt_graph_add_simple_sink_component() .
272 <h2>\anchor api-graph-lc-connect Connect component ports</h2>
274 When you \ref api-graph-lc-add "add a component" to a trace processing
275 graph with one of the <code>bt_graph_add_*_component*()</code>
276 functions, the function sets \bt_p{*component} to the
277 created and added component.
279 With such a \bt_comp, you can borrow one of its \bt_p_port by index or
282 Connect two component ports within a trace processing graph with
283 bt_graph_connect_ports().
285 After you connect component ports, you can still
286 \ref api-graph-lc-add "add" more components to the graph, and then
289 You don't need to connect all the available ports of a given component,
290 depending on the trace processing task you need to perform. However,
291 when you \ref api-graph-lc-run "run" the trace processing graph:
293 - At least one \bt_oport of any \bt_src_comp must be connected.
294 - At least one \bt_iport and one output port of any \bt_flt_comp must
296 - At least one input port of any \bt_sink_comp must be connected.
298 <h2>\anchor api-graph-lc-run Run</h2>
300 When you are done configuring a trace processing graph, you can run it
303 bt_graph_run() does \em not return until one of:
305 - All the sink components are ended: bt_graph_run() returns
306 #BT_GRAPH_RUN_STATUS_OK.
308 - One of the sink component returns an error:
309 bt_graph_run() returns #BT_GRAPH_RUN_STATUS_ERROR or
310 #BT_GRAPH_RUN_STATUS_MEMORY_ERROR.
312 - One of the sink component returns "try again":
313 bt_graph_run() returns #BT_GRAPH_RUN_STATUS_AGAIN.
315 In that case, you can call bt_graph_run() again later, usually after
316 waiting for some time.
318 This feature exists to allow blocking operations within components
319 to be postponed until they don't block. The graph user can perform
320 other tasks instead of the graph's thread blocking.
322 - The trace processing graph is interrupted (see
323 bt_graph_borrow_default_interrupter() and bt_graph_add_interrupter()):
324 bt_graph_run() returns #BT_GRAPH_RUN_STATUS_AGAIN.
326 Check the \bt_intr's state with bt_interrupter_is_set() to
327 distinguish between a sink component returning "try again" and
328 the trace processing graph getting interrupted.
330 If you want to make a single sink component consume and process a few
331 \bt_p_msg before controlling the thread again, use bt_graph_run_once()
332 instead of bt_graph_run().
334 <h1>Standard \bt_name component classes</h1>
336 The \bt_name project ships with project \bt_p_plugin which provide
337 "standard" \bt_p_comp_cls.
339 Those standard component classes can be useful in many trace processing
340 graph topologies. They are:
343 <dt>\c ctf plugin</dt>
346 <dt>\c fs source component class</dt>
349 <a href="https://diamon.org/ctf/">CTF</a> trace on the file
350 system and emits the \bt_p_msg of their data stream files.
352 See \bt_man{babeltrace2-source.ctf.fs,7}.
355 <dt>\c lttng-live source component class</dt>
357 Connects to an <a href="https://lttng.org/">LTTng</a> relay
358 daemon and emits the messages of the received CTF data streams.
360 See \bt_man{babeltrace2-source.ctf.lttng-live,7}.
363 <dt>\c fs sink component class</dt>
365 Writes the consumed messages as one or more CTF traces on the
368 See \bt_man{babeltrace2-sink.ctf.fs,7}.
373 <dt>\c lttng-utils plugin</dt>
376 <dt>\c debug-info filter component class</dt>
378 Adds debugging information to compatible LTTng event messages.
380 This component class is only available if the project was
381 built with the <code>\-\-enable-debug-info</code>
382 configuration option.
384 See \bt_man{babeltrace2-filter.lttng-utils.debug-info,7}.
389 <dt>\c text plugin</dt>
392 <dt>\c dmesg source component class</dt>
394 Reads the lines of a Linux kernel ring buffer, that is, the
396 <a href="http://man7.org/linux/man-pages/man1/dmesg.1.html"><code>dmesg</code></a>
397 tool, and emits each line as an \bt_ev_msg.
399 See \bt_man{babeltrace2-source.text.dmesg,7}.
402 <dt>\c details sink component class</dt>
404 Deterministically prints the messages it consumes with details
405 to the standard output.
407 See \bt_man{babeltrace2-sink.text.details,7}.
410 <dt>\c pretty sink component class</dt>
412 Pretty-prints the messages it consumes to the standard output or
415 This is equivalent to the \c text output format of the
416 <a href="https://manpages.debian.org/stretch/babeltrace/babeltrace.1.en.html">Babeltrace 1
417 command-line tool</a>.
419 See \bt_man{babeltrace2-sink.text.pretty,7}.
424 <dt>\c utils plugin</dt>
427 <dt>\c muxer filter component class</dt>
429 Muxes messages by time.
431 See \bt_man{babeltrace2-filter.utils.muxer,7}.
434 <dt>\c trimmer filter component class</dt>
436 Discards all the consumed messages with a time outside a given
437 time range, effectively "cutting" \bt_p_stream.
439 See \bt_man{babeltrace2-filter.utils.trimmer,7}.
442 <dt>\c counter sink component class</dt>
444 Prints the number of consumed messages, either once at the end
445 or periodically, to the standard output.
447 See \bt_man{babeltrace2-sink.utils.counter,7}.
450 <dt>\c dummy sink component class</dt>
452 Consumes messages and discards them (does nothing with them).
454 This is useful for testing and benchmarking a trace processing
455 graph application, for example.
457 See \bt_man{babeltrace2-sink.utils.dummy,7}.
463 To access such a component class, get its plugin by name with
464 bt_plugin_find() and then borrow the component class by name
465 with bt_plugin_borrow_source_component_class_by_name_const(),
466 bt_plugin_borrow_filter_component_class_by_name_const(), or
467 bt_plugin_borrow_sink_component_class_by_name_const().
472 const bt_plugin *plugin;
474 if (bt_plugin_find("utils", BT_TRUE, BT_TRUE, BT_TRUE, BT_TRUE, BT_TRUE,
475 &plugin) != BT_PLUGIN_FIND_STATUS_OK) {
479 const bt_component_class_filter *muxer_component_class =
480 bt_plugin_borrow_filter_component_class_by_name_const(plugin, "muxer");
482 if (!muxer_component_class) {
487 <h1>\anchor api-graph-listeners Listeners</h1>
489 A \bt_comp can add a \bt_port:
491 - At initialization time, that is, when you call one of the
492 <code>bt_graph_add_*_component*()</code> functions.
494 - When one of its ports gets connected, that is, when you call
495 bt_graph_connect_ports().
497 To get notified when any component of a given trace processing
498 graph adds a port, add one or more "port
499 added" listeners to the graph with:
501 - bt_graph_add_source_component_output_port_added_listener()
502 - bt_graph_add_filter_component_input_port_added_listener()
503 - bt_graph_add_filter_component_output_port_added_listener()
504 - bt_graph_add_sink_component_input_port_added_listener()
506 Within a "port added" listener function, you can
507 \ref api-graph-lc-add "add more components"
508 and \ref api-graph-lc-connect "connect more component ports".
517 @typedef struct bt_graph bt_graph;
520 Trace processing graph.
532 Creates a default, empty trace processing graph honouring version
533 \bt_p{mip_version} of the \bt_mip.
535 On success, the returned graph contains no components (see
536 \ref api-graph-lc-add "Add components").
538 The graph is configured as operating following version
539 \bt_p{mip_version} of the Message Interchange Protocol, so that
540 bt_self_component_get_graph_mip_version() returns this version when
544 As of \bt_name_version_min_maj, the only available MIP version is 0.
546 The returned graph has a default \bt_intr. Any \bt_comp you add with the
547 <code>bt_graph_add_*_component*()</code> functions and all their
548 \bt_p_msg_iter also have this same default interrupter. Borrow the graph's
549 default interrupter with bt_graph_borrow_default_interrupter().
551 @param[in] mip_version
552 Version of the Message Interchange Protocol to use within the
556 New trace processing graph reference, or \c NULL on memory error.
559 \bt_p{mip_version} is 0.
561 extern bt_graph
*bt_graph_create(uint64_t mip_version
);
566 @name Component adding
573 <code>bt_graph_add_*_component*()</code> functions.
575 typedef enum bt_graph_add_component_status
{
580 BT_GRAPH_ADD_COMPONENT_STATUS_OK
= __BT_FUNC_STATUS_OK
,
586 BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
592 BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
593 } bt_graph_add_component_status
;
597 Alias of bt_graph_add_source_component_with_initialize_method_data()
598 with the \bt_p{initialize_method_data} parameter set to \c NULL.
600 extern bt_graph_add_component_status
601 bt_graph_add_source_component(bt_graph
*graph
,
602 const bt_component_class_source
*component_class
,
603 const char *name
, const bt_value
*params
,
604 bt_logging_level logging_level
,
605 const bt_component_source
**component
);
609 Creates a \bt_src_comp from the
610 \ref api-tir-comp-cls "class" \bt_p{component_class}
611 with the initialization parameters \bt_p{params}, the initialization
612 user data \bt_p{initialize_method_data}, and the initial
613 logging level \bt_p{logging_level}, adds it to the trace processing
614 graph \bt_p{graph} with the name \bt_p{name}, and sets
615 \bt_p{*component} to the resulting component.
617 See \ref api-graph-lc-add "Add components" to learn more about adding
618 components to a trace processing graph.
620 This function calls the source component's
621 \ref api-comp-cls-dev-meth-init "initialization method" after
624 The created source component's initialization method receives:
626 - \bt_p{params} as its own \bt_p{params} parameter (or an empty
627 \bt_map_val if \bt_p{params} is \c NULL).
629 - \bt_p{initialize_method_data} as its own \bt_p{initialize_method_data}
632 The created source component can get its logging level
633 (\bt_p{logging_level}) with bt_component_get_logging_level().
636 Trace processing graph to which to add the created source component.
637 @param[in] component_class
638 Class to instantiate within \bt_p{graph}.
640 Unique name, within \bt_p{graph}, of the component to create.
643 Initialization parameters to use when creating the source component.
645 Can be \c NULL, in which case the created source component's
646 initialization method receives an empty \bt_map_val as its
647 \bt_p{params} parameter.
649 @param[in] initialize_method_data
650 User data passed as is to the created source component's
651 initialization method.
652 @param[in] logging_level
653 Initial logging level of the source component to create.
654 @param[out] component
655 <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
656 a \em borrowed reference of the created source component.
658 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
660 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
662 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
663 Other error, for example, the created source component's
664 initialization method failed.
666 @bt_pre_not_null{graph}
667 @bt_pre_graph_not_configured{graph}
668 @bt_pre_graph_not_faulty{graph}
669 @bt_pre_not_null{component_class}
670 @bt_pre_not_null{name}
672 No other component within \bt_p{graph} has the name \bt_p{name}.
674 \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
677 @bt_post_success_frozen{component_class}
678 @bt_post_success_frozen{params}
680 extern bt_graph_add_component_status
681 bt_graph_add_source_component_with_initialize_method_data(
683 const bt_component_class_source
*component_class
,
684 const char *name
, const bt_value
*params
,
685 void *initialize_method_data
, bt_logging_level logging_level
,
686 const bt_component_source
**component
);
690 Alias of bt_graph_add_filter_component_with_initialize_method_data()
691 with the \bt_p{initialize_method_data} parameter set to \c NULL.
693 extern bt_graph_add_component_status
694 bt_graph_add_filter_component(bt_graph
*graph
,
695 const bt_component_class_filter
*component_class
,
696 const char *name
, const bt_value
*params
,
697 bt_logging_level logging_level
,
698 const bt_component_filter
**component
);
702 Creates a \bt_flt_comp from the
703 \ref api-tir-comp-cls "class" \bt_p{component_class}
704 with the initialization parameters \bt_p{params}, the initialization
705 user data \bt_p{initialize_method_data}, and the initial
706 logging level \bt_p{logging_level}, adds it to the trace processing
707 graph \bt_p{graph} with the name \bt_p{name}, and sets
708 \bt_p{*component} to the resulting component.
710 See \ref api-graph-lc-add "Add components" to learn more about adding
711 components to a trace processing graph.
713 This function calls the filter component's
714 \ref api-comp-cls-dev-meth-init "initialization method" after
717 The created filter component's initialization method receives:
719 - \bt_p{params} as its own \bt_p{params} parameter (or an empty
720 \bt_map_val if \bt_p{params} is \c NULL).
722 - \bt_p{initialize_method_data} as its own \bt_p{initialize_method_data}
725 The created filter component can get its logging level
726 (\bt_p{logging_level}) with bt_component_get_logging_level().
729 Trace processing graph to which to add the created filter component.
730 @param[in] component_class
731 Class to instantiate within \bt_p{graph}.
733 Unique name, within \bt_p{graph}, of the component to create.
736 Initialization parameters to use when creating the filter component.
738 Can be \c NULL, in which case the created filter component's
739 initialization method receives an empty \bt_map_val as its
740 \bt_p{params} parameter.
742 @param[in] initialize_method_data
743 User data passed as is to the created filter component's
744 initialization method.
745 @param[in] logging_level
746 Initial logging level of the filter component to create.
747 @param[out] component
748 <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
749 a \em borrowed reference of the created filter component.
751 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
753 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
755 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
756 Other error, for example, the created filter component's
757 initialization method failed.
759 @bt_pre_not_null{graph}
760 @bt_pre_graph_not_configured{graph}
761 @bt_pre_graph_not_faulty{graph}
762 @bt_pre_not_null{component_class}
763 @bt_pre_not_null{name}
765 No other component within \bt_p{graph} has the name \bt_p{name}.
767 \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
770 @bt_post_success_frozen{component_class}
771 @bt_post_success_frozen{params}
773 extern bt_graph_add_component_status
774 bt_graph_add_filter_component_with_initialize_method_data(
776 const bt_component_class_filter
*component_class
,
777 const char *name
, const bt_value
*params
,
778 void *initialize_method_data
, bt_logging_level logging_level
,
779 const bt_component_filter
**component
);
783 Alias of bt_graph_add_sink_component_with_initialize_method_data()
784 with the \bt_p{initialize_method_data} parameter set to \c NULL.
786 extern bt_graph_add_component_status
787 bt_graph_add_sink_component(
788 bt_graph
*graph
, const bt_component_class_sink
*component_class
,
789 const char *name
, const bt_value
*params
,
790 bt_logging_level logging_level
,
791 const bt_component_sink
**component
);
795 Creates a \bt_sink_comp from the
796 \ref api-tir-comp-cls "class" \bt_p{component_class}
797 with the initialization parameters \bt_p{params}, the initialization
798 user data \bt_p{initialize_method_data}, and the initial
799 logging level \bt_p{logging_level}, adds it to the trace processing
800 graph \bt_p{graph} with the name \bt_p{name}, and sets
801 \bt_p{*component} to the resulting component.
803 See \ref api-graph-lc-add "Add components" to learn more about adding
804 components to a trace processing graph.
806 This function calls the sink component's
807 \ref api-comp-cls-dev-meth-init "initialization method" after
810 The created sink component's initialization method receives:
812 - \bt_p{params} as its own \bt_p{params} parameter (or an empty
813 \bt_map_val if \bt_p{params} is \c NULL).
815 - \bt_p{initialize_method_data} as its own \bt_p{initialize_method_data}
818 The created sink component can get its logging level
819 (\bt_p{logging_level}) with bt_component_get_logging_level().
822 Trace processing graph to which to add the created sink component.
823 @param[in] component_class
824 Class to instantiate within \bt_p{graph}.
826 Unique name, within \bt_p{graph}, of the component to create.
829 Initialization parameters to use when creating the sink component.
831 Can be \c NULL, in which case the created sink component's
832 initialization method receives an empty \bt_map_val as its
833 \bt_p{params} parameter.
835 @param[in] initialize_method_data
836 User data passed as is to the created sink component's
837 initialization method.
838 @param[in] logging_level
839 Initial logging level of the sink component to create.
840 @param[out] component
841 <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
842 a \em borrowed reference of the created sink component.
844 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
846 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
848 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
849 Other error, for example, the created sink component's
850 initialization method failed.
852 @bt_pre_not_null{graph}
853 @bt_pre_graph_not_configured{graph}
854 @bt_pre_graph_not_faulty{graph}
855 @bt_pre_not_null{component_class}
856 @bt_pre_not_null{name}
858 No other component within \bt_p{graph} has the name \bt_p{name}.
860 \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
863 @bt_post_success_frozen{component_class}
864 @bt_post_success_frozen{params}
866 extern bt_graph_add_component_status
867 bt_graph_add_sink_component_with_initialize_method_data(
868 bt_graph
*graph
, const bt_component_class_sink
*component_class
,
869 const char *name
, const bt_value
*params
,
870 void *initialize_method_data
, bt_logging_level logging_level
,
871 const bt_component_sink
**component
);
876 @name Simple sink component adding
882 Status codes for the #bt_graph_simple_sink_component_initialize_func
885 typedef enum bt_graph_simple_sink_component_initialize_func_status
{
890 BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_OK
= __BT_FUNC_STATUS_OK
,
896 BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
902 BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
903 } bt_graph_simple_sink_component_initialize_func_status
;
907 User initialization function for
908 bt_graph_add_simple_sink_component().
910 Such an initialization function is called when the trace processing
911 graph becomes configured and when the simple sink component has created
912 its single \bt_msg_iter. This occurs the first time you call
913 bt_graph_run() or bt_graph_run_once() on the trace processing graph.
915 See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
916 about adding a simple component to a trace processing graph.
918 @param[in] message_iterator
920 Simple sink component's upstream message iterator.
922 This user function is free to get the message iterator's next
923 message or to make it seek.
926 User data, as passed as the \bt_p{user_data} parameter of
927 bt_graph_add_simple_sink_component().
929 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_OK
931 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_MEMORY_ERROR
933 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_ERROR
936 @bt_pre_not_null{message_iterator}
939 The reference count of \bt_p{message_iterator} is not changed.
941 @sa bt_graph_add_simple_sink_component() —
942 Creates and adds a simple sink component to a trace processing
945 typedef bt_graph_simple_sink_component_initialize_func_status
946 (*bt_graph_simple_sink_component_initialize_func
)(
947 bt_message_iterator
*message_iterator
,
952 Status codes for the #bt_graph_simple_sink_component_consume_func
955 typedef enum bt_graph_simple_sink_component_consume_func_status
{
960 BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK
= __BT_FUNC_STATUS_OK
,
966 BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END
= __BT_FUNC_STATUS_END
,
972 BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
978 BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
984 BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
985 } bt_graph_simple_sink_component_consume_func_status
;
989 User consuming function for bt_graph_add_simple_sink_component().
991 Such a consuming function is called when the simple sink component's own
992 \ref api-comp-cls-dev-meth-consume "consuming method" is called. This
993 occurs in a loop within bt_graph_run() or when it's this sink
994 component's turn to consume in
997 See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
998 about adding a simple component to a trace processing graph.
1000 If you are not done consuming messages, return
1001 #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK.
1003 If you are done consuming messages, return
1004 #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END.
1006 If you wish to avoid a blocking operation and make
1007 bt_graph_run() or bt_graph_run_once() aware, return
1008 #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN.
1010 @param[in] message_iterator
1012 Simple sink component's upstream message iterator.
1014 This user function is free to get the message iterator's next
1015 message or to make it seek.
1017 @param[in] user_data
1018 User data, as passed as the \bt_p{user_data} parameter of
1019 bt_graph_add_simple_sink_component().
1021 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK
1023 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END
1025 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN
1027 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_MEMORY_ERROR
1029 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_ERROR
1032 @bt_pre_not_null{message_iterator}
1035 The reference count of \bt_p{message_iterator} is not changed.
1037 @sa bt_graph_add_simple_sink_component() —
1038 Creates and adds a simple sink component to a trace processing
1041 typedef bt_graph_simple_sink_component_consume_func_status
1042 (*bt_graph_simple_sink_component_consume_func
)(
1043 bt_message_iterator
*message_iterator
,
1048 User finalization function for bt_graph_add_simple_sink_component().
1050 Such a finalization function is called when the simple sink component
1051 is finalized. This occurs when the trace processing graph is destroyed
1052 (you put its last strong \ref api-fund-shared-object "reference"
1053 with bt_graph_put_ref()).
1055 See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
1056 about adding a simple component to a trace processing graph.
1058 @param[in] user_data
1059 User data, as passed as the \bt_p{user_data} parameter of
1060 bt_graph_add_simple_sink_component().
1064 @sa bt_graph_add_simple_sink_component() —
1065 Creates and adds a simple sink component to a trace processing
1068 typedef void (*bt_graph_simple_sink_component_finalize_func
)(void *user_data
);
1072 Creates a simple \bt_sink_comp, adds it to the trace processing
1073 graph \bt_p{graph} with the name \bt_p{name}, and sets
1074 \bt_p{*component} to the resulting component.
1076 See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
1077 about adding a simple component to a trace processing graph.
1079 \bt_p{initialize_func} (if not \c NULL), \bt_p{consume_func},
1080 and \bt_p{finalize_func} (if not \c NULL) receive \bt_p{user_data}
1081 as their own \bt_p{user_data} parameter.
1084 Trace processing graph to which to add the created simple sink
1087 Unique name, within \bt_p{graph}, of the component to create.
1088 @param[in] initialize_func
1090 User initialization function.
1094 @param[in] consume_func
1095 User consuming function.
1096 @param[in] finalize_func
1098 User finalization function.
1102 @param[in] user_data
1103 User data to pass as the \bt_p{user_data} parameter of
1104 \bt_p{initialize_func}, \bt_p{consume_func}, and
1105 \bt_p{finalize_func}.
1106 @param[out] component
1107 <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
1108 a \em borrowed reference of the created simple sink component.
1110 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
1112 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
1114 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
1115 Other error, for example, the created sink component's
1116 \ref api-comp-cls-dev-meth-init "initialization method" failed.
1118 @bt_pre_not_null{graph}
1119 @bt_pre_graph_not_configured{graph}
1120 @bt_pre_graph_not_faulty{graph}
1121 @bt_pre_not_null{name}
1123 No other component within \bt_p{graph} has the name \bt_p{name}.
1124 @bt_pre_not_null{consume_func}
1126 extern bt_graph_add_component_status
1127 bt_graph_add_simple_sink_component(bt_graph
*graph
, const char *name
,
1128 bt_graph_simple_sink_component_initialize_func initialize_func
,
1129 bt_graph_simple_sink_component_consume_func consume_func
,
1130 bt_graph_simple_sink_component_finalize_func finalize_func
,
1131 void *user_data
, const bt_component_sink
**component
);
1136 @name Component port connection
1142 Status codes for bt_graph_connect_ports().
1144 typedef enum bt_graph_connect_ports_status
{
1149 BT_GRAPH_CONNECT_PORTS_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1155 BT_GRAPH_CONNECT_PORTS_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1161 BT_GRAPH_CONNECT_PORTS_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1162 } bt_graph_connect_ports_status
;
1166 Connects the \bt_oport \bt_p{upstream_port} to the \bt_iport
1167 \bt_p{downstream_port} within the trace processing graph
1168 \bt_p{graph}, and sets \bt_p{*connection} to the resulting
1171 See \ref api-graph-lc-connect "Connect component ports" to learn more
1172 about connecting ports within a trace processing graph.
1174 Both \bt_p{upstream_port} and \bt_p{downstream_port} must be
1175 unconnected (bt_port_is_connected() returns #BT_FALSE) when you call
1179 Trace processing graph containing the \bt_p_comp to which belong
1180 \bt_p{upstream_port} and \bt_p{downstream_port}.
1181 @param[in] upstream_port
1182 \bt_c_oport to connect to \bt_p{downstream_port}.
1183 @param[in] downstream_port
1184 \bt_c_iport to connect to \bt_p{upstream_port}.
1185 @param[in] connection
1186 <strong>On success, if not \c NULL</strong>, \bt_p{*connection} is
1187 a \em borrowed reference of the resulting \bt_conn.
1189 @retval #BT_GRAPH_CONNECT_PORTS_STATUS_OK
1191 @retval #BT_GRAPH_CONNECT_PORTS_STATUS_MEMORY_ERROR
1193 @retval #BT_GRAPH_CONNECT_PORTS_STATUS_ERROR
1196 @bt_pre_not_null{graph}
1197 @bt_pre_graph_not_configured{graph}
1198 @bt_pre_graph_not_faulty{graph}
1199 @bt_pre_not_null{upstream_port}
1201 \bt_p{graph} contains the component of \bt_p{upstream_port},
1202 as returned by bt_port_borrow_component_const().
1204 \bt_p{upstream_port} is unconnected
1205 (bt_port_is_connected() returns #BT_FALSE).
1206 @bt_pre_not_null{downstream_port}
1208 \bt_p{graph} contains the component of \bt_p{downstream_port},
1209 as returned by bt_port_borrow_component_const().
1211 \bt_p{downstream_port} is unconnected
1212 (bt_port_is_connected() returns #BT_FALSE).
1214 Connecting \bt_p{upstream_port} to \bt_p{downstream_port} does not
1215 form a connection cycle within \bt_p{graph}.
1217 extern bt_graph_connect_ports_status
bt_graph_connect_ports(bt_graph
*graph
,
1218 const bt_port_output
*upstream_port
,
1219 const bt_port_input
*downstream_port
,
1220 const bt_connection
**connection
);
1231 Status codes for bt_graph_run().
1233 typedef enum bt_graph_run_status
{
1238 BT_GRAPH_RUN_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1244 BT_GRAPH_RUN_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
1250 BT_GRAPH_RUN_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1256 BT_GRAPH_RUN_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1257 } bt_graph_run_status
;
1261 Runs the trace processing graph \bt_p{graph}, calling each
1263 \ref api-comp-cls-dev-meth-consume "consuming method" in a round
1264 robin fashion until they are all done consuming or an exception
1267 See \ref api-graph-lc-run "Run" to learn more about running a trace
1270 This function does \em not return until one of:
1272 - All the sink components are ended, in which case this function
1273 returns #BT_GRAPH_RUN_STATUS_OK.
1275 - One of the sink component returns an error, in which case this
1276 function returns #BT_GRAPH_RUN_STATUS_ERROR or
1277 #BT_GRAPH_RUN_STATUS_MEMORY_ERROR.
1279 - One of the sink component returns "try again", in which case
1280 this function returns #BT_GRAPH_RUN_STATUS_AGAIN.
1282 In that case, you can call this function again later, usually after
1283 waiting for some time.
1285 This feature exists to allow blocking operations within components
1286 to be postponed until they don't block. The graph user can perform
1287 other tasks instead of the graph's thread blocking.
1289 - \bt_p{graph} is interrupted (see bt_graph_borrow_default_interrupter()
1290 and bt_graph_add_interrupter()), in which case this function returns
1291 #BT_GRAPH_RUN_STATUS_AGAIN.
1293 Check the \bt_intr's state with bt_interrupter_is_set() to
1294 distinguish between a sink component returning "try again" and
1295 \bt_p{graph} getting interrupted.
1297 To make a single sink component consume, then get the thread's control
1298 back, use bt_graph_run_once().
1300 When you call this function or bt_graph_run_once() for the first time,
1301 \bt_p{graph} becomes <em>configured</em>. See
1302 \ref api-graph-lc "Trace processing graph life cycle"
1303 to learn what happens when a trace processing graph becomes configured,
1304 and what you can and cannot do with a configured graph.
1307 Trace processing graph to run.
1309 @retval #BT_GRAPH_RUN_STATUS_OK
1311 @retval #BT_GRAPH_RUN_STATUS_AGAIN
1313 @retval #BT_GRAPH_RUN_STATUS_MEMORY_ERROR
1315 @retval #BT_GRAPH_RUN_STATUS_ERROR
1318 @bt_pre_not_null{graph}
1319 @bt_pre_graph_not_faulty{graph}
1321 For each \bt_src_comp within \bt_p{graph}, at least one \bt_oport
1324 For each \bt_flt_comp within \bt_p{graph}, at least one \bt_iport
1325 and one \bt_iport are connected.
1327 For each \bt_sink_comp within \bt_p{graph}, at least one \bt_iport
1330 \bt_p{graph} contains at least one sink component.
1332 @sa bt_graph_run_once() —
1333 Calls a single trace processing graph's sink component's consuming
1336 extern bt_graph_run_status
bt_graph_run(bt_graph
*graph
);
1340 Status codes for bt_graph_run().
1342 typedef enum bt_graph_run_once_status
{
1347 BT_GRAPH_RUN_ONCE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1351 All sink components are finished processing.
1353 BT_GRAPH_RUN_ONCE_STATUS_END
= __BT_FUNC_STATUS_END
,
1359 BT_GRAPH_RUN_ONCE_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
1365 BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1371 BT_GRAPH_RUN_ONCE_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1372 } bt_graph_run_once_status
;
1376 Calls the \ref api-comp-cls-dev-meth-consume "consuming method" of
1377 the next non-ended \bt_sink_comp to make consume within the trace
1378 processing graph \bt_p{graph}.
1380 See \ref api-graph-lc-run "Run" to learn more about running a trace
1383 This function makes the \em next non-ended sink component consume. For
1384 example, if \bt_p{graph} has two non-ended sink components A and B:
1386 - Calling bt_graph_run_once() makes sink component A consume.
1387 - Calling bt_graph_run_once() again makes sink component B consume.
1388 - Calling bt_graph_run_once() again makes sink component A consume.
1391 Considering this, if \bt_p{graph} contains a single non-ended sink
1392 component, this function \em always makes this sink component consume.
1394 If the sink component's consuming method:
1398 <dd>This function returns #BT_GRAPH_RUN_ONCE_STATUS_OK.</dd>
1400 <dt>Returns "try again"</dt>
1401 <dd>This function returns #BT_GRAPH_RUN_ONCE_STATUS_AGAIN.</dd>
1405 This function returns #BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR
1406 or #BT_GRAPH_RUN_ONCE_STATUS_ERROR.
1410 When all the sink components of \bt_p{graph} are finished processing
1411 (ended), this function returns #BT_GRAPH_RUN_ONCE_STATUS_END.
1413 bt_graph_run() calls this function in a loop until are the sink
1414 components are ended or an exception occurs.
1416 When you call this function or bt_graph_run() for the first time,
1417 \bt_p{graph} becomes <em>configured</em>. See
1418 \ref api-graph-lc "Trace processing graph life cycle"
1419 to learn what happens when a trace processing graph becomes configured,
1420 and what you can and cannot do with a configured graph.
1423 Trace processing graph of which to make the next sink component
1426 @retval #BT_GRAPH_RUN_ONCE_STATUS_OK
1428 @retval #BT_GRAPH_RUN_ONCE_STATUS_END
1429 All sink components are finished processing.
1430 @retval #BT_GRAPH_RUN_ONCE_STATUS_AGAIN
1432 @retval #BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR
1434 @retval #BT_GRAPH_RUN_ONCE_STATUS_ERROR
1437 @bt_pre_not_null{graph}
1438 @bt_pre_graph_not_faulty{graph}
1440 @sa bt_graph_run() —
1441 Runs a trace processing graph, making all its sink components
1442 consume in a round robin fashion.
1444 extern bt_graph_run_once_status
bt_graph_run_once(bt_graph
*graph
);
1455 Status codes for bt_graph_add_interrupter().
1457 typedef enum bt_graph_add_interrupter_status
{
1462 BT_GRAPH_ADD_INTERRUPTER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1468 BT_GRAPH_ADD_INTERRUPTER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1469 } bt_graph_add_interrupter_status
;
1473 Adds the \bt_intr \bt_p{interrupter} to all the current and future
1474 \bt_p_sink_comp and \bt_p_msg_iter of the trace processing graph
1475 \bt_p{graph}, as well as to the graph itself.
1477 Sink components can check whether or not they are interrupted
1478 with bt_self_component_sink_is_interrupted().
1480 Message iterators can check whether or not they are interrupted
1481 with bt_self_message_iterator_is_interrupted().
1483 The bt_graph_run() loop intermittently checks whether or not any of the
1484 graph's interrupters is set. If so, bt_graph_run() returns
1485 #BT_GRAPH_RUN_STATUS_AGAIN.
1489 bt_graph_create() returns a trace processing graph which comes
1490 with its own <em>default interrupter</em>.
1492 Instead of adding your own interrupter to \bt_p{graph}, you can
1493 set its default interrupter with
1496 bt_interrupter_set(bt_graph_borrow_default_interrupter());
1501 Trace processing graph to which to add \bt_p{interrupter}.
1502 @param[in] interrupter
1503 Interrupter to add to \bt_p{graph}.
1505 @retval #BT_GRAPH_ADD_INTERRUPTER_STATUS_OK
1507 @retval #BT_GRAPH_ADD_INTERRUPTER_STATUS_MEMORY_ERROR
1510 @bt_pre_not_null{graph}
1511 @bt_pre_graph_not_faulty{graph}
1512 @bt_pre_not_null{interrupter}
1514 @sa bt_graph_borrow_default_interrupter() —
1515 Borrows the default interrupter from a trace processing graph.
1517 extern bt_graph_add_interrupter_status
bt_graph_add_interrupter(bt_graph
*graph
,
1518 const bt_interrupter
*interrupter
);
1522 Borrows the default \bt_intr from the trace processing graph
1526 Trace processing graph from which to borrow the default interrupter.
1530 \em Borrowed reference of the default interrupter of \bt_p{graph}.
1532 The returned pointer remains valid as long as \bt_p{graph} exists.
1535 @bt_pre_not_null{graph}
1537 @sa bt_graph_add_interrupter() —
1538 Adds an interrupter to a trace processing graph.
1540 extern bt_interrupter
*bt_graph_borrow_default_interrupter(bt_graph
*graph
);
1551 Status codes for the
1552 <code>bt_graph_add_*_component_*_port_added_listener()</code>
1555 typedef enum bt_graph_add_listener_status
{
1560 BT_GRAPH_ADD_LISTENER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1566 BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1567 } bt_graph_add_listener_status
;
1571 Status codes for the
1572 <code>bt_graph_*_component_*_port_added_listener_func()</code>
1575 typedef enum bt_graph_listener_func_status
{
1580 BT_GRAPH_LISTENER_FUNC_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1586 BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1592 BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1593 } bt_graph_listener_func_status
;
1598 bt_graph_add_filter_component_input_port_added_listener().
1600 Such a function is called whenever a \bt_flt_comp within a trace
1601 processing graph adds an \bt_iport during the graph
1602 \ref api-graph-lc "configuration" phase.
1604 See \ref api-graph-listeners "Listeners" to learn more.
1606 @param[in] component
1607 Filter component which added \bt_p{port}.
1609 Input port added by \bt_p{component}.
1610 @param[in] user_data
1611 User data, as passed as the \bt_p{user_data} parameter of
1612 bt_graph_add_filter_component_input_port_added_listener().
1614 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
1616 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
1618 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
1621 @bt_pre_not_null{component}
1622 @bt_pre_not_null{port}
1624 @sa bt_graph_add_filter_component_input_port_added_listener() —
1625 Adds a "filter component input port added" listener to a trace
1628 typedef bt_graph_listener_func_status
1629 (*bt_graph_filter_component_input_port_added_listener_func
)(
1630 const bt_component_filter
*component
,
1631 const bt_port_input
*port
, void *user_data
);
1635 Adds a \"\bt_flt_comp \bt_iport added\" listener to the trace
1636 processing graph \bt_p{graph}.
1638 Once this function returns, \bt_p{user_func} is called whenever a
1639 filter component adds an input port within \bt_p{graph}.
1641 See \ref api-graph-listeners "Listeners" to learn more.
1644 Trace processing graph to add the "filter component input port
1646 @param[in] user_func
1647 User function of the "filter component input port added" listener to
1648 add to \bt_p{graph}.
1649 @param[in] user_data
1650 User data to pass as the \bt_p{user_data} parameter of
1652 @param[out] listener_id
1653 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
1654 is the ID of the added listener within \bt_p{graph}.
1656 @retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
1658 @retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
1661 @bt_pre_not_null{graph}
1662 @bt_pre_graph_not_faulty{graph}
1663 @bt_pre_not_null{user_func}
1665 extern bt_graph_add_listener_status
1666 bt_graph_add_filter_component_input_port_added_listener(
1668 bt_graph_filter_component_input_port_added_listener_func user_func
,
1669 void *user_data
, bt_listener_id
*listener_id
);
1674 bt_graph_add_sink_component_input_port_added_listener().
1676 Such a function is called whenever a \bt_sink_comp within a trace
1677 processing graph adds an \bt_iport during the graph
1678 \ref api-graph-lc "configuration" phase.
1680 See \ref api-graph-listeners "Listeners" to learn more.
1682 @param[in] component
1683 Filter component which added \bt_p{port}.
1685 Input port added by \bt_p{component}.
1686 @param[in] user_data
1687 User data, as passed as the \bt_p{user_data} parameter of
1688 bt_graph_add_sink_component_input_port_added_listener().
1690 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
1692 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
1694 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
1697 @bt_pre_not_null{component}
1698 @bt_pre_not_null{port}
1700 @sa bt_graph_add_sink_component_input_port_added_listener() —
1701 Adds a "sink component input port added" listener to a trace
1704 typedef bt_graph_listener_func_status
1705 (*bt_graph_sink_component_input_port_added_listener_func
)(
1706 const bt_component_sink
*component
,
1707 const bt_port_input
*port
, void *user_data
);
1711 Adds a \"\bt_sink_comp \bt_iport added\" listener to the trace
1712 processing graph \bt_p{graph}.
1714 Once this function returns, \bt_p{user_func} is called whenever a
1715 sink component adds an input port within \bt_p{graph}.
1717 See \ref api-graph-listeners "Listeners" to learn more.
1720 Trace processing graph to add the "sink component input port
1722 @param[in] user_func
1723 User function of the "sink component input port added" listener to
1724 add to \bt_p{graph}.
1725 @param[in] user_data
1726 User data to pass as the \bt_p{user_data} parameter of
1728 @param[out] listener_id
1729 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
1730 is the ID of the added listener within \bt_p{graph}.
1732 @retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
1734 @retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
1737 @bt_pre_not_null{graph}
1738 @bt_pre_graph_not_faulty{graph}
1739 @bt_pre_not_null{user_func}
1741 extern bt_graph_add_listener_status
1742 bt_graph_add_sink_component_input_port_added_listener(
1744 bt_graph_sink_component_input_port_added_listener_func user_func
,
1745 void *user_data
, bt_listener_id
*listener_id
);
1750 bt_graph_add_source_component_output_port_added_listener().
1752 Such a function is called whenever a \bt_src_comp within a trace
1753 processing graph adds an \bt_oport during the graph
1754 \ref api-graph-lc "configuration" phase.
1756 See \ref api-graph-listeners "Listeners" to learn more.
1758 @param[in] component
1759 Filter component which added \bt_p{port}.
1761 Input port added by \bt_p{component}.
1762 @param[in] user_data
1763 User data, as passed as the \bt_p{user_data} parameter of
1764 bt_graph_add_source_component_output_port_added_listener().
1766 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
1768 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
1770 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
1773 @bt_pre_not_null{component}
1774 @bt_pre_not_null{port}
1776 @sa bt_graph_add_source_component_output_port_added_listener() —
1777 Adds a "source component output port added" listener to a trace
1780 typedef bt_graph_listener_func_status
1781 (*bt_graph_source_component_output_port_added_listener_func
)(
1782 const bt_component_source
*component
,
1783 const bt_port_output
*port
, void *user_data
);
1787 Adds a \"\bt_src_comp \bt_oport added\" listener to the trace
1788 processing graph \bt_p{graph}.
1790 Once this function returns, \bt_p{user_func} is called whenever a
1791 source component adds an output port within \bt_p{graph}.
1793 See \ref api-graph-listeners "Listeners" to learn more.
1796 Trace processing graph to add the "source component output port
1798 @param[in] user_func
1799 User function of the "source component output port added" listener
1800 to add to \bt_p{graph}.
1801 @param[in] user_data
1802 User data to pass as the \bt_p{user_data} parameter of
1804 @param[out] listener_id
1805 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
1806 is the ID of the added listener within \bt_p{graph}.
1808 @retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
1810 @retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
1813 @bt_pre_not_null{graph}
1814 @bt_pre_graph_not_faulty{graph}
1815 @bt_pre_not_null{user_func}
1817 extern bt_graph_add_listener_status
1818 bt_graph_add_source_component_output_port_added_listener(
1820 bt_graph_source_component_output_port_added_listener_func user_func
,
1821 void *user_data
, bt_listener_id
*listener_id
);
1826 bt_graph_add_filter_component_output_port_added_listener().
1828 Such a function is called whenever a \bt_flt_comp within a trace
1829 processing graph adds an \bt_oport during the graph
1830 \ref api-graph-lc "configuration" phase.
1832 See \ref api-graph-listeners "Listeners" to learn more.
1834 @param[in] component
1835 Filter component which added \bt_p{port}.
1837 Input port added by \bt_p{component}.
1838 @param[in] user_data
1839 User data, as passed as the \bt_p{user_data} parameter of
1840 bt_graph_add_filter_component_output_port_added_listener().
1842 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
1844 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
1846 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
1849 @bt_pre_not_null{component}
1850 @bt_pre_not_null{port}
1852 @sa bt_graph_add_filter_component_output_port_added_listener() —
1853 Adds a "filter component output port added" listener to a trace
1856 typedef bt_graph_listener_func_status
1857 (*bt_graph_filter_component_output_port_added_listener_func
)(
1858 const bt_component_filter
*component
,
1859 const bt_port_output
*port
, void *user_data
);
1863 Adds a \"\bt_flt_comp \bt_oport added\" listener to the trace
1864 processing graph \bt_p{graph}.
1866 Once this function returns, \bt_p{user_func} is called whenever a
1867 filter component adds an output port within \bt_p{graph}.
1869 See \ref api-graph-listeners "Listeners" to learn more.
1872 Trace processing graph to add the "filter component output port
1874 @param[in] user_func
1875 User function of the "filter component output port added" listener
1876 to add to \bt_p{graph}.
1877 @param[in] user_data
1878 User data to pass as the \bt_p{user_data} parameter of
1880 @param[out] listener_id
1881 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
1882 is the ID of the added listener within \bt_p{graph}.
1884 @retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
1886 @retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
1889 @bt_pre_not_null{graph}
1890 @bt_pre_graph_not_faulty{graph}
1891 @bt_pre_not_null{user_func}
1893 extern bt_graph_add_listener_status
1894 bt_graph_add_filter_component_output_port_added_listener(
1896 bt_graph_filter_component_output_port_added_listener_func user_func
,
1897 void *user_data
, bt_listener_id
*listener_id
);
1902 @name Reference count
1908 Increments the \ref api-fund-shared-object "reference count" of
1909 the trace processing graph \bt_p{graph}.
1913 Trace processing graph of which to increment the reference count.
1918 @sa bt_graph_put_ref() —
1919 Decrements the reference count of a trace processing graph.
1921 extern void bt_graph_get_ref(const bt_graph
*graph
);
1925 Decrements the \ref api-fund-shared-object "reference count" of
1926 the trace processing graph \bt_p{graph}.
1930 Trace processing graph of which to decrement the reference count.
1935 @sa bt_graph_get_ref() —
1936 Increments the reference count of a trace processing graph.
1938 extern void bt_graph_put_ref(const bt_graph
*graph
);
1942 Decrements the reference count of the trace processing graph
1943 \bt_p{_graph}, and then sets \bt_p{_graph} to \c NULL.
1947 Trace processing graph of which to decrement the reference count.
1949 Can contain \c NULL.
1952 @bt_pre_assign_expr{_graph}
1954 #define BT_GRAPH_PUT_REF_AND_RESET(_graph) \
1956 bt_graph_put_ref(_graph); \
1962 Decrements the reference count of the trace processing graph
1963 \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets
1964 \bt_p{_src} to \c NULL.
1966 This macro effectively moves a trace processing graph reference from the
1967 expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
1968 existing \bt_p{_dst} reference.
1972 Destination expression.
1974 Can contain \c NULL.
1980 Can contain \c NULL.
1983 @bt_pre_assign_expr{_dst}
1984 @bt_pre_assign_expr{_src}
1986 #define BT_GRAPH_MOVE_REF(_dst, _src) \
1988 bt_graph_put_ref(_dst); \
2001 #endif /* BABELTRACE2_GRAPH_GRAPH_H */