Detailed Description

Trace processing graph.

A trace processing graph is a specialized filter graph to manipulate one or more traces.

Whereas the nodes of a multimedia filter graph typically exchange video frames and audio samples, the nodes, or components, of a trace processing graph exchange immutable messages containing trace data.

The following illustration shows a basic trace processing graph which converts many traces to a single log of pretty-printed lines:

Basic trace processing graph (conversion graph).

In the illustrations above, notice that:

The graph (blue) contains five components.
Three source components (green) are connected to a single filter component (yellow).

There are five connections, from five output ports to five input ports.
The filter component is connected to a single sink component (red).

There's a single connection.
Source components read external resources while the sink component writes to the standard output or to a file.
There are two source components having the same class: source.ctf.fs.
All components are instances of plugin-provided classes: babeltrace2-plugin-ctf.so, user-plugin.so, babeltrace2-plugin-utils.so, and babeltrace2-plugin-text.so.

Of course the topology can be much more complex if needed:

Complex trace processing graph.

In a trace processing graph, components are instances of component classes.

A plugin can provide a component class, but you can also create one dynamically (see Component class development).

The connections between component ports in a trace processing graph indicate the needed topology to achieve a trace processing task. That being said, messages do not flow within connections. Instead, a source-to-sink or filter-to-sink connection makes it possible for a sink component to create a message iterator on its end of the connection (an input port). In turn, a filter component message iterator can create other message iterators on one or more of the component's input ports. For a single connection, there can exist multiple message iterators.

A trace processing graph is a shared object: get a new reference with bt_graph_get_ref() and put an existing reference with bt_graph_put_ref().

The type of a trace processing graph is bt_graph.

Create a default trace processing graph with bt_graph_create(). You need to pass a Message Interchange Protocol (MIP) version number when you call this function. Then, see Trace processing graph life cycle to learn how to add components to the graph, connect their ports, and run it.

To interrupt a running trace processing graph, either:

Borrow the graph's default interrupter with bt_graph_borrow_default_interrupter() and set it with bt_interrupter_set().

When you call bt_graph_create(), the returned trace processing graph has a default interrupter.
Add your own interrupter with bt_graph_add_interrupter() before you run the graph with bt_graph_run() or bt_graph_run_once().

Then, set the interrupter with bt_interrupter_set().

Trace processing graph life cycle

The following diagram shows the life cycle of a trace processing graph:

Trace processing graph lifecycle.

After you create a default (empty) trace processing graph with bt_graph_create(), there are three steps to make the trace processing task execute:

You can repeat steps 1 and 2 before step 3, as connecting a component port can make this component create a new port: you might want to add a component in reaction to this event (see Listeners).

Steps 1 and 2 constitute the configuration phase of the trace processing graph. The first time you call bt_graph_run() or bt_graph_run_once() for a given graph (step 3), the graph becomes configured, and it notifies the sink components as such so that they can create their message iterators.

Once a trace processing graph becomes configured:

You cannot add a component to it.
You cannot connect component ports.
Components cannot add ports.

In general, as of Babeltrace 2.0:

You cannot remove a component from a trace processing graph.
You cannot end (remove) a port connection.
Components cannot remove ports.

If any error occurs (a function returns a status code which ends with ERROR) during step 1 or 2, the trace processing graph is considered faulty: you cannot use it anymore. The only functions you can call with a faulty graph are bt_graph_get_ref() and bt_graph_put_ref().

Add components

Adding a component to a trace processing graph is also known as instantiating a component class because the graph must first create the component from its class before adding it.

Because component and component class C types are highly specific, there are six functions to add a component to a trace processing graph:

Source component

Without initialization method data

bt_graph_add_source_component()

With initialization method data

bt_graph_add_source_component_with_initialize_method_data()

Filter component

Without initialization method data

bt_graph_add_filter_component()

With initialization method data

bt_graph_add_filter_component_with_initialize_method_data()

Sink component

Without initialization method data

bt_graph_add_sink_component()

With initialization method data

bt_graph_add_sink_component_with_initialize_method_data()

The *_with_initialize_method_data() versions can pass a custom, void * pointer to the component's initialization method. The other versions pass NULL as this parameter.

All the functions above accept the same parameters:

Parameters

[in]	graph	Trace processing graph to which to add the created component.
[in]	component_class	Class to instantiate within graph.
[in]	name	Unique name of the component to add within graph.
[in]	params	Initialization parameters to use when creating the component.
[in]	logging_level	Initial logging level of the component to create.
[out]	component	On success, *component is the created component.

Once you have the created and added component (*component), you can borrow its ports to connect them.

You can add as many components as needed to a trace processing graph, but they must all have a unique name.

Add a simple sink component

To add a very basic sink component which has a single input port and creates a single message iterator when the trace processing graph becomes configured, use bt_graph_add_simple_sink_component(). When you call this function, you pass three user functions:

Optional: Initialization

Called when the trace processing graph becomes configured and when the sink component created its single message iterator.

You can do an initial action with the message iterator such as making it seek a specific point in time or getting messages.

Consume

Called every time the sink component's consuming method is called.

You can get the next messages from the component's message iterator and process them.

Optional: Finalization

Called when the sink component is finalized.

The three functions above receive, as their last parameter, the user data you passed to bt_graph_add_simple_sink_component() .

Connect component ports

When you add a component to a trace processing graph with one of the bt_graph_add_*_component*() functions, the function sets *component to the created and added component.

With such a component, you can borrow one of its ports by index or by name.

Connect two component ports within a trace processing graph with bt_graph_connect_ports().

After you connect component ports, you can still add more components to the graph, and then connect more ports.

You don't need to connect all the available ports of a given component, depending on the trace processing task you need to perform. However, when you run the trace processing graph:

At least one output port of any source component must be connected.
At least one input port and one output port of any filter component must be connected.
At least one input port of any sink component must be connected.

Run

When you are done configuring a trace processing graph, you can run it with bt_graph_run().

bt_graph_run() does not return until one of:

All the sink components are ended: bt_graph_run() returns BT_GRAPH_RUN_STATUS_OK.
One of the sink component returns an error: bt_graph_run() returns BT_GRAPH_RUN_STATUS_ERROR or BT_GRAPH_RUN_STATUS_MEMORY_ERROR.
One of the sink component returns "try again": bt_graph_run() returns BT_GRAPH_RUN_STATUS_AGAIN.

In that case, you can call bt_graph_run() again later, usually after waiting for some time.

This feature exists to allow blocking operations within components to be postponed until they don't block. The graph user can perform other tasks instead of the graph's thread blocking.
The trace processing graph is interrupted (see bt_graph_borrow_default_interrupter() and bt_graph_add_interrupter()): bt_graph_run() returns BT_GRAPH_RUN_STATUS_AGAIN.

Check the interrupter's state with bt_interrupter_is_set() to distinguish between a sink component returning "try again" and the trace processing graph getting interrupted.

If you want to make a single sink component consume and process a few messages before controlling the thread again, use bt_graph_run_once() instead of bt_graph_run().

Standard Babeltrace 2 component classes

The Babeltrace 2 project ships with project plugins which provide "standard" component classes.

