1 #ifndef BABELTRACE2_GRAPH_GRAPH_H
2 #define BABELTRACE2_GRAPH_GRAPH_H
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to deal
9 * in the Software without restriction, including without limitation the rights
10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
30 #include <babeltrace2/types.h>
31 #include <babeltrace2/logging.h>
38 @defgroup api-graph Graph
41 Trace processing graph.
43 A <strong><em>trace processing graph</em></strong> is a specialized
44 <a href="https://en.wikipedia.org/wiki/Filter_graph">filter graph</a>
45 to manipulate one or more traces.
47 Whereas the nodes of a multimedia filter graph typically exchange
48 video frames and audio samples, the nodes, or \bt_p_comp, of a trace
49 processing graph exchange immutable \bt_p_msg containing trace data.
51 The following illustration shows a basic trace processing graph which
52 converts many traces to a single log of pretty-printed lines:
54 @image html basic-convert-graph.png "Basic trace processing graph (conversion graph)."
56 In the illustrations above, notice that:
58 - The graph (blue) contains five components.
60 - Three source components (green) are connected to a single filter
63 There are five \bt_p_conn, from five \bt_p_oport
66 - The filter component is connected to a single sink component (red).
68 There's a single connection.
70 - Source components read external resources while the sink component
71 writes to the standard output or to a file.
73 - There are two source components having the same
74 \ref api-tir-comp-cls "class": <code>source.ctf.fs</code>.
76 - All components are instances of \bt_plugin-provided classes:
77 <code>babeltrace2-plugin-ctf.so</code>,
78 <code>user-plugin.so</code>,
79 <code>babeltrace2-plugin-utils.so</code>, and
80 <code>babeltrace2-plugin-text.so</code>.
82 Of course the topology can be much more complex if needed:
84 @image html complex-graph.png "Complex trace processing graph."
86 In a trace processing graph, \bt_p_comp are instances of \bt_p_comp_cls.
88 A \bt_plugin can provide a component class, but you can also create one
89 dynamically (see \ref api-comp-cls-dev).
91 The connections between component ports in a trace processing graph
92 indicate the needed topology to achieve a trace processing task. That
94 \bt_p_msg do not flow within connections. Instead, a source-to-sink
95 or filter-to-sink connection makes it
96 possible for a sink component to create a \bt_msg_iter on its end of
97 the connection (an \bt_iport). In turn, a filter component message
98 iterator can create other message iterators on one or more of the
99 component's input ports. For a single connection, there can exist
100 multiple message iterators.
102 A trace processing graph is a
103 \ref api-fund-shared-object "shared object": get a new reference with
104 bt_graph_get_ref() and put an existing reference with
107 The type of a trace processing graph is #bt_graph.
109 Create a default trace processing graph with bt_graph_create(). You need
110 to pass a \bt_mip (MIP) version number when you call this function.
112 \ref api-graph-lc "Trace processing graph life cycle"
113 to learn how to add components to the graph, connect their ports, and
116 To interrupt a \ref api-graph-lc-run "running" trace processing graph,
119 - Borrow the graph's default \bt_intr with
120 bt_graph_borrow_default_interrupter() and set it with
121 bt_interrupter_set().
123 When you call bt_graph_create(), the returned trace processing
124 graph has a default interrupter.
126 - Add your own interrupter with bt_graph_add_interrupter() \em before
127 you run the graph with bt_graph_run() or bt_graph_run_once().
129 Then, set the interrupter with bt_interrupter_set().
131 <h1>\anchor api-graph-lc Trace processing graph life cycle</h1>
133 The following diagram shows the life cycle of a trace processing
136 @image html graph-lifetime.png "Trace processing graph lifecycle."
138 After you create a default (empty) trace processing graph with
139 bt_graph_create(), there are three steps to make the trace processing
142 -# \ref api-graph-lc-add "Add components" to the graph.
143 -# \ref api-graph-lc-connect "Connect component ports".
144 -# \ref api-graph-lc-run "Run the graph".
146 You can repeat steps 1 and 2 before step 3, as connecting a
147 component \bt_port can make this \bt_comp create a new port:
148 you might want to add a component in reaction to this event
149 (see \ref api-graph-listeners "Listeners").
151 Steps 1 and 2 constitute the \em configuration phase of the trace
152 processing graph. The first time you call bt_graph_run() or
153 bt_graph_run_once() for a given graph (step 3), the graph becomes
154 <em>configured</em>, and it notifies the sink components as such so that
155 they can create their \bt_p_msg_iter.
157 Once a trace processing graph becomes configured:
159 - You cannot \ref api-graph-lc-add "add a component" to it.
161 - You cannot \ref api-graph-lc-connect "connect component ports".
163 - Components cannot add ports.
165 In general, as of \bt_name_version_min_maj:
167 - You cannot remove a component from a trace processing graph.
169 - You cannot end (remove) a port \bt_conn.
171 - Components cannot remove ports.
173 If \em any error occurs (a function returns a status code which ends
174 with <code>ERROR</code>) during step 1 or 2, the trace processing
175 graph is considered <strong>faulty</strong>: you cannot use it anymore.
176 The only functions you can call with a faulty graph are
177 bt_graph_get_ref() and bt_graph_put_ref().
179 <h2>\anchor api-graph-lc-add Add components</h2>
181 Adding a \bt_comp to a trace processing graph is also known as
182 <em>instantiating a \bt_comp_cls</em> because the graph must first
183 create the component from its class before adding it.
185 Because component and component class C types are
186 \ref api-fund-c-typing "highly specific", there are six functions
187 to add a component to a trace processing graph:
190 <dt>Source component</dt>
193 <dt>Without initialization method data</dt>
194 <dd>bt_graph_add_source_component()</dd>
196 <dt>With initialization method data</dt>
197 <dd>bt_graph_add_source_component_with_initialize_method_data()</dd>
201 <dt>Filter component</dt>
204 <dt>Without initialization method data</dt>
205 <dd>bt_graph_add_filter_component()</dd>
207 <dt>With initialization method data</dt>
208 <dd>bt_graph_add_filter_component_with_initialize_method_data()</dd>
212 <dt>Sink component</dt>
215 <dt>Without initialization method data</dt>
216 <dd>bt_graph_add_sink_component()</dd>
218 <dt>With initialization method data</dt>
219 <dd>bt_graph_add_sink_component_with_initialize_method_data()</dd>
224 The <code>*_with_initialize_method_data()</code> versions can pass a
225 custom, \bt_voidp pointer to the component's
226 \ref api-comp-cls-dev-meth-init "initialization method".
227 The other versions pass \c NULL as this parameter.
229 All the functions above accept the same parameters:
232 Trace processing graph to which to add the created component.
233 @param[in] component_class
234 Class to instantiate within \bt_p{graph}.
236 Unique name of the component to add within \bt_p{graph}.
238 Initialization parameters to use when creating the component.
239 @param[in] logging_level
240 Initial logging level of the component to create.
241 @param[out] component
242 <strong>On success</strong>, \bt_p{*component} is the created
245 Once you have the created and added component (\bt_p{*component}),
246 you can borrow its \bt_p_port to
247 \ref api-graph-lc-connect "connect them".
249 You can add as many components as needed to a trace processing graph,
250 but they must all have a unique name.
252 <h3>\anchor api-graph-lc-add-ss Add a simple sink component</h3>
254 To add a very basic \bt_sink_comp which has a single \bt_iport and
255 creates a single \bt_msg_iter when the trace processing graph becomes
256 configured, use bt_graph_add_simple_sink_component(). When you call
257 this function, you pass three user functions:
260 <dt>\bt_dt_opt Initialization</dt>
262 Called when the trace processing graph becomes
263 configured and when the sink component created its single
266 You can do an initial action with the message iterator such as
267 making it seek a specific point in time or getting messages.
272 Called every time the sink component's
273 \ref api-comp-cls-dev-meth-consume "consuming method" is called.
275 You can get the next messages from the component's message
276 iterator and process them.
279 <dt>\bt_dt_opt Finalization</dt>
281 Called when the sink component is finalized.
285 The three functions above receive, as their last parameter, the user
286 data you passed to bt_graph_add_simple_sink_component() .
288 <h2>\anchor api-graph-lc-connect Connect component ports</h2>
290 When you \ref api-graph-lc-add "add a component" to a trace processing
291 graph with one of the <code>bt_graph_add_*_component*()</code>
292 functions, the function sets \bt_p{*component} to the
293 created and added component.
295 With such a \bt_comp, you can borrow one of its \bt_p_port by index or
298 Connect two component ports within a trace processing graph with
299 bt_graph_connect_ports().
301 After you connect component ports, you can still
302 \ref api-graph-lc-add "add" more components to the graph, and then
305 You don't need to connect all the available ports of a given component,
306 depending on the trace processing task you need to perform. However,
307 when you \ref api-graph-lc-run "run" the trace processing graph:
309 - At least one \bt_oport of any \bt_src_comp must be connected.
310 - At least one \bt_iport and one output port of any \bt_flt_comp must
312 - At least one input port of any \bt_sink_comp must be connected.
314 <h2>\anchor api-graph-lc-run Run</h2>
316 When you are done configuring a trace processing graph, you can run it
319 bt_graph_run() does \em not return until one of:
321 - All the sink components are ended: bt_graph_run() returns
322 #BT_GRAPH_RUN_STATUS_OK.
324 - One of the sink component returns an error:
325 bt_graph_run() returns #BT_GRAPH_RUN_STATUS_ERROR or
326 #BT_GRAPH_RUN_STATUS_MEMORY_ERROR.
328 - One of the sink component returns "try again":
329 bt_graph_run() returns #BT_GRAPH_RUN_STATUS_AGAIN.
331 In that case, you can call bt_graph_run() again later, usually after
332 waiting for some time.
334 This feature exists to allow blocking operations within components
335 to be postponed until they don't block. The graph user can perform
336 other tasks instead of the graph's thread blocking.
338 - The trace processing graph is interrupted (see
339 bt_graph_borrow_default_interrupter() and bt_graph_add_interrupter()):
340 bt_graph_run() returns #BT_GRAPH_RUN_STATUS_AGAIN.
342 Check the \bt_intr's state with bt_interrupter_is_set() to
343 distinguish between a sink component returning "try again" and
344 the trace processing graph getting interrupted.
346 If you want to make a single sink component consume and process a few
347 \bt_p_msg before controlling the thread again, use bt_graph_run_once()
348 instead of bt_graph_run().
350 <h1>Standard \bt_name component classes</h1>
352 The \bt_name project ships with project \bt_p_plugin which provide
353 "standard" \bt_p_comp_cls.
355 Those standard component classes can be useful in many trace processing
356 graph topologies. They are:
359 <dt>\c ctf plugin</dt>
362 <dt>\c fs source component class</dt>
365 <a href="https://diamon.org/ctf/">CTF</a> trace on the file
366 system and emits the \bt_p_msg of their data stream files.
368 See \bt_man{babeltrace2-source.ctf.fs,7}.
371 <dt>\c lttng-live source component class</dt>
373 Connects to an <a href="https://lttng.org/">LTTng</a> relay
374 daemon and emits the messages of the received CTF data streams.
376 See \bt_man{babeltrace2-source.ctf.lttng-live,7}.
379 <dt>\c fs sink component class</dt>
381 Writes the consumed messages as one or more CTF traces on the
384 See \bt_man{babeltrace2-sink.ctf.fs,7}.
389 <dt>\c lttng-utils plugin</dt>
392 <dt>\c debug-info filter component class</dt>
394 Adds debugging information to compatible LTTng event messages.
396 This component class is only available if the project was
397 built with the <code>\-\-enable-debug-info</code>
398 configuration option.
400 See \bt_man{babeltrace2-filter.lttng-utils.debug-info,7}.
405 <dt>\c text plugin</dt>
408 <dt>\c dmesg source component class</dt>
410 Reads the lines of a Linux kernel ring buffer, that is, the
412 <a href="http://man7.org/linux/man-pages/man1/dmesg.1.html"><code>dmesg</code></a>
413 tool, and emits each line as an \bt_ev_msg.
415 See \bt_man{babeltrace2-source.text.dmesg,7}.
418 <dt>\c details sink component class</dt>
420 Deterministically prints the messages it consumes with details
421 to the standard output.
423 See \bt_man{babeltrace2-sink.text.details,7}.
426 <dt>\c pretty sink component class</dt>
428 Pretty-prints the messages it consumes to the standard output or
431 This is equivalent to the \c text output format of the
432 <a href="http://man7.org/linux/man-pages/man1/babeltrace.1.html">Babeltrace 1
433 command-line tool</a>.
435 See \bt_man{babeltrace2-sink.text.pretty,7}.
440 <dt>\c utils plugin</dt>
443 <dt>\c muxer filter component class</dt>
445 Muxes messages by time.
447 See \bt_man{babeltrace2-filter.utils.muxer,7}.
450 <dt>\c trimmer filter component class</dt>
452 Discards all the consumed messages with a time outside a given
453 time range, effectively "cutting" \bt_p_stream.
455 See \bt_man{babeltrace2-filter.utils.trimmer,7}.
458 <dt>\c counter sink component class</dt>
460 Prints the number of consumed messages, either once at the end
461 or periodically, to the standard output.
463 See \bt_man{babeltrace2-sink.utils.counter,7}.
466 <dt>\c dummy sink component class</dt>
468 Consumes messages and discards them (does nothing with them).
470 This is useful for testing and benchmarking a trace processing
471 graph application, for example.
473 See \bt_man{babeltrace2-sink.utils.dummy,7}.
479 To access such a component class, get its plugin by name with
480 bt_plugin_find() and then borrow the component class by name
481 with bt_plugin_borrow_source_component_class_by_name_const(),
482 bt_plugin_borrow_filter_component_class_by_name_const(), or
483 bt_plugin_borrow_sink_component_class_by_name_const().
488 const bt_plugin *plugin;
490 if (bt_plugin_find("utils", BT_TRUE, BT_TRUE, BT_TRUE, BT_TRUE, BT_TRUE,
491 &plugin) != BT_PLUGIN_FIND_STATUS_OK) {
495 const bt_component_class_filter *muxer_component_class =
496 bt_plugin_borrow_filter_component_class_by_name_const(plugin, "muxer");
498 if (!muxer_component_class) {
503 <h1>\anchor api-graph-listeners Listeners</h1>
505 A \bt_comp can add a \bt_port:
507 - At initialization time, that is, when you call one of the
508 <code>bt_graph_add_*_component*()</code> functions.
510 - When one of its ports gets connected, that is, when you call
511 bt_graph_connect_ports().
513 To get notified when any component of a given trace processing
514 graph adds a port, add one or more "port
515 added" listeners to the graph with:
517 - bt_graph_add_source_component_output_port_added_listener()
518 - bt_graph_add_filter_component_input_port_added_listener()
519 - bt_graph_add_filter_component_output_port_added_listener()
520 - bt_graph_add_sink_component_input_port_added_listener()
522 Within a "port added" listener function, you can
523 \ref api-graph-lc-add "add more components"
524 and \ref api-graph-lc-connect "connect more component ports".
533 @typedef struct bt_graph bt_graph;
536 Trace processing graph.
548 Creates a default, empty trace processing graph honouring version
549 \bt_p{mip_version} of the \bt_mip.
551 On success, the returned graph contains no components (see
552 \ref api-graph-lc-add "Add components").
554 The graph is configured as operating following version
555 \bt_p{mip_version} of the Message Interchange Protocol, so that
556 bt_self_component_get_graph_mip_version() returns this version when
560 As of \bt_name_version_min_maj, the only available MIP version is 0.
562 The returned graph has a default \bt_intr. Any \bt_comp you add with the
563 <code>bt_graph_add_*_component*()</code> functions and all their
564 \bt_p_msg_iter also have this same default interrupter. Borrow the graph's
565 default interrupter with bt_graph_borrow_default_interrupter().
567 @param[in] mip_version
568 Version of the Message Interchange Protocol to use within the
572 New trace processing graph reference, or \c NULL on memory error.
575 \bt_p{mip_version} is 0.
577 extern bt_graph
*bt_graph_create(uint64_t mip_version
);
582 @name Component adding
589 <code>bt_graph_add_*_component*()</code> functions.
591 typedef enum bt_graph_add_component_status
{
596 BT_GRAPH_ADD_COMPONENT_STATUS_OK
= __BT_FUNC_STATUS_OK
,
602 BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
608 BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
609 } bt_graph_add_component_status
;
613 Alias of bt_graph_add_source_component_with_initialize_method_data()
614 with the \bt_p{initialize_method_data} parameter set to \c NULL.
616 extern bt_graph_add_component_status
617 bt_graph_add_source_component(bt_graph
*graph
,
618 const bt_component_class_source
*component_class
,
619 const char *name
, const bt_value
*params
,
620 bt_logging_level logging_level
,
621 const bt_component_source
**component
);
625 Creates a \bt_src_comp from the
626 \ref api-tir-comp-cls "class" \bt_p{component_class}
627 with the initialization parameters \bt_p{params}, the initialization
628 user data \bt_p{initialize_method_data}, and the initial
629 logging level \bt_p{logging_level}, adds it to the trace processing
630 graph \bt_p{graph} with the name \bt_p{name}, and sets
631 \bt_p{*component} to the resulting component.
633 See \ref api-graph-lc-add "Add components" to learn more about adding
634 components to a trace processing graph.
636 This function calls the source component's
637 \ref api-comp-cls-dev-meth-init "initialization method" after
640 The created source component's initialization method receives:
642 - \bt_p{params} as its own \bt_p{params} parameter (or an empty
643 \bt_map_val if \bt_p{params} is \c NULL).
645 - \bt_p{initialize_method_data} as its own \bt_p{initialize_method_data}
648 The created source component can get its logging level
649 (\bt_p{logging_level}) with bt_component_get_logging_level().
652 Trace processing graph to which to add the created source component.
653 @param[in] component_class
654 Class to instantiate within \bt_p{graph}.
656 Unique name, within \bt_p{graph}, of the component to create.
659 Initialization parameters to use when creating the source component.
661 Can be \c NULL, in which case the created source component's
662 initialization method receives an empty \bt_map_val as its
663 \bt_p{params} parameter.
665 @param[in] initialize_method_data
666 User data passed as is to the created source component's
667 initialization method.
668 @param[in] logging_level
669 Initial logging level of the source component to create.
670 @param[out] component
671 <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
672 a \em borrowed reference of the created source component.
674 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
676 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
678 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
679 Other error, for example, the created source component's
680 initialization method failed.
682 @bt_pre_not_null{graph}
683 @bt_pre_graph_not_configured{graph}
684 @bt_pre_graph_not_faulty{graph}
685 @bt_pre_not_null{component_class}
686 @bt_pre_not_null{name}
688 No other component within \bt_p{graph} has the name \bt_p{name}.
690 \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
693 @bt_post_success_frozen{component_class}
694 @bt_post_success_frozen{params}
696 extern bt_graph_add_component_status
697 bt_graph_add_source_component_with_initialize_method_data(
699 const bt_component_class_source
*component_class
,
700 const char *name
, const bt_value
*params
,
701 void *initialize_method_data
, bt_logging_level logging_level
,
702 const bt_component_source
**component
);
706 Alias of bt_graph_add_filter_component_with_initialize_method_data()
707 with the \bt_p{initialize_method_data} parameter set to \c NULL.
709 extern bt_graph_add_component_status
710 bt_graph_add_filter_component(bt_graph
*graph
,
711 const bt_component_class_filter
*component_class
,
712 const char *name
, const bt_value
*params
,
713 bt_logging_level logging_level
,
714 const bt_component_filter
**component
);
718 Creates a \bt_flt_comp from the
719 \ref api-tir-comp-cls "class" \bt_p{component_class}
720 with the initialization parameters \bt_p{params}, the initialization
721 user data \bt_p{initialize_method_data}, and the initial
722 logging level \bt_p{logging_level}, adds it to the trace processing
723 graph \bt_p{graph} with the name \bt_p{name}, and sets
724 \bt_p{*component} to the resulting component.
726 See \ref api-graph-lc-add "Add components" to learn more about adding
727 components to a trace processing graph.
729 This function calls the filter component's
730 \ref api-comp-cls-dev-meth-init "initialization method" after
733 The created filter component's initialization method receives:
735 - \bt_p{params} as its own \bt_p{params} parameter (or an empty
736 \bt_map_val if \bt_p{params} is \c NULL).
738 - \bt_p{initialize_method_data} as its own \bt_p{initialize_method_data}
741 The created filter component can get its logging level
742 (\bt_p{logging_level}) with bt_component_get_logging_level().
745 Trace processing graph to which to add the created filter component.
746 @param[in] component_class
747 Class to instantiate within \bt_p{graph}.
749 Unique name, within \bt_p{graph}, of the component to create.
752 Initialization parameters to use when creating the filter component.
754 Can be \c NULL, in which case the created filter component's
755 initialization method receives an empty \bt_map_val as its
756 \bt_p{params} parameter.
758 @param[in] initialize_method_data
759 User data passed as is to the created filter component's
760 initialization method.
761 @param[in] logging_level
762 Initial logging level of the filter component to create.
763 @param[out] component
764 <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
765 a \em borrowed reference of the created filter component.
767 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
769 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
771 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
772 Other error, for example, the created filter component's
773 initialization method failed.
775 @bt_pre_not_null{graph}
776 @bt_pre_graph_not_configured{graph}
777 @bt_pre_graph_not_faulty{graph}
778 @bt_pre_not_null{component_class}
779 @bt_pre_not_null{name}
781 No other component within \bt_p{graph} has the name \bt_p{name}.
783 \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
786 @bt_post_success_frozen{component_class}
787 @bt_post_success_frozen{params}
789 extern bt_graph_add_component_status
790 bt_graph_add_filter_component_with_initialize_method_data(
792 const bt_component_class_filter
*component_class
,
793 const char *name
, const bt_value
*params
,
794 void *initialize_method_data
, bt_logging_level logging_level
,
795 const bt_component_filter
**component
);
799 Alias of bt_graph_add_sink_component_with_initialize_method_data()
800 with the \bt_p{initialize_method_data} parameter set to \c NULL.
802 extern bt_graph_add_component_status
803 bt_graph_add_sink_component(
804 bt_graph
*graph
, const bt_component_class_sink
*component_class
,
805 const char *name
, const bt_value
*params
,
806 bt_logging_level logging_level
,
807 const bt_component_sink
**component
);
811 Creates a \bt_sink_comp from the
812 \ref api-tir-comp-cls "class" \bt_p{component_class}
813 with the initialization parameters \bt_p{params}, the initialization
814 user data \bt_p{initialize_method_data}, and the initial
815 logging level \bt_p{logging_level}, adds it to the trace processing
816 graph \bt_p{graph} with the name \bt_p{name}, and sets
817 \bt_p{*component} to the resulting component.
819 See \ref api-graph-lc-add "Add components" to learn more about adding
820 components to a trace processing graph.
822 This function calls the sink component's
823 \ref api-comp-cls-dev-meth-init "initialization method" after
826 The created sink component's initialization method receives:
828 - \bt_p{params} as its own \bt_p{params} parameter (or an empty
829 \bt_map_val if \bt_p{params} is \c NULL).
831 - \bt_p{initialize_method_data} as its own \bt_p{initialize_method_data}
834 The created sink component can get its logging level
835 (\bt_p{logging_level}) with bt_component_get_logging_level().
838 Trace processing graph to which to add the created sink component.
839 @param[in] component_class
840 Class to instantiate within \bt_p{graph}.
842 Unique name, within \bt_p{graph}, of the component to create.
845 Initialization parameters to use when creating the sink component.
847 Can be \c NULL, in which case the created sink component's
848 initialization method receives an empty \bt_map_val as its
849 \bt_p{params} parameter.
851 @param[in] initialize_method_data
852 User data passed as is to the created sink component's
853 initialization method.
854 @param[in] logging_level
855 Initial logging level of the sink component to create.
856 @param[out] component
857 <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
858 a \em borrowed reference of the created sink component.
860 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
862 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
864 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
865 Other error, for example, the created sink component's
866 initialization method failed.
868 @bt_pre_not_null{graph}
869 @bt_pre_graph_not_configured{graph}
870 @bt_pre_graph_not_faulty{graph}
871 @bt_pre_not_null{component_class}
872 @bt_pre_not_null{name}
874 No other component within \bt_p{graph} has the name \bt_p{name}.
876 \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
879 @bt_post_success_frozen{component_class}
880 @bt_post_success_frozen{params}
882 extern bt_graph_add_component_status
883 bt_graph_add_sink_component_with_initialize_method_data(
884 bt_graph
*graph
, const bt_component_class_sink
*component_class
,
885 const char *name
, const bt_value
*params
,
886 void *initialize_method_data
, bt_logging_level logging_level
,
887 const bt_component_sink
**component
);
892 @name Simple sink component adding
898 Status codes for the #bt_graph_simple_sink_component_initialize_func
901 typedef enum bt_graph_simple_sink_component_initialize_func_status
{
906 BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_OK
= __BT_FUNC_STATUS_OK
,
912 BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
918 BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
919 } bt_graph_simple_sink_component_initialize_func_status
;
923 User initialization function for
924 bt_graph_add_simple_sink_component().
926 Such an initialization function is called when the trace processing
927 graph becomes configured and when the simple sink component has created
928 its single \bt_msg_iter. This occurs the first time you call
929 bt_graph_run() or bt_graph_run_once() on the trace processing graph.
931 See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
932 about adding a simple component to a trace processing graph.
934 @param[in] message_iterator
936 Simple sink component's upstream message iterator.
938 This user function is free to get the message iterator's next
939 message or to make it seek.
942 User data, as passed as the \bt_p{user_data} parameter of
943 bt_graph_add_simple_sink_component().
945 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_OK
947 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_MEMORY_ERROR
949 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_ERROR
952 @bt_pre_not_null{message_iterator}
955 The reference count of \bt_p{message_iterator} is not changed.
957 @sa bt_graph_add_simple_sink_component() —
958 Creates and adds a simple sink component to a trace processing
961 typedef bt_graph_simple_sink_component_initialize_func_status
962 (*bt_graph_simple_sink_component_initialize_func
)(
963 bt_message_iterator
*message_iterator
,
968 Status codes for the #bt_graph_simple_sink_component_consume_func
971 typedef enum bt_graph_simple_sink_component_consume_func_status
{
976 BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK
= __BT_FUNC_STATUS_OK
,
982 BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END
= __BT_FUNC_STATUS_END
,
988 BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
994 BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1000 BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1001 } bt_graph_simple_sink_component_consume_func_status
;
1005 User consuming function for bt_graph_add_simple_sink_component().
1007 Such a consuming function is called when the simple sink component's own
1008 \ref api-comp-cls-dev-meth-consume "consuming method" is called. This
1009 occurs in a loop within bt_graph_run() or when it's this sink
1010 component's turn to consume in
1011 bt_graph_run_once().
1013 See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
1014 about adding a simple component to a trace processing graph.
1016 If you are not done consuming messages, return
1017 #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK.
1019 If you are done consuming messages, return
1020 #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END.
1022 If you wish to avoid a blocking operation and make
1023 bt_graph_run() or bt_graph_run_once() aware, return
1024 #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN.
1026 @param[in] message_iterator
1028 Simple sink component's upstream message iterator.
1030 This user function is free to get the message iterator's next
1031 message or to make it seek.
1033 @param[in] user_data
1034 User data, as passed as the \bt_p{user_data} parameter of
1035 bt_graph_add_simple_sink_component().
1037 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK
1039 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END
1041 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN
1043 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_MEMORY_ERROR
1045 @retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_ERROR
1048 @bt_pre_not_null{message_iterator}
1051 The reference count of \bt_p{message_iterator} is not changed.
1053 @sa bt_graph_add_simple_sink_component() —
1054 Creates and adds a simple sink component to a trace processing
1057 typedef bt_graph_simple_sink_component_consume_func_status
1058 (*bt_graph_simple_sink_component_consume_func
)(
1059 bt_message_iterator
*message_iterator
,
1064 User finalization function for bt_graph_add_simple_sink_component().
1066 Such a finalization function is called when the simple sink component
1067 is finalized. This occurs when the trace processing graph is destroyed
1068 (you put its last strong \ref api-fund-shared-object "reference"
1069 with bt_graph_put_ref()).
1071 See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
1072 about adding a simple component to a trace processing graph.
1074 @param[in] user_data
1075 User data, as passed as the \bt_p{user_data} parameter of
1076 bt_graph_add_simple_sink_component().
1080 @sa bt_graph_add_simple_sink_component() —
1081 Creates and adds a simple sink component to a trace processing
1084 typedef void (*bt_graph_simple_sink_component_finalize_func
)(void *user_data
);
1088 Creates a simple \bt_sink_comp, adds it to the trace processing
1089 graph \bt_p{graph} with the name \bt_p{name}, and sets
1090 \bt_p{*component} to the resulting component.
1092 See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
1093 about adding a simple component to a trace processing graph.
1095 \bt_p{initialize_func} (if not \c NULL), \bt_p{consume_func},
1096 and \bt_p{finalize_func} (if not \c NULL) receive \bt_p{user_data}
1097 as their own \bt_p{user_data} parameter.
1100 Trace processing graph to which to add the created simple sink
1103 Unique name, within \bt_p{graph}, of the component to create.
1104 @param[in] initialize_func
1106 User initialization function.
1110 @param[in] consume_func
1111 User consuming function.
1112 @param[in] finalize_func
1114 User finalization function.
1118 @param[in] user_data
1119 User data to pass as the \bt_p{user_data} parameter of
1120 \bt_p{initialize_func}, \bt_p{consume_func}, and
1121 \bt_p{finalize_func}.
1122 @param[out] component
1123 <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
1124 a \em borrowed reference of the created simple sink component.
1126 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
1128 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
1130 @retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
1131 Other error, for example, the created sink component's
1132 \ref api-comp-cls-dev-meth-init "initialization method" failed.
1134 @bt_pre_not_null{graph}
1135 @bt_pre_graph_not_configured{graph}
1136 @bt_pre_graph_not_faulty{graph}
1137 @bt_pre_not_null{name}
1139 No other component within \bt_p{graph} has the name \bt_p{name}.
1140 @bt_pre_not_null{consume_func}
1142 extern bt_graph_add_component_status
1143 bt_graph_add_simple_sink_component(bt_graph
*graph
, const char *name
,
1144 bt_graph_simple_sink_component_initialize_func initialize_func
,
1145 bt_graph_simple_sink_component_consume_func consume_func
,
1146 bt_graph_simple_sink_component_finalize_func finalize_func
,
1147 void *user_data
, const bt_component_sink
**component
);
1152 @name Component port connection
1158 Status codes for bt_graph_connect_ports().
1160 typedef enum bt_graph_connect_ports_status
{
1165 BT_GRAPH_CONNECT_PORTS_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1171 BT_GRAPH_CONNECT_PORTS_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1177 BT_GRAPH_CONNECT_PORTS_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1178 } bt_graph_connect_ports_status
;
1182 Connects the \bt_oport \bt_p{upstream_port} to the \bt_iport
1183 \bt_p{downstream_port} within the trace processing graph
1184 \bt_p{graph}, and sets \bt_p{*connection} to the resulting
1187 See \ref api-graph-lc-connect "Connect component ports" to learn more
1188 about connecting ports within a trace processing graph.
1190 Both \bt_p{upstream_port} and \bt_p{downstream_port} must be
1191 unconnected (bt_port_is_connected() returns #BT_FALSE) when you call
1195 Trace processing graph containing the \bt_p_comp to which belong
1196 \bt_p{upstream_port} and \bt_p{downstream_port}.
1197 @param[in] upstream_port
1198 \bt_c_oport to connect to \bt_p{downstream_port}.
1199 @param[in] downstream_port
1200 \bt_c_iport to connect to \bt_p{upstream_port}.
1201 @param[in] connection
1202 <strong>On success, if not \c NULL</strong>, \bt_p{*connection} is
1203 a \em borrowed reference of the resulting \bt_conn.
1205 @retval #BT_GRAPH_CONNECT_PORTS_STATUS_OK
1207 @retval #BT_GRAPH_CONNECT_PORTS_STATUS_MEMORY_ERROR
1209 @retval #BT_GRAPH_CONNECT_PORTS_STATUS_ERROR
1212 @bt_pre_not_null{graph}
1213 @bt_pre_graph_not_configured{graph}
1214 @bt_pre_graph_not_faulty{graph}
1215 @bt_pre_not_null{upstream_port}
1217 \bt_p{graph} contains the component of \bt_p{upstream_port},
1218 as returned by bt_port_borrow_component_const().
1220 \bt_p{upstream_port} is unconnected
1221 (bt_port_is_connected() returns #BT_FALSE).
1222 @bt_pre_not_null{downstream_port}
1224 \bt_p{graph} contains the component of \bt_p{downstream_port},
1225 as returned by bt_port_borrow_component_const().
1227 \bt_p{downstream_port} is unconnected
1228 (bt_port_is_connected() returns #BT_FALSE).
1230 Connecting \bt_p{upstream_port} to \bt_p{downstream_port} does not
1231 form a connection cycle within \bt_p{graph}.
1233 extern bt_graph_connect_ports_status
bt_graph_connect_ports(bt_graph
*graph
,
1234 const bt_port_output
*upstream_port
,
1235 const bt_port_input
*downstream_port
,
1236 const bt_connection
**connection
);
1247 Status codes for bt_graph_run().
1249 typedef enum bt_graph_run_status
{
1254 BT_GRAPH_RUN_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1260 BT_GRAPH_RUN_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
1266 BT_GRAPH_RUN_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1272 BT_GRAPH_RUN_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1273 } bt_graph_run_status
;
1277 Runs the trace processing graph \bt_p{graph}, calling each
1279 \ref api-comp-cls-dev-meth-consume "consuming method" in a round
1280 robin fashion until they are all done consuming or an exception
1283 See \ref api-graph-lc-run "Run" to learn more about running a trace
1286 This function does \em not return until one of:
1288 - All the sink components are ended, in which case this function
1289 returns #BT_GRAPH_RUN_STATUS_OK.
1291 - One of the sink component returns an error, in which case this
1292 function returns #BT_GRAPH_RUN_STATUS_ERROR or
1293 #BT_GRAPH_RUN_STATUS_MEMORY_ERROR.
1295 - One of the sink component returns "try again", in which case
1296 this function returns #BT_GRAPH_RUN_STATUS_AGAIN.
1298 In that case, you can call this function again later, usually after
1299 waiting for some time.
1301 This feature exists to allow blocking operations within components
1302 to be postponed until they don't block. The graph user can perform
1303 other tasks instead of the graph's thread blocking.
1305 - \bt_p{graph} is interrupted (see bt_graph_borrow_default_interrupter()
1306 and bt_graph_add_interrupter()), in which case this function returns
1307 #BT_GRAPH_RUN_STATUS_AGAIN.
1309 Check the \bt_intr's state with bt_interrupter_is_set() to
1310 distinguish between a sink component returning "try again" and
1311 \bt_p{graph} getting interrupted.
1313 To make a single sink component consume, then get the thread's control
1314 back, use bt_graph_run_once().
1316 When you call this function or bt_graph_run_once() for the first time,
1317 \bt_p{graph} becomes <em>configured</em>. See
1318 \ref api-graph-lc "Trace processing graph life cycle"
1319 to learn what happens when a trace processing graph becomes configured,
1320 and what you can and cannot do with a configured graph.
1323 Trace processing graph to run.
1325 @retval #BT_GRAPH_RUN_STATUS_OK
1327 @retval #BT_GRAPH_RUN_STATUS_AGAIN
1329 @retval #BT_GRAPH_RUN_STATUS_MEMORY_ERROR
1331 @retval #BT_GRAPH_RUN_STATUS_ERROR
1334 @bt_pre_not_null{graph}
1335 @bt_pre_graph_not_faulty{graph}
1337 For each \bt_src_comp within \bt_p{graph}, at least one \bt_oport
1340 For each \bt_flt_comp within \bt_p{graph}, at least one \bt_iport
1341 and one \bt_iport are connected.
1343 For each \bt_sink_comp within \bt_p{graph}, at least one \bt_iport
1346 \bt_p{graph} contains at least one sink component.
1348 @sa bt_graph_run_once() —
1349 Calls a single trace processing graph's sink component's consuming
1352 extern bt_graph_run_status
bt_graph_run(bt_graph
*graph
);
1356 Status codes for bt_graph_run().
1358 typedef enum bt_graph_run_once_status
{
1363 BT_GRAPH_RUN_ONCE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1367 All sink components are finished processing.
1369 BT_GRAPH_RUN_ONCE_STATUS_END
= __BT_FUNC_STATUS_END
,
1375 BT_GRAPH_RUN_ONCE_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
1381 BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1387 BT_GRAPH_RUN_ONCE_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1388 } bt_graph_run_once_status
;
1392 Calls the \ref api-comp-cls-dev-meth-consume "consuming method" of
1393 the next non-ended \bt_sink_comp to make consume within the trace
1394 processing graph \bt_p{graph}.
1396 See \ref api-graph-lc-run "Run" to learn more about running a trace
1399 This function makes the \em next non-ended sink component consume. For
1400 example, if \bt_p{graph} has two non-ended sink components A and B:
1402 - Calling bt_graph_run_once() makes sink component A consume.
1403 - Calling bt_graph_run_once() again makes sink component B consume.
1404 - Calling bt_graph_run_once() again makes sink component A consume.
1407 Considering this, if \bt_p{graph} contains a single non-ended sink
1408 component, this function \em always makes this sink component consume.
1410 If the sink component's consuming method:
1414 <dd>This function returns #BT_GRAPH_RUN_ONCE_STATUS_OK.</dd>
1416 <dt>Returns "try again"</dt>
1417 <dd>This function returns #BT_GRAPH_RUN_ONCE_STATUS_AGAIN.</dd>
1421 This function returns #BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR
1422 or #BT_GRAPH_RUN_ONCE_STATUS_ERROR.
1426 When all the sink components of \bt_p{graph} are finished processing
1427 (ended), this function returns #BT_GRAPH_RUN_ONCE_STATUS_END.
1429 bt_graph_run() calls this function in a loop until are the sink
1430 components are ended or an exception occurs.
1432 When you call this function or bt_graph_run() for the first time,
1433 \bt_p{graph} becomes <em>configured</em>. See
1434 \ref api-graph-lc "Trace processing graph life cycle"
1435 to learn what happens when a trace processing graph becomes configured,
1436 and what you can and cannot do with a configured graph.
1439 Trace processing graph of which to make the next sink component
1442 @retval #BT_GRAPH_RUN_ONCE_STATUS_OK
1444 @retval #BT_GRAPH_RUN_ONCE_STATUS_END
1445 All sink components are finished processing.
1446 @retval #BT_GRAPH_RUN_ONCE_STATUS_AGAIN
1448 @retval #BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR
1450 @retval #BT_GRAPH_RUN_ONCE_STATUS_ERROR
1453 @bt_pre_not_null{graph}
1454 @bt_pre_graph_not_faulty{graph}
1456 @sa bt_graph_run() —
1457 Runs a trace processing graph, making all its sink components
1458 consume in a round robin fashion.
1460 extern bt_graph_run_once_status
bt_graph_run_once(bt_graph
*graph
);
1471 Status codes for bt_graph_add_interrupter().
1473 typedef enum bt_graph_add_interrupter_status
{
1478 BT_GRAPH_ADD_INTERRUPTER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1484 BT_GRAPH_ADD_INTERRUPTER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1485 } bt_graph_add_interrupter_status
;
1489 Adds the \bt_intr \bt_p{interrupter} to all the current and future
1490 \bt_p_sink_comp and \bt_p_msg_iter of the trace processing graph
1491 \bt_p{graph}, as well as to the graph itself.
1493 Sink components can check whether or not they are interrupted
1494 with bt_self_component_sink_is_interrupted().
1496 Message iterators can check whether or not they are interrupted
1497 with bt_self_message_iterator_is_interrupted().
1499 The bt_graph_run() loop intermittently checks whether or not any of the
1500 graph's interrupters is set. If so, bt_graph_run() returns
1501 #BT_GRAPH_RUN_STATUS_AGAIN.
1505 bt_graph_create() returns a trace processing graph which comes
1506 with its own <em>default interrupter</em>.
1508 Instead of adding your own interrupter to \bt_p{graph}, you can
1509 set its default interrupter with
1512 bt_interrupter_set(bt_graph_borrow_default_interrupter());
1517 Trace processing graph to which to add \bt_p{interrupter}.
1518 @param[in] interrupter
1519 Interrupter to add to \bt_p{graph}.
1521 @retval #BT_GRAPH_ADD_INTERRUPTER_STATUS_OK
1523 @retval #BT_GRAPH_ADD_INTERRUPTER_STATUS_MEMORY_ERROR
1526 @bt_pre_not_null{graph}
1527 @bt_pre_graph_not_faulty{graph}
1528 @bt_pre_not_null{interrupter}
1530 @sa bt_graph_borrow_default_interrupter() —
1531 Borrows the default interrupter from a trace processing graph.
1533 extern bt_graph_add_interrupter_status
bt_graph_add_interrupter(bt_graph
*graph
,
1534 const bt_interrupter
*interrupter
);
1538 Borrows the default \bt_intr from the trace processing graph
1542 Trace processing graph from which to borrow the default interrupter.
1546 \em Borrowed reference of the default interrupter of \bt_p{graph}.
1548 The returned pointer remains valid as long as \bt_p{graph} exists.
1551 @bt_pre_not_null{graph}
1553 @sa bt_graph_add_interrupter() —
1554 Adds an interrupter to a trace processing graph.
1556 extern bt_interrupter
*bt_graph_borrow_default_interrupter(bt_graph
*graph
);
1567 Status codes for the
1568 <code>bt_graph_add_*_component_*_port_added_listener()</code>
1571 typedef enum bt_graph_add_listener_status
{
1576 BT_GRAPH_ADD_LISTENER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1582 BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1583 } bt_graph_add_listener_status
;
1587 Status codes for the
1588 <code>bt_graph_*_component_*_port_added_listener_func()</code>
1591 typedef enum bt_graph_listener_func_status
{
1596 BT_GRAPH_LISTENER_FUNC_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1602 BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1608 BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1609 } bt_graph_listener_func_status
;
1614 bt_graph_add_filter_component_input_port_added_listener().
1616 Such a function is called whenever a \bt_flt_comp within a trace
1617 processing graph adds an \bt_iport during the graph
1618 \ref api-graph-lc "configuration" phase.
1620 See \ref api-graph-listeners "Listeners" to learn more.
1622 @param[in] component
1623 Filter component which added \bt_p{port}.
1625 Input port added by \bt_p{component}.
1626 @param[in] user_data
1627 User data, as passed as the \bt_p{user_data} parameter of
1628 bt_graph_add_filter_component_input_port_added_listener().
1630 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
1632 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
1634 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
1637 @bt_pre_not_null{component}
1638 @bt_pre_not_null{port}
1640 @sa bt_graph_add_filter_component_input_port_added_listener() —
1641 Adds a "filter component input port added" listener to a trace
1644 typedef bt_graph_listener_func_status
1645 (*bt_graph_filter_component_input_port_added_listener_func
)(
1646 const bt_component_filter
*component
,
1647 const bt_port_input
*port
, void *user_data
);
1651 Adds a \"\bt_flt_comp \bt_iport added\" listener to the trace
1652 processing graph \bt_p{graph}.
1654 Once this function returns, \bt_p{user_func} is called whenever a
1655 filter component adds an input port within \bt_p{graph}.
1657 See \ref api-graph-listeners "Listeners" to learn more.
1660 Trace processing graph to add the "filter component input port
1662 @param[in] user_func
1663 User function of the "filter component input port added" listener to
1664 add to \bt_p{graph}.
1665 @param[in] user_data
1666 User data to pass as the \bt_p{user_data} parameter of
1668 @param[out] listener_id
1669 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
1670 is the ID of the added listener within \bt_p{graph}.
1672 @retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
1674 @retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
1677 @bt_pre_not_null{graph}
1678 @bt_pre_graph_not_faulty{graph}
1679 @bt_pre_not_null{user_func}
1681 extern bt_graph_add_listener_status
1682 bt_graph_add_filter_component_input_port_added_listener(
1684 bt_graph_filter_component_input_port_added_listener_func user_func
,
1685 void *user_data
, bt_listener_id
*listener_id
);
1690 bt_graph_add_sink_component_input_port_added_listener().
1692 Such a function is called whenever a \bt_sink_comp within a trace
1693 processing graph adds an \bt_iport during the graph
1694 \ref api-graph-lc "configuration" phase.
1696 See \ref api-graph-listeners "Listeners" to learn more.
1698 @param[in] component
1699 Filter component which added \bt_p{port}.
1701 Input port added by \bt_p{component}.
1702 @param[in] user_data
1703 User data, as passed as the \bt_p{user_data} parameter of
1704 bt_graph_add_sink_component_input_port_added_listener().
1706 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
1708 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
1710 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
1713 @bt_pre_not_null{component}
1714 @bt_pre_not_null{port}
1716 @sa bt_graph_add_sink_component_input_port_added_listener() —
1717 Adds a "sink component input port added" listener to a trace
1720 typedef bt_graph_listener_func_status
1721 (*bt_graph_sink_component_input_port_added_listener_func
)(
1722 const bt_component_sink
*component
,
1723 const bt_port_input
*port
, void *user_data
);
1727 Adds a \"\bt_sink_comp \bt_iport added\" listener to the trace
1728 processing graph \bt_p{graph}.
1730 Once this function returns, \bt_p{user_func} is called whenever a
1731 sink component adds an input port within \bt_p{graph}.
1733 See \ref api-graph-listeners "Listeners" to learn more.
1736 Trace processing graph to add the "sink component input port
1738 @param[in] user_func
1739 User function of the "sink component input port added" listener to
1740 add to \bt_p{graph}.
1741 @param[in] user_data
1742 User data to pass as the \bt_p{user_data} parameter of
1744 @param[out] listener_id
1745 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
1746 is the ID of the added listener within \bt_p{graph}.
1748 @retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
1750 @retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
1753 @bt_pre_not_null{graph}
1754 @bt_pre_graph_not_faulty{graph}
1755 @bt_pre_not_null{user_func}
1757 extern bt_graph_add_listener_status
1758 bt_graph_add_sink_component_input_port_added_listener(
1760 bt_graph_sink_component_input_port_added_listener_func user_func
,
1761 void *user_data
, bt_listener_id
*listener_id
);
1766 bt_graph_add_source_component_output_port_added_listener().
1768 Such a function is called whenever a \bt_src_comp within a trace
1769 processing graph adds an \bt_oport during the graph
1770 \ref api-graph-lc "configuration" phase.
1772 See \ref api-graph-listeners "Listeners" to learn more.
1774 @param[in] component
1775 Filter component which added \bt_p{port}.
1777 Input port added by \bt_p{component}.
1778 @param[in] user_data
1779 User data, as passed as the \bt_p{user_data} parameter of
1780 bt_graph_add_source_component_output_port_added_listener().
1782 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
1784 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
1786 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
1789 @bt_pre_not_null{component}
1790 @bt_pre_not_null{port}
1792 @sa bt_graph_add_source_component_output_port_added_listener() —
1793 Adds a "source component output port added" listener to a trace
1796 typedef bt_graph_listener_func_status
1797 (*bt_graph_source_component_output_port_added_listener_func
)(
1798 const bt_component_source
*component
,
1799 const bt_port_output
*port
, void *user_data
);
1803 Adds a \"\bt_src_comp \bt_oport added\" listener to the trace
1804 processing graph \bt_p{graph}.
1806 Once this function returns, \bt_p{user_func} is called whenever a
1807 source component adds an output port within \bt_p{graph}.
1809 See \ref api-graph-listeners "Listeners" to learn more.
1812 Trace processing graph to add the "source component output port
1814 @param[in] user_func
1815 User function of the "source component output port added" listener
1816 to add to \bt_p{graph}.
1817 @param[in] user_data
1818 User data to pass as the \bt_p{user_data} parameter of
1820 @param[out] listener_id
1821 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
1822 is the ID of the added listener within \bt_p{graph}.
1824 @retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
1826 @retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
1829 @bt_pre_not_null{graph}
1830 @bt_pre_graph_not_faulty{graph}
1831 @bt_pre_not_null{user_func}
1833 extern bt_graph_add_listener_status
1834 bt_graph_add_source_component_output_port_added_listener(
1836 bt_graph_source_component_output_port_added_listener_func user_func
,
1837 void *user_data
, bt_listener_id
*listener_id
);
1842 bt_graph_add_filter_component_output_port_added_listener().
1844 Such a function is called whenever a \bt_flt_comp within a trace
1845 processing graph adds an \bt_oport during the graph
1846 \ref api-graph-lc "configuration" phase.
1848 See \ref api-graph-listeners "Listeners" to learn more.
1850 @param[in] component
1851 Filter component which added \bt_p{port}.
1853 Input port added by \bt_p{component}.
1854 @param[in] user_data
1855 User data, as passed as the \bt_p{user_data} parameter of
1856 bt_graph_add_filter_component_output_port_added_listener().
1858 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
1860 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
1862 @retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
1865 @bt_pre_not_null{component}
1866 @bt_pre_not_null{port}
1868 @sa bt_graph_add_filter_component_output_port_added_listener() —
1869 Adds a "filter component output port added" listener to a trace
1872 typedef bt_graph_listener_func_status
1873 (*bt_graph_filter_component_output_port_added_listener_func
)(
1874 const bt_component_filter
*component
,
1875 const bt_port_output
*port
, void *user_data
);
1879 Adds a \"\bt_flt_comp \bt_oport added\" listener to the trace
1880 processing graph \bt_p{graph}.
1882 Once this function returns, \bt_p{user_func} is called whenever a
1883 filter component adds an output port within \bt_p{graph}.
1885 See \ref api-graph-listeners "Listeners" to learn more.
1888 Trace processing graph to add the "filter component output port
1890 @param[in] user_func
1891 User function of the "filter component output port added" listener
1892 to add to \bt_p{graph}.
1893 @param[in] user_data
1894 User data to pass as the \bt_p{user_data} parameter of
1896 @param[out] listener_id
1897 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
1898 is the ID of the added listener within \bt_p{graph}.
1900 @retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
1902 @retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
1905 @bt_pre_not_null{graph}
1906 @bt_pre_graph_not_faulty{graph}
1907 @bt_pre_not_null{user_func}
1909 extern bt_graph_add_listener_status
1910 bt_graph_add_filter_component_output_port_added_listener(
1912 bt_graph_filter_component_output_port_added_listener_func user_func
,
1913 void *user_data
, bt_listener_id
*listener_id
);
1918 @name Reference count
1924 Increments the \ref api-fund-shared-object "reference count" of
1925 the trace processing graph \bt_p{graph}.
1929 Trace processing graph of which to increment the reference count.
1934 @sa bt_graph_put_ref() —
1935 Decrements the reference count of a trace processing graph.
1937 extern void bt_graph_get_ref(const bt_graph
*graph
);
1941 Decrements the \ref api-fund-shared-object "reference count" of
1942 the trace processing graph \bt_p{graph}.
1946 Trace processing graph of which to decrement the reference count.
1951 @sa bt_graph_get_ref() —
1952 Increments the reference count of a trace processing graph.
1954 extern void bt_graph_put_ref(const bt_graph
*graph
);
1958 Decrements the reference count of the trace processing graph
1959 \bt_p{_graph}, and then sets \bt_p{_graph} to \c NULL.
1963 Trace processing graph of which to decrement the reference count.
1965 Can contain \c NULL.
1968 @bt_pre_assign_expr{_graph}
1970 #define BT_GRAPH_PUT_REF_AND_RESET(_graph) \
1972 bt_graph_put_ref(_graph); \
1978 Decrements the reference count of the trace processing graph
1979 \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets
1980 \bt_p{_src} to \c NULL.
1982 This macro effectively moves a trace processing graph reference from the
1983 expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
1984 existing \bt_p{_dst} reference.
1988 Destination expression.
1990 Can contain \c NULL.
1996 Can contain \c NULL.
1999 @bt_pre_assign_expr{_dst}
2000 @bt_pre_assign_expr{_src}
2002 #define BT_GRAPH_MOVE_REF(_dst, _src) \
2004 bt_graph_put_ref(_dst); \
2017 #endif /* BABELTRACE2_GRAPH_GRAPH_H */