Those standard component classes can be useful in many trace processing graph topologies. They are:

ctf plugin

fs source component class

Opens a CTF trace on the file system and emits the messages of their data stream files.

See babeltrace2-source.ctf.fs(7).

lttng-live source component class

Connects to an LTTng relay daemon and emits the messages of the received CTF data streams.

See babeltrace2-source.ctf.lttng-live(7).

fs sink component class

Writes the consumed messages as one or more CTF traces on the file system.

See babeltrace2-sink.ctf.fs(7).

lttng-utils plugin

debug-info filter component class

Adds debugging information to compatible LTTng event messages.

This component class is only available if the project was built with the --enable-debug-info configuration option.

See babeltrace2-filter.lttng-utils.debug-info(7).

text plugin

dmesg source component class

Reads the lines of a Linux kernel ring buffer, that is, the output of the dmesg tool, and emits each line as an event message.

See babeltrace2-source.text.dmesg(7).

details sink component class

Deterministically prints the messages it consumes with details to the standard output.

See babeltrace2-sink.text.details(7).

pretty sink component class

Pretty-prints the messages it consumes to the standard output or to a file.

This is equivalent to the text output format of the Babeltrace 1 command-line tool.

See babeltrace2-sink.text.pretty(7).

utils plugin

muxer filter component class

Muxes messages by time.

See babeltrace2-filter.utils.muxer(7).

trimmer filter component class

Discards all the consumed messages with a time outside a given time range, effectively "cutting" streams.

See babeltrace2-filter.utils.trimmer(7).

counter sink component class

Prints the number of consumed messages, either once at the end or periodically, to the standard output.

See babeltrace2-sink.utils.counter(7).

dummy sink component class

Consumes messages and discards them (does nothing with them).

This is useful for testing and benchmarking a trace processing graph application, for example.

See babeltrace2-sink.utils.dummy(7).

To access such a component class, get its plugin by name with bt_plugin_find() and then borrow the component class by name with bt_plugin_borrow_source_component_class_by_name_const(), bt_plugin_borrow_filter_component_class_by_name_const(), or bt_plugin_borrow_sink_component_class_by_name_const().

For example:

const bt_plugin *plugin;
 
if (bt_plugin_find("utils", BT_TRUE, BT_TRUE, BT_TRUE, BT_TRUE, BT_TRUE,
                   &plugin) != BT_PLUGIN_FIND_STATUS_OK) {
    // handle error
}
 
const bt_component_class_filter *muxer_component_class =
    bt_plugin_borrow_filter_component_class_by_name_const(plugin, "muxer");
 
if (!muxer_component_class) {
    // handle error
}

Listeners

A component can add a port:

At initialization time, that is, when you call one of the bt_graph_add_*_component*() functions.
When one of its ports gets connected, that is, when you call bt_graph_connect_ports().

To get notified when any component of a given trace processing graph adds a port, add one or more "port added" listeners to the graph with:

Within a "port added" listener function, you can add more components and connect more component ports.

Modules
	Component class development
	Component class development (creation).

	Components
	Source, filter, and sink components: nodes in a trace processing graph.

	Component classes
	Source, filter, and sink component classes (non-development).

	Component descriptor set
	Set of descriptors of prospective components to use with bt_get_greatest_operative_mip_version().

	Connection
	Component port connection.

	Interrupter
	Interrupter.

	Query executor
	Executor of component class object queries.

Type
typedef struct bt_graph	bt_graph
	Trace processing graph.

Creation
bt_graph *	bt_graph_create (uint64_t mip_version)
	Creates a default, empty trace processing graph honouring version mip_version of the Message Interchange Protocol. More...

Component adding
enum	bt_graph_add_component_status { BT_GRAPH_ADD_COMPONENT_STATUS_OK, BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR, BT_GRAPH_ADD_COMPONENT_STATUS_ERROR }
	Status codes for the `bt_graph_add__component()` functions. More...

typedef enum bt_graph_add_component_status	bt_graph_add_component_status
	Status codes for the `bt_graph_add__component()` functions.

bt_graph_add_component_status	bt_graph_add_source_component (bt_graph graph, const bt_component_class_source component_class, const char name, const bt_value params, bt_logging_level logging_level, const bt_component_source **component)
	Alias of bt_graph_add_source_component_with_initialize_method_data() with the initialize_method_data parameter set to `NULL`.

bt_graph_add_component_status	bt_graph_add_source_component_with_initialize_method_data (bt_graph graph, const bt_component_class_source component_class, const char name, const bt_value params, void initialize_method_data, bt_logging_level logging_level, const bt_component_source *component)
	Creates a source component from the class component_class with the initialization parameters params, the initialization user data initialize_method_data, and the initial logging level logging_level, adds it to the trace processing graph graph with the name name, and sets *component to the resulting component. More...

bt_graph_add_component_status	bt_graph_add_filter_component (bt_graph graph, const bt_component_class_filter component_class, const char name, const bt_value params, bt_logging_level logging_level, const bt_component_filter **component)
	Alias of bt_graph_add_filter_component_with_initialize_method_data() with the initialize_method_data parameter set to `NULL`.

bt_graph_add_component_status	bt_graph_add_filter_component_with_initialize_method_data (bt_graph graph, const bt_component_class_filter component_class, const char name, const bt_value params, void initialize_method_data, bt_logging_level logging_level, const bt_component_filter *component)
	Creates a filter component from the class component_class with the initialization parameters params, the initialization user data initialize_method_data, and the initial logging level logging_level, adds it to the trace processing graph graph with the name name, and sets *component to the resulting component. More...

bt_graph_add_component_status	bt_graph_add_sink_component (bt_graph graph, const bt_component_class_sink component_class, const char name, const bt_value params, bt_logging_level logging_level, const bt_component_sink **component)
	Alias of bt_graph_add_sink_component_with_initialize_method_data() with the initialize_method_data parameter set to `NULL`.

bt_graph_add_component_status	bt_graph_add_sink_component_with_initialize_method_data (bt_graph graph, const bt_component_class_sink component_class, const char name, const bt_value params, void initialize_method_data, bt_logging_level logging_level, const bt_component_sink *component)
	Creates a sink component from the class component_class with the initialization parameters params, the initialization user data initialize_method_data, and the initial logging level logging_level, adds it to the trace processing graph graph with the name name, and sets *component to the resulting component. More...

Simple sink component adding
enum	bt_graph_simple_sink_component_initialize_func_status { BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_OK, BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_MEMORY_ERROR, BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_ERROR }
	Status codes for the bt_graph_simple_sink_component_initialize_func type. More...

enum	bt_graph_simple_sink_component_consume_func_status { BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK, BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END, BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN, BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_MEMORY_ERROR, BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_ERROR }
	Status codes for the bt_graph_simple_sink_component_consume_func type. More...

typedef enum bt_graph_simple_sink_component_initialize_func_status	bt_graph_simple_sink_component_initialize_func_status
	Status codes for the bt_graph_simple_sink_component_initialize_func type.

typedef bt_graph_simple_sink_component_initialize_func_status(*	bt_graph_simple_sink_component_initialize_func) (bt_message_iterator message_iterator, void user_data)
	User initialization function for bt_graph_add_simple_sink_component(). More...

typedef enum bt_graph_simple_sink_component_consume_func_status	bt_graph_simple_sink_component_consume_func_status
	Status codes for the bt_graph_simple_sink_component_consume_func type.

typedef bt_graph_simple_sink_component_consume_func_status(*	bt_graph_simple_sink_component_consume_func) (bt_message_iterator message_iterator, void user_data)
	User consuming function for bt_graph_add_simple_sink_component(). More...

typedef void(*	bt_graph_simple_sink_component_finalize_func) (void *user_data)
	User finalization function for bt_graph_add_simple_sink_component(). More...

bt_graph_add_component_status	bt_graph_add_simple_sink_component (bt_graph graph, const char name, bt_graph_simple_sink_component_initialize_func initialize_func, bt_graph_simple_sink_component_consume_func consume_func, bt_graph_simple_sink_component_finalize_func finalize_func, void user_data, const bt_component_sink *component)
	Creates a simple sink component, adds it to the trace processing graph graph with the name name, and sets *component to the resulting component. More...

Component port connection
enum	bt_graph_connect_ports_status { BT_GRAPH_CONNECT_PORTS_STATUS_OK, BT_GRAPH_CONNECT_PORTS_STATUS_MEMORY_ERROR, BT_GRAPH_CONNECT_PORTS_STATUS_ERROR }
	Status codes for bt_graph_connect_ports(). More...

typedef enum bt_graph_connect_ports_status	bt_graph_connect_ports_status
	Status codes for bt_graph_connect_ports().

bt_graph_connect_ports_status	bt_graph_connect_ports (bt_graph graph, const bt_port_output upstream_port, const bt_port_input downstream_port, const bt_connection *connection)
	Connects the output port upstream_port to the input port downstream_port within the trace processing graph graph, and sets *connection to the resulting connection. More...

Running
enum	bt_graph_run_status { BT_GRAPH_RUN_STATUS_OK, BT_GRAPH_RUN_STATUS_AGAIN, BT_GRAPH_RUN_STATUS_MEMORY_ERROR, BT_GRAPH_RUN_STATUS_ERROR }
	Status codes for bt_graph_run(). More...

enum	bt_graph_run_once_status { BT_GRAPH_RUN_ONCE_STATUS_OK, BT_GRAPH_RUN_ONCE_STATUS_END, BT_GRAPH_RUN_ONCE_STATUS_AGAIN, BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR, BT_GRAPH_RUN_ONCE_STATUS_ERROR }
	Status codes for bt_graph_run(). More...

typedef enum bt_graph_run_status	bt_graph_run_status
	Status codes for bt_graph_run().

typedef enum bt_graph_run_once_status	bt_graph_run_once_status
	Status codes for bt_graph_run().

bt_graph_run_status	bt_graph_run (bt_graph *graph)
	Runs the trace processing graph graph, calling each sink component's consuming method in a round robin fashion until they are all done consuming or an exception occurs. More...

bt_graph_run_once_status	bt_graph_run_once (bt_graph *graph)
	Calls the consuming method of the next non-ended sink component to make consume within the trace processing graph graph. More...

Interruption
enum	bt_graph_add_interrupter_status { BT_GRAPH_ADD_INTERRUPTER_STATUS_OK, BT_GRAPH_ADD_INTERRUPTER_STATUS_MEMORY_ERROR }
	Status codes for bt_graph_add_interrupter(). More...

typedef enum bt_graph_add_interrupter_status	bt_graph_add_interrupter_status
	Status codes for bt_graph_add_interrupter().

bt_graph_add_interrupter_status	bt_graph_add_interrupter (bt_graph graph, const bt_interrupter interrupter)
	Adds the interrupter interrupter to all the current and future sink components and message iterators of the trace processing graph graph, as well as to the graph itself. More...

bt_interrupter *	bt_graph_borrow_default_interrupter (bt_graph *graph)
	Borrows the default interrupter from the trace processing graph graph. More...

Listeners
enum	bt_graph_add_listener_status { BT_GRAPH_ADD_LISTENER_STATUS_OK, BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR }
	Status codes for the `bt_graph_add__component__port_added_listener()` functions. More...

enum	bt_graph_listener_func_status { BT_GRAPH_LISTENER_FUNC_STATUS_OK, BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR, BT_GRAPH_LISTENER_FUNC_STATUS_ERROR }
	Status codes for the `bt_graph__component__port_added_listener_func()` types. More...

typedef enum bt_graph_add_listener_status	bt_graph_add_listener_status
	Status codes for the `bt_graph_add__component__port_added_listener()` functions.

typedef enum bt_graph_listener_func_status	bt_graph_listener_func_status
	Status codes for the `bt_graph__component__port_added_listener_func()` types.

typedef bt_graph_listener_func_status(*	bt_graph_filter_component_input_port_added_listener_func) (const bt_component_filter component, const bt_port_input port, void *user_data)
	User function for bt_graph_add_filter_component_input_port_added_listener(). More...

typedef bt_graph_listener_func_status(*	bt_graph_sink_component_input_port_added_listener_func) (const bt_component_sink component, const bt_port_input port, void *user_data)
	User function for bt_graph_add_sink_component_input_port_added_listener(). More...

typedef bt_graph_listener_func_status(*	bt_graph_source_component_output_port_added_listener_func) (const bt_component_source component, const bt_port_output port, void *user_data)
	User function for bt_graph_add_source_component_output_port_added_listener(). More...

typedef bt_graph_listener_func_status(*	bt_graph_filter_component_output_port_added_listener_func) (const bt_component_filter component, const bt_port_output port, void *user_data)
	User function for bt_graph_add_filter_component_output_port_added_listener(). More...

bt_graph_add_listener_status	bt_graph_add_filter_component_input_port_added_listener (bt_graph graph, bt_graph_filter_component_input_port_added_listener_func user_func, void user_data, bt_listener_id *listener_id)
	Adds a "filter component input port added" listener to the trace processing graph graph. More...

bt_graph_add_listener_status	bt_graph_add_sink_component_input_port_added_listener (bt_graph graph, bt_graph_sink_component_input_port_added_listener_func user_func, void user_data, bt_listener_id *listener_id)
	Adds a "sink component input port added" listener to the trace processing graph graph. More...

bt_graph_add_listener_status	bt_graph_add_source_component_output_port_added_listener (bt_graph graph, bt_graph_source_component_output_port_added_listener_func user_func, void user_data, bt_listener_id *listener_id)
	Adds a "source component output port added" listener to the trace processing graph graph. More...

bt_graph_add_listener_status	bt_graph_add_filter_component_output_port_added_listener (bt_graph graph, bt_graph_filter_component_output_port_added_listener_func user_func, void user_data, bt_listener_id *listener_id)
	Adds a "filter component output port added" listener to the trace processing graph graph. More...

Reference count
void	bt_graph_get_ref (const bt_graph *graph)
	Increments the reference count of the trace processing graph graph. More...

void	bt_graph_put_ref (const bt_graph *graph)
	Decrements the reference count of the trace processing graph graph. More...

#define	BT_GRAPH_PUT_REF_AND_RESET(_graph)
	Decrements the reference count of the trace processing graph _graph, and then sets _graph to `NULL`. More...

#define	BT_GRAPH_MOVE_REF(_dst, _src)
	Decrements the reference count of the trace processing graph _dst, sets _dst to _src, and then sets _src to `NULL`. More...

Typedef Documentation

◆ bt_graph_simple_sink_component_initialize_func

typedef bt_graph_simple_sink_component_initialize_func_status(* bt_graph_simple_sink_component_initialize_func) (bt_message_iterator *message_iterator, void *user_data)

User initialization function for bt_graph_add_simple_sink_component().

Such an initialization function is called when the trace processing graph becomes configured and when the simple sink component has created its single message iterator. This occurs the first time you call bt_graph_run() or bt_graph_run_once() on the trace processing graph.

See Add a simple sink component to learn more about adding a simple component to a trace processing graph.

Parameters

[in]

message_iterator

Simple sink component's upstream message iterator.

This user function is free to get the message iterator's next message or to make it seek.

[in] user_data User data, as passed as the user_data parameter of bt_graph_add_simple_sink_component().

Return values

BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_OK	Success.
BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_MEMORY_ERROR	Out of memory.
BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_ERROR	Other error.

Precondition: message_iterator is not NULL.

Postcondition: The reference count of message_iterator is not changed.

See also: bt_graph_add_simple_sink_component() — Creates and adds a simple sink component to a trace processing graph.

◆ bt_graph_simple_sink_component_consume_func

typedef bt_graph_simple_sink_component_consume_func_status(* bt_graph_simple_sink_component_consume_func) (bt_message_iterator *message_iterator, void *user_data)

User consuming function for bt_graph_add_simple_sink_component().

Such a consuming function is called when the simple sink component's own consuming method is called. This occurs in a loop within bt_graph_run() or when it's this sink component's turn to consume in bt_graph_run_once().

See Add a simple sink component to learn more about adding a simple component to a trace processing graph.

If you are not done consuming messages, return BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK.

If you are done consuming messages, return BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END.

If you wish to avoid a blocking operation and make bt_graph_run() or bt_graph_run_once() aware, return BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN.

Parameters

[in]

message_iterator

Simple sink component's upstream message iterator.

This user function is free to get the message iterator's next message or to make it seek.

[in] user_data User data, as passed as the user_data parameter of bt_graph_add_simple_sink_component().

Return values

BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK	Success.
BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END	End of processing.
BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN	Try again.
BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_MEMORY_ERROR	Out of memory.
BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_ERROR	Other error.

Precondition: message_iterator is not NULL.

Postcondition: The reference count of message_iterator is not changed.

See also: bt_graph_add_simple_sink_component() — Creates and adds a simple sink component to a trace processing graph.

◆ bt_graph_simple_sink_component_finalize_func

typedef void(* bt_graph_simple_sink_component_finalize_func) (void *user_data)

User finalization function for bt_graph_add_simple_sink_component().

Such a finalization function is called when the simple sink component is finalized. This occurs when the trace processing graph is destroyed (you put its last strong reference with bt_graph_put_ref()).

See Add a simple sink component to learn more about adding a simple component to a trace processing graph.

Parameters

[in] user_data User data, as passed as the user_data parameter of bt_graph_add_simple_sink_component().

Postcondition: The current thread has no error.

See also: bt_graph_add_simple_sink_component() — Creates and adds a simple sink component to a trace processing graph.

◆ bt_graph_filter_component_input_port_added_listener_func

typedef bt_graph_listener_func_status(* bt_graph_filter_component_input_port_added_listener_func) (const bt_component_filter *component, const bt_port_input *port, void *user_data)

User function for bt_graph_add_filter_component_input_port_added_listener().

Such a function is called whenever a filter component within a trace processing graph adds an input port during the graph configuration phase.

See Listeners to learn more.

Parameters

[in]	component	Filter component which added port.
[in]	port	Input port added by component.
[in]	user_data	User data, as passed as the user_data parameter of bt_graph_add_filter_component_input_port_added_listener().

Return values

BT_GRAPH_LISTENER_FUNC_STATUS_OK	Success.
BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR	Out of memory.
BT_GRAPH_LISTENER_FUNC_STATUS_ERROR	Other error.

Precondition: component is not NULL.; port is not NULL.

See also: bt_graph_add_filter_component_input_port_added_listener() — Adds a "filter component input port added" listener to a trace processing graph.

◆ bt_graph_sink_component_input_port_added_listener_func

typedef bt_graph_listener_func_status(* bt_graph_sink_component_input_port_added_listener_func) (const bt_component_sink *component, const bt_port_input *port, void *user_data)

User function for bt_graph_add_sink_component_input_port_added_listener().

Such a function is called whenever a sink component within a trace processing graph adds an input port during the graph configuration phase.

See Listeners to learn more.

Parameters

[in]	component	Filter component which added port.
[in]	port	Input port added by component.
[in]	user_data	User data, as passed as the user_data parameter of bt_graph_add_sink_component_input_port_added_listener().

Return values

BT_GRAPH_LISTENER_FUNC_STATUS_OK	Success.
BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR	Out of memory.
BT_GRAPH_LISTENER_FUNC_STATUS_ERROR	Other error.

Precondition: component is not NULL.; port is not NULL.

See also: bt_graph_add_sink_component_input_port_added_listener() — Adds a "sink component input port added" listener to a trace processing graph.

◆ bt_graph_source_component_output_port_added_listener_func

typedef bt_graph_listener_func_status(* bt_graph_source_component_output_port_added_listener_func) (const bt_component_source *component, const bt_port_output *port, void *user_data)

User function for bt_graph_add_source_component_output_port_added_listener().

Such a function is called whenever a source component within a trace processing graph adds an output port during the graph configuration phase.

See Listeners to learn more.

Parameters

[in]	component	Filter component which added port.
[in]	port	Input port added by component.
[in]	user_data	User data, as passed as the user_data parameter of bt_graph_add_source_component_output_port_added_listener().

Return values

BT_GRAPH_LISTENER_FUNC_STATUS_OK	Success.
BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR	Out of memory.
BT_GRAPH_LISTENER_FUNC_STATUS_ERROR	Other error.

Precondition: component is not NULL.; port is not NULL.

See also: bt_graph_add_source_component_output_port_added_listener() — Adds a "source component output port added" listener to a trace processing graph.

◆ bt_graph_filter_component_output_port_added_listener_func

typedef bt_graph_listener_func_status(* bt_graph_filter_component_output_port_added_listener_func) (const bt_component_filter *component, const bt_port_output *port, void *user_data)

User function for bt_graph_add_filter_component_output_port_added_listener().

Such a function is called whenever a filter component within a trace processing graph adds an output port during the graph configuration phase.

See Listeners to learn more.

Parameters

[in]	component	Filter component which added port.
[in]	port	Input port added by component.
[in]	user_data	User data, as passed as the user_data parameter of bt_graph_add_filter_component_output_port_added_listener().

Return values

BT_GRAPH_LISTENER_FUNC_STATUS_OK	Success.
BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR	Out of memory.
BT_GRAPH_LISTENER_FUNC_STATUS_ERROR	Other error.

Precondition: component is not NULL.; port is not NULL.

See also: bt_graph_add_filter_component_output_port_added_listener() — Adds a "filter component output port added" listener to a trace processing graph.

Enumeration Type Documentation

◆ bt_graph_add_component_status

enum bt_graph_add_component_status

Status codes for the bt_graph_add_*_component*() functions.

Enumerator
BT_GRAPH_ADD_COMPONENT_STATUS_OK	Success.
BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR	Out of memory.
BT_GRAPH_ADD_COMPONENT_STATUS_ERROR	Other error.

◆ bt_graph_simple_sink_component_initialize_func_status

enum bt_graph_simple_sink_component_initialize_func_status

Status codes for the bt_graph_simple_sink_component_initialize_func type.

Enumerator
BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_OK	Success.
BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_MEMORY_ERROR	Out of memory.
BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_ERROR	Other error.

◆ bt_graph_simple_sink_component_consume_func_status

enum bt_graph_simple_sink_component_consume_func_status

Status codes for the bt_graph_simple_sink_component_consume_func type.

Enumerator
BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK	Success.
BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END	End of processing.
BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN	Try again.
BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_MEMORY_ERROR	Out of memory.
BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_ERROR	Other error.

◆ bt_graph_connect_ports_status

enum bt_graph_connect_ports_status

Status codes for bt_graph_connect_ports().

Enumerator
BT_GRAPH_CONNECT_PORTS_STATUS_OK	Success.
BT_GRAPH_CONNECT_PORTS_STATUS_MEMORY_ERROR	Out of memory.
BT_GRAPH_CONNECT_PORTS_STATUS_ERROR	Other error.

◆ bt_graph_run_status

enum bt_graph_run_status

Status codes for bt_graph_run().

Enumerator
BT_GRAPH_RUN_STATUS_OK	Success.
BT_GRAPH_RUN_STATUS_AGAIN	Try again.
BT_GRAPH_RUN_STATUS_MEMORY_ERROR	Out of memory.
BT_GRAPH_RUN_STATUS_ERROR	Other error.

◆ bt_graph_run_once_status

enum bt_graph_run_once_status

Status codes for bt_graph_run().

Enumerator
BT_GRAPH_RUN_ONCE_STATUS_OK	Success.
BT_GRAPH_RUN_ONCE_STATUS_END	All sink components are finished processing.
BT_GRAPH_RUN_ONCE_STATUS_AGAIN	Try again.
BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR	Out of memory.
BT_GRAPH_RUN_ONCE_STATUS_ERROR	Other error.

◆ bt_graph_add_interrupter_status

enum bt_graph_add_interrupter_status

Status codes for bt_graph_add_interrupter().

Enumerator
BT_GRAPH_ADD_INTERRUPTER_STATUS_OK	Success.
BT_GRAPH_ADD_INTERRUPTER_STATUS_MEMORY_ERROR	Out of memory.

◆ bt_graph_add_listener_status

enum bt_graph_add_listener_status

Status codes for the bt_graph_add_*_component_*_port_added_listener() functions.

Enumerator
BT_GRAPH_ADD_LISTENER_STATUS_OK	Success.
BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR	Out of memory.

◆ bt_graph_listener_func_status

enum bt_graph_listener_func_status

Status codes for the bt_graph_*_component_*_port_added_listener_func() types.

Enumerator
BT_GRAPH_LISTENER_FUNC_STATUS_OK	Success.
BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR	Out of memory.
BT_GRAPH_LISTENER_FUNC_STATUS_ERROR	Other error.

Macro Definition Documentation

◆ BT_GRAPH_PUT_REF_AND_RESET

#define BT_GRAPH_PUT_REF_AND_RESET ( _graph )

Decrements the reference count of the trace processing graph _graph, and then sets _graph to NULL.

Parameters

_graph

Trace processing graph of which to decrement the reference count.

Can contain NULL.

Precondition: _graph is an assignable expression.

◆ BT_GRAPH_MOVE_REF

#define BT_GRAPH_MOVE_REF	(	_dst,
		_src
	)

Decrements the reference count of the trace processing graph _dst, sets _dst to _src, and then sets _src to NULL.

This macro effectively moves a trace processing graph reference from the expression _src to the expression _dst, putting the existing _dst reference.

Parameters

_dst

Destination expression.

Can contain NULL.

_src

Source expression.

Can contain NULL.

Precondition: _dst is an assignable expression.; _src is an assignable expression.

Function Documentation

◆ bt_graph_create()

bt_graph* bt_graph_create ( uint64_t mip_version )

Creates a default, empty trace processing graph honouring version mip_version of the Message Interchange Protocol.

On success, the returned graph contains no components (see Add components).

The graph is configured as operating following version mip_version of the Message Interchange Protocol, so that bt_self_component_get_graph_mip_version() returns this version when components call it.

Note: As of Babeltrace 2.0, the only available MIP version is 0.

The returned graph has a default interrupter. Any component you add with the bt_graph_add_*_component*() functions and all their message iterators also have this same default interrupter. Borrow the graph's default interrupter with bt_graph_borrow_default_interrupter().

Parameters

[in] mip_version Version of the Message Interchange Protocol to use within the graph to create.

Returns: New trace processing graph reference, or NULL on memory error.

Precondition: mip_version is 0.

◆ bt_graph_add_source_component_with_initialize_method_data()

bt_graph_add_component_status bt_graph_add_source_component_with_initialize_method_data	(	bt_graph *	graph,
		const bt_component_class_source *	component_class,
		const char *	name,
		const bt_value *	params,
		void *	initialize_method_data,
		bt_logging_level	logging_level,
		const bt_component_source **	component
	)

Creates a source component from the class component_class with the initialization parameters params, the initialization user data initialize_method_data, and the initial logging level logging_level, adds it to the trace processing graph graph with the name name, and sets *component to the resulting component.

See Add components to learn more about adding components to a trace processing graph.

This function calls the source component's initialization method after creating it.

The created source component's initialization method receives:

params as its own params parameter (or an empty map value if params is NULL).
initialize_method_data as its own initialize_method_data parameter.

The created source component can get its logging level (logging_level) with bt_component_get_logging_level().

Parameters

[in]	graph	Trace processing graph to which to add the created source component.
[in]	component_class	Class to instantiate within graph.
[in]	name	Unique name, within graph, of the component to create.
[in]	params	Initialization parameters to use when creating the source component. Can be `NULL`, in which case the created source component's initialization method receives an empty map value as its params parameter.
[in]	initialize_method_data	User data passed as is to the created source component's initialization method.
[in]	logging_level	Initial logging level of the source component to create.
[out]	component	On success, if not `NULL`, component is a borrowed* reference of the created source component.

Return values

BT_GRAPH_ADD_COMPONENT_STATUS_OK	Success.
BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR	Out of memory.
BT_GRAPH_ADD_COMPONENT_STATUS_ERROR	Other error, for example, the created source component's initialization method failed.

Precondition: graph is not NULL.; graph is not completely configured yet (you didn't call bt_graph_run() or bt_graph_run_once() with it).; graph is not faulty: no previous component adding or component port connecting functions failed with it.; component_class is not NULL.; name is not NULL.; No other component within graph has the name name.; params is a map value (bt_value_is_map() returns BT_TRUE) or is NULL.

Postcondition: On success, component_class is frozen.; On success, params is frozen.

◆ bt_graph_add_filter_component_with_initialize_method_data()

bt_graph_add_component_status bt_graph_add_filter_component_with_initialize_method_data	(	bt_graph *	graph,
		const bt_component_class_filter *	component_class,
		const char *	name,
		const bt_value *	params,
		void *	initialize_method_data,
		bt_logging_level	logging_level,
		const bt_component_filter **	component
	)

Creates a filter component from the class component_class with the initialization parameters params, the initialization user data initialize_method_data, and the initial logging level logging_level, adds it to the trace processing graph graph with the name name, and sets *component to the resulting component.

See Add components to learn more about adding components to a trace processing graph.

This function calls the filter component's initialization method after creating it.

The created filter component's initialization method receives:

params as its own params parameter (or an empty map value if params is NULL).
initialize_method_data as its own initialize_method_data parameter.

The created filter component can get its logging level (logging_level) with bt_component_get_logging_level().

Parameters

[in]	graph	Trace processing graph to which to add the created filter component.
[in]	component_class	Class to instantiate within graph.
[in]	name	Unique name, within graph, of the component to create.
[in]	params	Initialization parameters to use when creating the filter component. Can be `NULL`, in which case the created filter component's initialization method receives an empty map value as its params parameter.
[in]	initialize_method_data	User data passed as is to the created filter component's initialization method.
[in]	logging_level	Initial logging level of the filter component to create.
[out]	component	On success, if not `NULL`, component is a borrowed* reference of the created filter component.

Return values

BT_GRAPH_ADD_COMPONENT_STATUS_OK	Success.
BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR	Out of memory.
BT_GRAPH_ADD_COMPONENT_STATUS_ERROR	Other error, for example, the created filter component's initialization method failed.

Precondition: graph is not NULL.; graph is not completely configured yet (you didn't call bt_graph_run() or bt_graph_run_once() with it).; graph is not faulty: no previous component adding or component port connecting functions failed with it.; component_class is not NULL.; name is not NULL.; No other component within graph has the name name.; params is a map value (bt_value_is_map() returns BT_TRUE) or is NULL.

Postcondition: On success, component_class is frozen.; On success, params is frozen.

◆ bt_graph_add_sink_component_with_initialize_method_data()

bt_graph_add_component_status bt_graph_add_sink_component_with_initialize_method_data	(	bt_graph *	graph,
		const bt_component_class_sink *	component_class,
		const char *	name,
		const bt_value *	params,
		void *	initialize_method_data,
		bt_logging_level	logging_level,
		const bt_component_sink **	component
	)

Creates a sink component from the class component_class with the initialization parameters params, the initialization user data initialize_method_data, and the initial logging level logging_level, adds it to the trace processing graph graph with the name name, and sets *component to the resulting component.

See Add components to learn more about adding components to a trace processing graph.

This function calls the sink component's initialization method after creating it.

The created sink component's initialization method receives:

params as its own params parameter (or an empty map value if params is NULL).
initialize_method_data as its own initialize_method_data parameter.

The created sink component can get its logging level (logging_level) with bt_component_get_logging_level().

Parameters

[in]	graph	Trace processing graph to which to add the created sink component.
[in]	component_class	Class to instantiate within graph.
[in]	name	Unique name, within graph, of the component to create.
[in]	params	Initialization parameters to use when creating the sink component. Can be `NULL`, in which case the created sink component's initialization method receives an empty map value as its params parameter.
[in]	initialize_method_data	User data passed as is to the created sink component's initialization method.
[in]	logging_level	Initial logging level of the sink component to create.
[out]	component	On success, if not `NULL`, component is a borrowed* reference of the created sink component.

Return values

BT_GRAPH_ADD_COMPONENT_STATUS_OK	Success.
BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR	Out of memory.
BT_GRAPH_ADD_COMPONENT_STATUS_ERROR	Other error, for example, the created sink component's initialization method failed.

Precondition: graph is not NULL.; graph is not completely configured yet (you didn't call bt_graph_run() or bt_graph_run_once() with it).; graph is not faulty: no previous component adding or component port connecting functions failed with it.; component_class is not NULL.; name is not NULL.; No other component within graph has the name name.; params is a map value (bt_value_is_map() returns BT_TRUE) or is NULL.

Postcondition: On success, component_class is frozen.; On success, params is frozen.

◆ bt_graph_add_simple_sink_component()

bt_graph_add_component_status bt_graph_add_simple_sink_component	(	bt_graph *	graph,
		const char *	name,
		bt_graph_simple_sink_component_initialize_func	initialize_func,
		bt_graph_simple_sink_component_consume_func	consume_func,
		bt_graph_simple_sink_component_finalize_func	finalize_func,
		void *	user_data,
		const bt_component_sink **	component
	)

Creates a simple sink component, adds it to the trace processing graph graph with the name name, and sets *component to the resulting component.

See Add a simple sink component to learn more about adding a simple component to a trace processing graph.

initialize_func (if not NULL), consume_func, and finalize_func (if not NULL) receive user_data as their own user_data parameter.

Parameters

[in]	graph	Trace processing graph to which to add the created simple sink component.
[in]	name	Unique name, within graph, of the component to create.
[in]	initialize_func	User initialization function. Can be `NULL`.
[in]	consume_func	User consuming function.
[in]	finalize_func	User finalization function. Can be `NULL`.
[in]	user_data	User data to pass as the user_data parameter of initialize_func, consume_func, and finalize_func.
[out]	component	On success, if not `NULL`, component is a borrowed* reference of the created simple sink component.

Return values

BT_GRAPH_ADD_COMPONENT_STATUS_OK	Success.
BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR	Out of memory.
BT_GRAPH_ADD_COMPONENT_STATUS_ERROR	Other error, for example, the created sink component's initialization method failed.

Precondition: graph is not NULL.; graph is not completely configured yet (you didn't call bt_graph_run() or bt_graph_run_once() with it).; graph is not faulty: no previous component adding or component port connecting functions failed with it.; name is not NULL.; No other component within graph has the name name.; consume_func is not NULL.

◆ bt_graph_connect_ports()

bt_graph_connect_ports_status bt_graph_connect_ports	(	bt_graph *	graph,
		const bt_port_output *	upstream_port,
		const bt_port_input *	downstream_port,
		const bt_connection **	connection
	)

Connects the output port upstream_port to the input port downstream_port within the trace processing graph graph, and sets *connection to the resulting connection.

See Connect component ports to learn more about connecting ports within a trace processing graph.

Both upstream_port and downstream_port must be unconnected (bt_port_is_connected() returns BT_FALSE) when you call this function.

Parameters

[in]	graph	Trace processing graph containing the components to which belong upstream_port and downstream_port.
[in]	upstream_port	Output port to connect to downstream_port.
[in]	downstream_port	Input port to connect to upstream_port.
[in]	connection	On success, if not `NULL`, connection is a borrowed* reference of the resulting connection.

Return values

BT_GRAPH_CONNECT_PORTS_STATUS_OK	Success.
BT_GRAPH_CONNECT_PORTS_STATUS_MEMORY_ERROR	Out of memory.
BT_GRAPH_CONNECT_PORTS_STATUS_ERROR	Other error.

Precondition: graph is not NULL.; graph is not completely configured yet (you didn't call bt_graph_run() or bt_graph_run_once() with it).; graph is not faulty: no previous component adding or component port connecting functions failed with it.; upstream_port is not NULL.; graph contains the component of upstream_port, as returned by bt_port_borrow_component_const().; upstream_port is unconnected (bt_port_is_connected() returns BT_FALSE).; downstream_port is not NULL.; graph contains the component of downstream_port, as returned by bt_port_borrow_component_const().; downstream_port is unconnected (bt_port_is_connected() returns BT_FALSE).; Connecting upstream_port to downstream_port does not form a connection cycle within graph.

◆ bt_graph_run()

bt_graph_run_status bt_graph_run ( bt_graph * graph )

Runs the trace processing graph graph, calling each sink component's consuming method in a round robin fashion until they are all done consuming or an exception occurs.

See Run to learn more about running a trace processing graph.

This function does not return until one of:

All the sink components are ended, in which case this function returns BT_GRAPH_RUN_STATUS_OK.
One of the sink component returns an error, in which case this function returns BT_GRAPH_RUN_STATUS_ERROR or BT_GRAPH_RUN_STATUS_MEMORY_ERROR.
One of the sink component returns "try again", in which case this function returns BT_GRAPH_RUN_STATUS_AGAIN.

In that case, you can call this function again later, usually after waiting for some time.

This feature exists to allow blocking operations within components to be postponed until they don't block. The graph user can perform other tasks instead of the graph's thread blocking.
graph is interrupted (see bt_graph_borrow_default_interrupter() and bt_graph_add_interrupter()), in which case this function returns BT_GRAPH_RUN_STATUS_AGAIN.

Check the interrupter's state with bt_interrupter_is_set() to distinguish between a sink component returning "try again" and graph getting interrupted.

To make a single sink component consume, then get the thread's control back, use bt_graph_run_once().

When you call this function or bt_graph_run_once() for the first time, graph becomes configured. See Trace processing graph life cycle to learn what happens when a trace processing graph becomes configured, and what you can and cannot do with a configured graph.

Parameters

[in] graph Trace processing graph to run.

Return values

BT_GRAPH_RUN_STATUS_OK	Success.
BT_GRAPH_RUN_STATUS_AGAIN	Try again.
BT_GRAPH_RUN_STATUS_MEMORY_ERROR	Out of memory.
BT_GRAPH_RUN_STATUS_ERROR	Other error.

Precondition: graph is not NULL.; graph is not faulty: no previous component adding or component port connecting functions failed with it.; For each source component within graph, at least one output port is connected.; For each filter component within graph, at least one input port and one input port are connected.; For each sink component within graph, at least one input port is connected.; graph contains at least one sink component.

See also: bt_graph_run_once() — Calls a single trace processing graph's sink component's consuming method once.

◆ bt_graph_run_once()

bt_graph_run_once_status bt_graph_run_once ( bt_graph * graph )

Calls the consuming method of the next non-ended sink component to make consume within the trace processing graph graph.

See Run to learn more about running a trace processing graph.

This function makes the next non-ended sink component consume. For example, if graph has two non-ended sink components A and B:

Calling bt_graph_run_once() makes sink component A consume.
Calling bt_graph_run_once() again makes sink component B consume.
Calling bt_graph_run_once() again makes sink component A consume.
...

Considering this, if graph contains a single non-ended sink component, this function always makes this sink component consume.

If the sink component's consuming method:

Succeeds

This function returns BT_GRAPH_RUN_ONCE_STATUS_OK.

Returns "try again"

This function returns BT_GRAPH_RUN_ONCE_STATUS_AGAIN.

Fails

This function returns BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR or BT_GRAPH_RUN_ONCE_STATUS_ERROR.

When all the sink components of graph are finished processing (ended), this function returns BT_GRAPH_RUN_ONCE_STATUS_END.

bt_graph_run() calls this function in a loop until are the sink components are ended or an exception occurs.

When you call this function or bt_graph_run() for the first time, graph becomes configured. See Trace processing graph life cycle to learn what happens when a trace processing graph becomes configured, and what you can and cannot do with a configured graph.

Parameters

[in] graph Trace processing graph of which to make the next sink component consume.

Return values

BT_GRAPH_RUN_ONCE_STATUS_OK	Success.
BT_GRAPH_RUN_ONCE_STATUS_END	All sink components are finished processing.
BT_GRAPH_RUN_ONCE_STATUS_AGAIN	Try again.
BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR	Out of memory.
BT_GRAPH_RUN_ONCE_STATUS_ERROR	Other error.

Precondition: graph is not NULL.; graph is not faulty: no previous component adding or component port connecting functions failed with it.

See also: bt_graph_run() — Runs a trace processing graph, making all its sink components consume in a round robin fashion.

◆ bt_graph_add_interrupter()

bt_graph_add_interrupter_status bt_graph_add_interrupter	(	bt_graph *	graph,
		const bt_interrupter *	interrupter
	)

Adds the interrupter interrupter to all the current and future sink components and message iterators of the trace processing graph graph, as well as to the graph itself.

Sink components can check whether or not they are interrupted with bt_self_component_sink_is_interrupted().

Message iterators can check whether or not they are interrupted with bt_self_message_iterator_is_interrupted().

The bt_graph_run() loop intermittently checks whether or not any of the graph's interrupters is set. If so, bt_graph_run() returns BT_GRAPH_RUN_STATUS_AGAIN.

Note

bt_graph_create() returns a trace processing graph which comes with its own default interrupter.

Instead of adding your own interrupter to graph, you can set its default interrupter with

bt_interrupter_set(bt_graph_borrow_default_interrupter());

Parameters

[in]	graph	Trace processing graph to which to add interrupter.
[in]	interrupter	Interrupter to add to graph.

Return values

BT_GRAPH_ADD_INTERRUPTER_STATUS_OK	Success.
BT_GRAPH_ADD_INTERRUPTER_STATUS_MEMORY_ERROR	Out of memory.

Precondition: graph is not NULL.; graph is not faulty: no previous component adding or component port connecting functions failed with it.; interrupter is not NULL.

See also: bt_graph_borrow_default_interrupter() — Borrows the default interrupter from a trace processing graph.

◆ bt_graph_borrow_default_interrupter()

bt_interrupter* bt_graph_borrow_default_interrupter ( bt_graph * graph )

Borrows the default interrupter from the trace processing graph graph.

Parameters

[in] graph Trace processing graph from which to borrow the default interrupter.

Returns

Borrowed reference of the default interrupter of graph.

The returned pointer remains valid as long as graph exists.

Precondition: graph is not NULL.

See also: bt_graph_add_interrupter() — Adds an interrupter to a trace processing graph.

◆ bt_graph_add_filter_component_input_port_added_listener()

bt_graph_add_listener_status bt_graph_add_filter_component_input_port_added_listener	(	bt_graph *	graph,
		bt_graph_filter_component_input_port_added_listener_func	user_func,
		void *	user_data,
		bt_listener_id *	listener_id
	)

Adds a "filter component input port added" listener to the trace processing graph graph.

Once this function returns, user_func is called whenever a filter component adds an input port within graph.

See Listeners to learn more.

Parameters

[in]	graph	Trace processing graph to add the "filter component input port added" listener to.
[in]	user_func	User function of the "filter component input port added" listener to add to graph.
[in]	user_data	User data to pass as the user_data parameter of user_func.
[out]	listener_id	On success and if not `NULL`, *listener_id is the ID of the added listener within graph.

Return values

BT_GRAPH_ADD_LISTENER_STATUS_OK	Success.
BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR	Out of memory.

Precondition: graph is not NULL.; graph is not faulty: no previous component adding or component port connecting functions failed with it.; user_func is not NULL.

◆ bt_graph_add_sink_component_input_port_added_listener()

bt_graph_add_listener_status bt_graph_add_sink_component_input_port_added_listener	(	bt_graph *	graph,
		bt_graph_sink_component_input_port_added_listener_func	user_func,
		void *	user_data,
		bt_listener_id *	listener_id
	)

Adds a "sink component input port added" listener to the trace processing graph graph.

Once this function returns, user_func is called whenever a sink component adds an input port within graph.

See Listeners to learn more.

Parameters

[in]	graph	Trace processing graph to add the "sink component input port added" listener to.
[in]	user_func	User function of the "sink component input port added" listener to add to graph.
[in]	user_data	User data to pass as the user_data parameter of user_func.
[out]	listener_id	On success and if not `NULL`, *listener_id is the ID of the added listener within graph.

Return values

BT_GRAPH_ADD_LISTENER_STATUS_OK	Success.
BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR	Out of memory.

Precondition: graph is not NULL.; graph is not faulty: no previous component adding or component port connecting functions failed with it.; user_func is not NULL.

◆ bt_graph_add_source_component_output_port_added_listener()

bt_graph_add_listener_status bt_graph_add_source_component_output_port_added_listener	(	bt_graph *	graph,
		bt_graph_source_component_output_port_added_listener_func	user_func,
		void *	user_data,
		bt_listener_id *	listener_id
	)

Adds a "source component output port added" listener to the trace processing graph graph.

Once this function returns, user_func is called whenever a source component adds an output port within graph.

See Listeners to learn more.

Parameters

[in]	graph	Trace processing graph to add the "source component output port added" listener to.
[in]	user_func	User function of the "source component output port added" listener to add to graph.
[in]	user_data	User data to pass as the user_data parameter of user_func.
[out]	listener_id	On success and if not `NULL`, *listener_id is the ID of the added listener within graph.

Return values

BT_GRAPH_ADD_LISTENER_STATUS_OK	Success.
BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR	Out of memory.

Precondition: graph is not NULL.; graph is not faulty: no previous component adding or component port connecting functions failed with it.; user_func is not NULL.

◆ bt_graph_add_filter_component_output_port_added_listener()

bt_graph_add_listener_status bt_graph_add_filter_component_output_port_added_listener	(	bt_graph *	graph,
		bt_graph_filter_component_output_port_added_listener_func	user_func,
		void *	user_data,
		bt_listener_id *	listener_id
	)

Adds a "filter component output port added" listener to the trace processing graph graph.

Once this function returns, user_func is called whenever a filter component adds an output port within graph.

See Listeners to learn more.

Parameters

[in]	graph	Trace processing graph to add the "filter component output port added" listener to.
[in]	user_func	User function of the "filter component output port added" listener to add to graph.
[in]	user_data	User data to pass as the user_data parameter of user_func.
[out]	listener_id	On success and if not `NULL`, *listener_id is the ID of the added listener within graph.

Return values

BT_GRAPH_ADD_LISTENER_STATUS_OK	Success.
BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR	Out of memory.

Precondition: graph is not NULL.; graph is not faulty: no previous component adding or component port connecting functions failed with it.; user_func is not NULL.

◆ bt_graph_get_ref()

void bt_graph_get_ref ( const bt_graph * graph )

Increments the reference count of the trace processing graph graph.

Parameters

[in]

graph

Trace processing graph of which to increment the reference count.

Can be NULL.

See also: bt_graph_put_ref() — Decrements the reference count of a trace processing graph.

◆ bt_graph_put_ref()

void bt_graph_put_ref ( const bt_graph * graph )

Decrements the reference count of the trace processing graph graph.

Parameters

[in]

graph

Trace processing graph of which to decrement the reference count.

Can be NULL.

See also: bt_graph_get_ref() — Increments the reference count of a trace processing graph.

Detailed Description

Trace processing graph life cycle

Add components

Add a simple sink component

Connect component ports

Run

Standard Babeltrace 2 component classes

Listeners

Modules

Type

Creation

Component adding

Simple sink component adding

Component port connection

Running

Interruption

Listeners

Reference count

Typedef Documentation

◆ bt_graph_simple_sink_component_initialize_func

◆ bt_graph_simple_sink_component_consume_func

◆ bt_graph_simple_sink_component_finalize_func

◆ bt_graph_filter_component_input_port_added_listener_func

◆ bt_graph_sink_component_input_port_added_listener_func

◆ bt_graph_source_component_output_port_added_listener_func

◆ bt_graph_filter_component_output_port_added_listener_func

Enumeration Type Documentation

◆ bt_graph_add_component_status

◆ bt_graph_simple_sink_component_initialize_func_status

◆ bt_graph_simple_sink_component_consume_func_status

◆ bt_graph_connect_ports_status

◆ bt_graph_run_status

◆ bt_graph_run_once_status

◆ bt_graph_add_interrupter_status

◆ bt_graph_add_listener_status

◆ bt_graph_listener_func_status

Macro Definition Documentation

◆ BT_GRAPH_PUT_REF_AND_RESET

◆ BT_GRAPH_MOVE_REF

Function Documentation

◆ bt_graph_create()

◆ bt_graph_add_source_component_with_initialize_method_data()

◆ bt_graph_add_filter_component_with_initialize_method_data()

◆ bt_graph_add_sink_component_with_initialize_method_data()

◆ bt_graph_add_simple_sink_component()

◆ bt_graph_connect_ports()

◆ bt_graph_run()

◆ bt_graph_run_once()

◆ bt_graph_add_interrupter()

◆ bt_graph_borrow_default_interrupter()

◆ bt_graph_add_filter_component_input_port_added_listener()

◆ bt_graph_add_sink_component_input_port_added_listener()

◆ bt_graph_add_source_component_output_port_added_listener()

◆ bt_graph_add_filter_component_output_port_added_listener()

◆ bt_graph_get_ref()

◆ bt_graph_put_ref()