extern "C" {
#endif
-typedef enum bt_graph_listener_func_status {
- BT_GRAPH_LISTENER_FUNC_STATUS_OK = __BT_FUNC_STATUS_OK,
- BT_GRAPH_LISTENER_FUNC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
- BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_graph_listener_func_status;
+/*!
+@defgroup api-graph Graph
-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 *data);
+@brief
+ Trace processing graph.
-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 *data);
+A <strong><em>trace processing graph</em></strong> is a specialized
+<a href="https://en.wikipedia.org/wiki/Filter_graph">filter graph</a>
+to manipulate one or more traces.
-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 *data);
+Whereas the nodes of a multimedia filter graph typically exchange
+video frames and audio samples, the nodes, or \bt_p_comp, of a trace
+processing graph exchange immutable \bt_p_msg containing trace data.
-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 *data);
+The following illustration shows a basic trace processing graph which
+converts many traces to a single log of pretty-printed lines:
-typedef bt_graph_listener_func_status
-(*bt_graph_source_filter_component_ports_connected_listener_func)(
- const bt_component_source *source_component,
- const bt_component_filter *filter_component,
- const bt_port_output *upstream_port,
- const bt_port_input *downstream_port, void *data);
+@image html basic-convert-graph.png "Basic trace processing graph (conversion graph)."
-typedef bt_graph_listener_func_status
-(*bt_graph_source_sink_component_ports_connected_listener_func)(
- const bt_component_source *source_component,
- const bt_component_sink *sink_component,
- const bt_port_output *upstream_port,
- const bt_port_input *downstream_port, void *data);
+In the illustrations above, notice that:
-typedef bt_graph_listener_func_status
-(*bt_graph_filter_filter_component_ports_connected_listener_func)(
- const bt_component_filter *filter_component_upstream,
- const bt_component_filter *filter_component_downstream,
- const bt_port_output *upstream_port,
- const bt_port_input *downstream_port,
- void *data);
+- The graph (blue) contains five components.
-typedef bt_graph_listener_func_status
-(*bt_graph_filter_sink_component_ports_connected_listener_func)(
- const bt_component_filter *filter_component,
- const bt_component_sink *sink_component,
- const bt_port_output *upstream_port,
- const bt_port_input *downstream_port, void *data);
+- Three source components (green) are connected to a single filter
+ component (yellow).
-typedef enum bt_graph_simple_sink_component_initialize_func_status {
- BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_OK = __BT_FUNC_STATUS_OK,
- BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
- BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_graph_simple_sink_component_initialize_func_status;
+ There are five \bt_p_conn, from five \bt_p_oport
+ to five \bt_p_iport.
-typedef bt_graph_simple_sink_component_initialize_func_status
-(*bt_graph_simple_sink_component_initialize_func)(
- bt_message_iterator *iterator,
- void *data);
+- The filter component is connected to a single sink component (red).
-typedef enum bt_graph_simple_sink_component_consume_func_status {
- BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK = __BT_FUNC_STATUS_OK,
- BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
- BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
- BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
- BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END = __BT_FUNC_STATUS_END,
-} bt_graph_simple_sink_component_consume_func_status;
+ There's a single connection.
-typedef bt_graph_simple_sink_component_consume_func_status
-(*bt_graph_simple_sink_component_consume_func)(
- bt_message_iterator *iterator,
- void *data);
+- 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
+ \ref api-tir-comp-cls "class": <code>source.ctf.fs</code>.
+
+- All components are instances of \bt_plugin-provided classes:
+ <code>babeltrace2-plugin-ctf.so</code>,
+ <code>user-plugin.so</code>,
+ <code>babeltrace2-plugin-utils.so</code>, and
+ <code>babeltrace2-plugin-text.so</code>.
+
+Of course the topology can be much more complex if needed:
+
+@image html complex-graph.png "Complex trace processing graph."
+
+In a trace processing graph, \bt_p_comp are instances of \bt_p_comp_cls.
+
+A \bt_plugin can provide a component class, but you can also create one
+dynamically (see \ref api-comp-cls-dev).
+
+The connections between component ports in a trace processing graph
+indicate the needed topology to achieve a trace processing task. That
+being said,
+\bt_p_msg 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 \bt_msg_iter on its end of
+the connection (an \bt_iport). 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
+\ref api-fund-shared-object "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 \bt_mip (MIP) version number when you call this function.
+Then, see
+\ref api-graph-lc "Trace processing graph life cycle"
+to learn how to add components to the graph, connect their ports, and
+run it.
+
+To interrupt a \ref api-graph-lc-run "running" trace processing graph,
+either:
+
+- Borrow the graph's default \bt_intr 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() \em before
+ you run the graph with bt_graph_run() or bt_graph_run_once().
+
+ Then, set the interrupter with bt_interrupter_set().
+
+<h1>\anchor api-graph-lc Trace processing graph life cycle</h1>
+
+The following diagram shows the life cycle of a trace processing
+graph:
+
+@image html graph-lifetime.png "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:
+
+-# \ref api-graph-lc-add "Add components" to the graph.
+-# \ref api-graph-lc-connect "Connect component ports".
+-# \ref api-graph-lc-run "Run the graph".
+
+You can repeat steps 1 and 2 before step 3, as connecting a
+component \bt_port can make this \bt_comp create a new port:
+you might want to add a component in reaction to this event
+(see \ref api-graph-listeners "Listeners").
+
+Steps 1 and 2 constitute the \em 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
+<em>configured</em>, and it notifies the sink components as such so that
+they can create their \bt_p_msg_iter.
+
+Once a trace processing graph becomes configured:
+
+- You cannot \ref api-graph-lc-add "add a component" to it.
+
+- You cannot \ref api-graph-lc-connect "connect component ports".
+
+- Components cannot add ports.
+
+In general, as of \bt_name_version_min_maj:
+
+- You cannot remove a component from a trace processing graph.
+
+- You cannot end (remove) a port \bt_conn.
+
+- Components cannot remove ports.
+
+If \em any error occurs (a function returns a status code which ends
+with <code>ERROR</code>) during step 1 or 2, the trace processing
+graph is considered <strong>faulty</strong>: 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().
+
+<h2>\anchor api-graph-lc-add Add components</h2>
+
+Adding a \bt_comp to a trace processing graph is also known as
+<em>instantiating a \bt_comp_cls</em> because the graph must first
+create the component from its class before adding it.
+
+Because component and component class C types are
+\ref api-fund-c-typing "highly specific", there are six functions
+to add a component to a trace processing graph:
+
+<dl>
+ <dt>Source component</dt>
+ <dd>
+ <dl>
+ <dt>Without initialization method data</dt>
+ <dd>bt_graph_add_source_component()</dd>
+
+ <dt>With initialization method data</dt>
+ <dd>bt_graph_add_source_component_with_initialize_method_data()</dd>
+ </dl>
+ </dd>
+
+ <dt>Filter component</dt>
+ <dd>
+ <dl>
+ <dt>Without initialization method data</dt>
+ <dd>bt_graph_add_filter_component()</dd>
+
+ <dt>With initialization method data</dt>
+ <dd>bt_graph_add_filter_component_with_initialize_method_data()</dd>
+ </dl>
+ </dd>
+
+ <dt>Sink component</dt>
+ <dd>
+ <dl>
+ <dt>Without initialization method data</dt>
+ <dd>bt_graph_add_sink_component()</dd>
+
+ <dt>With initialization method data</dt>
+ <dd>bt_graph_add_sink_component_with_initialize_method_data()</dd>
+ </dl>
+ </dd>
+</dl>
+
+The <code>*_with_initialize_method_data()</code> versions can pass a
+custom, \bt_voidp pointer to the component's
+\ref api-comp-cls-dev-meth-init "initialization method".
+The other versions pass \c NULL as this parameter.
+
+All the functions above accept the same parameters:
+
+@param[in] graph
+ Trace processing graph to which to add the created component.
+@param[in] component_class
+ Class to instantiate within \bt_p{graph}.
+@param[in] name
+ Unique name of the component to add within \bt_p{graph}.
+@param[in] params
+ Initialization parameters to use when creating the component.
+@param[in] logging_level
+ Initial logging level of the component to create.
+@param[out] component
+ <strong>On success</strong>, \bt_p{*component} is the created
+ component.
+
+Once you have the created and added component (\bt_p{*component}),
+you can borrow its \bt_p_port to
+\ref api-graph-lc-connect "connect them".
+
+You can add as many components as needed to a trace processing graph,
+but they must all have a unique name.
+
+<h3>\anchor api-graph-lc-add-ss Add a simple sink component</h3>
+
+To add a very basic \bt_sink_comp which has a single \bt_iport and
+creates a single \bt_msg_iter when the trace processing graph becomes
+configured, use bt_graph_add_simple_sink_component(). When you call
+this function, you pass three user functions:
+
+<dl>
+ <dt>\bt_dt_opt Initialization</dt>
+ <dd>
+ 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.
+ </dd>
+
+ <dt>Consume</dt>
+ <dd>
+ Called every time the sink component's
+ \ref api-comp-cls-dev-meth-consume "consuming method" is called.
+
+ You can get the next messages from the component's message
+ iterator and process them.
+ </dd>
+
+ <dt>\bt_dt_opt Finalization</dt>
+ <dd>
+ Called when the sink component is finalized.
+ </dd>
+</dl>
+
+The three functions above receive, as their last parameter, the user
+data you passed to bt_graph_add_simple_sink_component() .
+
+<h2>\anchor api-graph-lc-connect Connect component ports</h2>
+
+When you \ref api-graph-lc-add "add a component" to a trace processing
+graph with one of the <code>bt_graph_add_*_component*()</code>
+functions, the function sets \bt_p{*component} to the
+created and added component.
+
+With such a \bt_comp, you can borrow one of its \bt_p_port 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
+\ref api-graph-lc-add "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 \ref api-graph-lc-run "run" the trace processing graph:
+
+- At least one \bt_oport of any \bt_src_comp must be connected.
+- At least one \bt_iport and one output port of any \bt_flt_comp must
+ be connected.
+- At least one input port of any \bt_sink_comp must be connected.
+
+<h2>\anchor api-graph-lc-run Run</h2>
+
+When you are done configuring a trace processing graph, you can run it
+with bt_graph_run().
+
+bt_graph_run() does \em 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 \bt_intr'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
+\bt_p_msg before controlling the thread again, use bt_graph_run_once()
+instead of bt_graph_run().
+
+<h1>Standard \bt_name component classes</h1>
-typedef void (*bt_graph_simple_sink_component_finalize_func)(void *data);
+The \bt_name project ships with project \bt_p_plugin which provide
+"standard" \bt_p_comp_cls.
+Those standard component classes can be useful in many trace processing
+graph topologies. They are:
+
+<dl>
+ <dt>\c ctf plugin</dt>
+ <dd>
+ <dl>
+ <dt>\c fs source component class</dt>
+ <dd>
+ Opens a
+ <a href="https://diamon.org/ctf/">CTF</a> trace on the file
+ system and emits the \bt_p_msg of their data stream files.
+
+ See \bt_man{babeltrace2-source.ctf.fs,7}.
+ </dd>
+
+ <dt>\c lttng-live source component class</dt>
+ <dd>
+ Connects to an <a href="https://lttng.org/">LTTng</a> relay
+ daemon and emits the messages of the received CTF data streams.
+
+ See \bt_man{babeltrace2-source.ctf.lttng-live,7}.
+ </dd>
+
+ <dt>\c fs sink component class</dt>
+ <dd>
+ Writes the consumed messages as one or more CTF traces on the
+ file system.
+
+ See \bt_man{babeltrace2-sink.ctf.fs,7}.
+ </dd>
+ </dl>
+ </dd>
+
+ <dt>\c lttng-utils plugin</dt>
+ <dd>
+ <dl>
+ <dt>\c debug-info filter component class</dt>
+ <dd>
+ Adds debugging information to compatible LTTng event messages.
+
+ This component class is only available if the project was
+ built with the <code>\-\-enable-debug-info</code>
+ configuration option.
+
+ See \bt_man{babeltrace2-filter.lttng-utils.debug-info,7}.
+ </dd>
+ </dl>
+ </dd>
+
+ <dt>\c text plugin</dt>
+ <dd>
+ <dl>
+ <dt>\c dmesg source component class</dt>
+ <dd>
+ Reads the lines of a Linux kernel ring buffer, that is, the
+ output of the
+ <a href="http://man7.org/linux/man-pages/man1/dmesg.1.html"><code>dmesg</code></a>
+ tool, and emits each line as an \bt_ev_msg.
+
+ See \bt_man{babeltrace2-source.text.dmesg,7}.
+ </dd>
+
+ <dt>\c details sink component class</dt>
+ <dd>
+ Deterministically prints the messages it consumes with details
+ to the standard output.
+
+ See \bt_man{babeltrace2-sink.text.details,7}.
+ </dd>
+
+ <dt>\c pretty sink component class</dt>
+ <dd>
+ Pretty-prints the messages it consumes to the standard output or
+ to a file.
+
+ This is equivalent to the \c text output format of the
+ <a href="http://man7.org/linux/man-pages/man1/babeltrace.1.html">Babeltrace 1
+ command-line tool</a>.
+
+ See \bt_man{babeltrace2-sink.text.pretty,7}.
+ </dd>
+ </dl>
+ </dd>
+
+ <dt>\c utils plugin</dt>
+ <dd>
+ <dl>
+ <dt>\c muxer filter component class</dt>
+ <dd>
+ Muxes messages by time.
+
+ See \bt_man{babeltrace2-filter.utils.muxer,7}.
+ </dd>
+
+ <dt>\c trimmer filter component class</dt>
+ <dd>
+ Discards all the consumed messages with a time outside a given
+ time range, effectively "cutting" \bt_p_stream.
+
+ See \bt_man{babeltrace2-filter.utils.trimmer,7}.
+ </dd>
+
+ <dt>\c counter sink component class</dt>
+ <dd>
+ Prints the number of consumed messages, either once at the end
+ or periodically, to the standard output.
+
+ See \bt_man{babeltrace2-sink.utils.counter,7}.
+ </dd>
+
+ <dt>\c dummy sink component class</dt>
+ <dd>
+ Consumes messages and discards them (does nothing with them).
+
+ This is useful for testing and benchmarking a trace processing
+ graph application, for example.
+
+ See \bt_man{babeltrace2-sink.utils.dummy,7}.
+ </dd>
+ </dl>
+ </dd>
+</dl>
+
+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:
+
+@code
+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
+}
+@endcode
+
+<h1>\anchor api-graph-listeners Listeners</h1>
+
+A \bt_comp can add a \bt_port:
+
+- At initialization time, that is, when you call one of the
+ <code>bt_graph_add_*_component*()</code> 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:
+
+- bt_graph_add_source_component_output_port_added_listener()
+- bt_graph_add_filter_component_input_port_added_listener()
+- bt_graph_add_filter_component_output_port_added_listener()
+- bt_graph_add_sink_component_input_port_added_listener()
+
+Within a "port added" listener function, you can
+\ref api-graph-lc-add "add more components"
+and \ref api-graph-lc-connect "connect more component ports".
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_graph bt_graph;
+
+@brief
+ Trace processing graph.
+
+@}
+*/
+
+/*!
+@name Creation
+@{
+*/
+
+/*!
+@brief
+ Creates a default, empty trace processing graph honouring version
+ \bt_p{mip_version} of the \bt_mip.
+
+On success, the returned graph contains no components (see
+\ref api-graph-lc-add "Add components").
+
+The graph is configured as operating following version
+\bt_p{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 \bt_name_version_min_maj, the only available MIP version is 0.
+
+The returned graph has a default \bt_intr. Any \bt_comp you add with the
+<code>bt_graph_add_*_component*()</code> functions and all their
+\bt_p_msg_iter also have this same default interrupter. Borrow the graph's
+default interrupter with bt_graph_borrow_default_interrupter().
+
+@param[in] mip_version
+ Version of the Message Interchange Protocol to use within the
+ graph to create.
+
+@returns
+ New trace processing graph reference, or \c NULL on memory error.
+
+@pre
+ \bt_p{mip_version} is 0.
+*/
extern bt_graph *bt_graph_create(uint64_t mip_version);
+/*! @} */
+
+/*!
+@name Component adding
+@{
+*/
+
+/*!
+@brief
+ Status codes for the
+ <code>bt_graph_add_*_component*()</code> functions.
+*/
typedef enum bt_graph_add_component_status {
+ /*!
+ @brief
+ Success.
+ */
BT_GRAPH_ADD_COMPONENT_STATUS_OK = __BT_FUNC_STATUS_OK,
- BT_GRAPH_ADD_COMPONENT_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
+
+ /*!
+ @brief
+ Out of memory.
+ */
BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+ /*!
+ @brief
+ Other error.
+ */
+ BT_GRAPH_ADD_COMPONENT_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
} bt_graph_add_component_status;
+/*!
+@brief
+ Alias of bt_graph_add_source_component_with_initialize_method_data()
+ with the \bt_p{initialize_method_data} parameter set to \c NULL.
+*/
extern 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 log_level, const bt_component_source **component);
+ bt_logging_level logging_level,
+ const bt_component_source **component);
+
+/*!
+@brief
+ Creates a \bt_src_comp from the
+ \ref api-tir-comp-cls "class" \bt_p{component_class}
+ with the initialization parameters \bt_p{params}, the initialization
+ user data \bt_p{initialize_method_data}, and the initial
+ logging level \bt_p{logging_level}, adds it to the trace processing
+ graph \bt_p{graph} with the name \bt_p{name}, and sets
+ \bt_p{*component} to the resulting component.
+
+See \ref api-graph-lc-add "Add components" to learn more about adding
+components to a trace processing graph.
+
+This function calls the source component's
+\ref api-comp-cls-dev-meth-init "initialization method" after
+creating it.
+
+The created source component's initialization method receives:
+
+- \bt_p{params} as its own \bt_p{params} parameter (or an empty
+ \bt_map_val if \bt_p{params} is \c NULL).
+
+- \bt_p{initialize_method_data} as its own \bt_p{initialize_method_data}
+ parameter.
+
+The created source component can get its logging level
+(\bt_p{logging_level}) with bt_component_get_logging_level().
+
+@param[in] graph
+ Trace processing graph to which to add the created source component.
+@param[in] component_class
+ Class to instantiate within \bt_p{graph}.
+@param[in] name
+ Unique name, within \bt_p{graph}, of the component to create.
+@param[in] params
+ @parblock
+ Initialization parameters to use when creating the source component.
+
+ Can be \c NULL, in which case the created source component's
+ initialization method receives an empty \bt_map_val as its
+ \bt_p{params} parameter.
+ @endparblock
+@param[in] initialize_method_data
+ User data passed as is to the created source component's
+ initialization method.
+@param[in] logging_level
+ Initial logging level of the source component to create.
+@param[out] component
+ <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
+ a \em borrowed reference of the created source component.
+
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
+ Success.
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
+ Other error, for example, the created source component's
+ initialization method failed.
+
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_configured{graph}
+@bt_pre_graph_not_faulty{graph}
+@bt_pre_not_null{component_class}
+@bt_pre_not_null{name}
+@pre
+ No other component within \bt_p{graph} has the name \bt_p{name}.
+@pre
+ \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
+ or is \c NULL.
+@bt_post_success_frozen{component_class}
+@bt_post_success_frozen{params}
+*/
extern 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 *init_method_data, bt_logging_level log_level,
+ void *initialize_method_data, bt_logging_level logging_level,
const bt_component_source **component);
+/*!
+@brief
+ Alias of bt_graph_add_filter_component_with_initialize_method_data()
+ with the \bt_p{initialize_method_data} parameter set to \c NULL.
+*/
extern 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 log_level,
+ bt_logging_level logging_level,
const bt_component_filter **component);
+/*!
+@brief
+ Creates a \bt_flt_comp from the
+ \ref api-tir-comp-cls "class" \bt_p{component_class}
+ with the initialization parameters \bt_p{params}, the initialization
+ user data \bt_p{initialize_method_data}, and the initial
+ logging level \bt_p{logging_level}, adds it to the trace processing
+ graph \bt_p{graph} with the name \bt_p{name}, and sets
+ \bt_p{*component} to the resulting component.
+
+See \ref api-graph-lc-add "Add components" to learn more about adding
+components to a trace processing graph.
+
+This function calls the filter component's
+\ref api-comp-cls-dev-meth-init "initialization method" after
+creating it.
+
+The created filter component's initialization method receives:
+
+- \bt_p{params} as its own \bt_p{params} parameter (or an empty
+ \bt_map_val if \bt_p{params} is \c NULL).
+
+- \bt_p{initialize_method_data} as its own \bt_p{initialize_method_data}
+ parameter.
+
+The created filter component can get its logging level
+(\bt_p{logging_level}) with bt_component_get_logging_level().
+
+@param[in] graph
+ Trace processing graph to which to add the created filter component.
+@param[in] component_class
+ Class to instantiate within \bt_p{graph}.
+@param[in] name
+ Unique name, within \bt_p{graph}, of the component to create.
+@param[in] params
+ @parblock
+ Initialization parameters to use when creating the filter component.
+
+ Can be \c NULL, in which case the created filter component's
+ initialization method receives an empty \bt_map_val as its
+ \bt_p{params} parameter.
+ @endparblock
+@param[in] initialize_method_data
+ User data passed as is to the created filter component's
+ initialization method.
+@param[in] logging_level
+ Initial logging level of the filter component to create.
+@param[out] component
+ <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
+ a \em borrowed reference of the created filter component.
+
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
+ Success.
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
+ Other error, for example, the created filter component's
+ initialization method failed.
+
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_configured{graph}
+@bt_pre_graph_not_faulty{graph}
+@bt_pre_not_null{component_class}
+@bt_pre_not_null{name}
+@pre
+ No other component within \bt_p{graph} has the name \bt_p{name}.
+@pre
+ \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
+ or is \c NULL.
+
+@bt_post_success_frozen{component_class}
+@bt_post_success_frozen{params}
+*/
extern 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 *init_method_data, bt_logging_level log_level,
+ void *initialize_method_data, bt_logging_level logging_level,
const bt_component_filter **component);
+/*!
+@brief
+ Alias of bt_graph_add_sink_component_with_initialize_method_data()
+ with the \bt_p{initialize_method_data} parameter set to \c NULL.
+*/
extern 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 log_level,
+ bt_logging_level logging_level,
const bt_component_sink **component);
+/*!
+@brief
+ Creates a \bt_sink_comp from the
+ \ref api-tir-comp-cls "class" \bt_p{component_class}
+ with the initialization parameters \bt_p{params}, the initialization
+ user data \bt_p{initialize_method_data}, and the initial
+ logging level \bt_p{logging_level}, adds it to the trace processing
+ graph \bt_p{graph} with the name \bt_p{name}, and sets
+ \bt_p{*component} to the resulting component.
+
+See \ref api-graph-lc-add "Add components" to learn more about adding
+components to a trace processing graph.
+
+This function calls the sink component's
+\ref api-comp-cls-dev-meth-init "initialization method" after
+creating it.
+
+The created sink component's initialization method receives:
+
+- \bt_p{params} as its own \bt_p{params} parameter (or an empty
+ \bt_map_val if \bt_p{params} is \c NULL).
+
+- \bt_p{initialize_method_data} as its own \bt_p{initialize_method_data}
+ parameter.
+
+The created sink component can get its logging level
+(\bt_p{logging_level}) with bt_component_get_logging_level().
+
+@param[in] graph
+ Trace processing graph to which to add the created sink component.
+@param[in] component_class
+ Class to instantiate within \bt_p{graph}.
+@param[in] name
+ Unique name, within \bt_p{graph}, of the component to create.
+@param[in] params
+ @parblock
+ Initialization parameters to use when creating the sink component.
+
+ Can be \c NULL, in which case the created sink component's
+ initialization method receives an empty \bt_map_val as its
+ \bt_p{params} parameter.
+ @endparblock
+@param[in] initialize_method_data
+ User data passed as is to the created sink component's
+ initialization method.
+@param[in] logging_level
+ Initial logging level of the sink component to create.
+@param[out] component
+ <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
+ a \em borrowed reference of the created sink component.
+
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
+ Success.
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
+ Other error, for example, the created sink component's
+ initialization method failed.
+
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_configured{graph}
+@bt_pre_graph_not_faulty{graph}
+@bt_pre_not_null{component_class}
+@bt_pre_not_null{name}
+@pre
+ No other component within \bt_p{graph} has the name \bt_p{name}.
+@pre
+ \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
+ or is \c NULL.
+
+@bt_post_success_frozen{component_class}
+@bt_post_success_frozen{params}
+*/
extern 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 *init_method_data, bt_logging_level log_level,
+ void *initialize_method_data, bt_logging_level logging_level,
const bt_component_sink **component);
+/*! @} */
+
+/*!
+@name Simple sink component adding
+@{
+*/
+
+/*!
+@brief
+ Status codes for the #bt_graph_simple_sink_component_initialize_func
+ type.
+*/
+typedef enum bt_graph_simple_sink_component_initialize_func_status {
+ /*!
+ @brief
+ Success.
+ */
+ BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_OK = __BT_FUNC_STATUS_OK,
+
+ /*!
+ @brief
+ Out of memory.
+ */
+ BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+ /*!
+ @brief
+ Other error.
+ */
+ BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
+} bt_graph_simple_sink_component_initialize_func_status;
+
+/*!
+@brief
+ 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 \bt_msg_iter. This occurs the first time you call
+bt_graph_run() or bt_graph_run_once() on the trace processing graph.
+
+See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
+about adding a simple component to a trace processing graph.
+
+@param[in] message_iterator
+ @parblock
+ 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.
+ @endparblock
+@param[in] user_data
+ User data, as passed as the \bt_p{user_data} parameter of
+ bt_graph_add_simple_sink_component().
+
+@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_OK
+ Success.
+@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_ERROR
+ Other error.
+
+@bt_pre_not_null{message_iterator}
+
+@post
+ The reference count of \bt_p{message_iterator} is not changed.
+
+@sa bt_graph_add_simple_sink_component() —
+ Creates and adds a simple sink component to a trace processing
+ graph.
+*/
+typedef bt_graph_simple_sink_component_initialize_func_status
+(*bt_graph_simple_sink_component_initialize_func)(
+ bt_message_iterator *message_iterator,
+ void *user_data);
+
+/*!
+@brief
+ Status codes for the #bt_graph_simple_sink_component_consume_func
+ type.
+*/
+typedef enum bt_graph_simple_sink_component_consume_func_status {
+ /*!
+ @brief
+ Success.
+ */
+ BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK = __BT_FUNC_STATUS_OK,
+
+ /*!
+ @brief
+ End of processing.
+ */
+ BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END = __BT_FUNC_STATUS_END,
+
+ /*!
+ @brief
+ Try again.
+ */
+ BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
+
+ /*!
+ @brief
+ Out of memory.
+ */
+ BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+ /*!
+ @brief
+ Other error.
+ */
+ BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
+} bt_graph_simple_sink_component_consume_func_status;
+
+/*!
+@brief
+ User consuming function for bt_graph_add_simple_sink_component().
+
+Such a consuming function is called when the simple sink component's own
+\ref api-comp-cls-dev-meth-consume "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 \ref api-graph-lc-add-ss "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.
+
+@param[in] message_iterator
+ @parblock
+ 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.
+ @endparblock
+@param[in] user_data
+ User data, as passed as the \bt_p{user_data} parameter of
+ bt_graph_add_simple_sink_component().
+
+@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK
+ Success.
+@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END
+ End of processing.
+@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN
+ Try again.
+@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_ERROR
+ Other error.
+
+@bt_pre_not_null{message_iterator}
+
+@post
+ The reference count of \bt_p{message_iterator} is not changed.
+
+@sa bt_graph_add_simple_sink_component() —
+ Creates and adds a simple sink component to a trace processing
+ graph.
+*/
+typedef bt_graph_simple_sink_component_consume_func_status
+(*bt_graph_simple_sink_component_consume_func)(
+ bt_message_iterator *message_iterator,
+ void *user_data);
+
+/*!
+@brief
+ 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 \ref api-fund-shared-object "reference"
+with bt_graph_put_ref()).
+
+See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
+about adding a simple component to a trace processing graph.
+
+@param[in] user_data
+ User data, as passed as the \bt_p{user_data} parameter of
+ bt_graph_add_simple_sink_component().
+
+@bt_post_no_error
+
+@sa bt_graph_add_simple_sink_component() —
+ Creates and adds a simple sink component to a trace processing
+ graph.
+*/
+typedef void (*bt_graph_simple_sink_component_finalize_func)(void *user_data);
+
+/*!
+@brief
+ Creates a simple \bt_sink_comp, adds it to the trace processing
+ graph \bt_p{graph} with the name \bt_p{name}, and sets
+ \bt_p{*component} to the resulting component.
+
+See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
+about adding a simple component to a trace processing graph.
+
+\bt_p{initialize_func} (if not \c NULL), \bt_p{consume_func},
+and \bt_p{finalize_func} (if not \c NULL) receive \bt_p{user_data}
+as their own \bt_p{user_data} parameter.
+
+@param[in] graph
+ Trace processing graph to which to add the created simple sink
+ component.
+@param[in] name
+ Unique name, within \bt_p{graph}, of the component to create.
+@param[in] initialize_func
+ @parblock
+ User initialization function.
+
+ Can be \c NULL.
+ @endparblock
+@param[in] consume_func
+ User consuming function.
+@param[in] finalize_func
+ @parblock
+ User finalization function.
+
+ Can be \c NULL.
+ @endparblock
+@param[in] user_data
+ User data to pass as the \bt_p{user_data} parameter of
+ \bt_p{initialize_func}, \bt_p{consume_func}, and
+ \bt_p{finalize_func}.
+@param[out] component
+ <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
+ a \em borrowed reference of the created simple sink component.
+
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
+ Success.
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
+ Other error, for example, the created sink component's
+ \ref api-comp-cls-dev-meth-init "initialization method" failed.
+
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_configured{graph}
+@bt_pre_graph_not_faulty{graph}
+@bt_pre_not_null{name}
+@pre
+ No other component within \bt_p{graph} has the name \bt_p{name}.
+@bt_pre_not_null{consume_func}
+*/
extern bt_graph_add_component_status
bt_graph_add_simple_sink_component(bt_graph *graph, const char *name,
- bt_graph_simple_sink_component_initialize_func init_func,
+ 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);
+/*! @} */
+
+/*!
+@name Component port connection
+@{
+*/
+
+/*!
+@brief
+ Status codes for bt_graph_connect_ports().
+*/
typedef enum bt_graph_connect_ports_status {
+ /*!
+ @brief
+ Success.
+ */
BT_GRAPH_CONNECT_PORTS_STATUS_OK = __BT_FUNC_STATUS_OK,
- BT_GRAPH_CONNECT_PORTS_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
+
+ /*!
+ @brief
+ Out of memory.
+ */
BT_GRAPH_CONNECT_PORTS_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+ /*!
+ @brief
+ Other error.
+ */
+ BT_GRAPH_CONNECT_PORTS_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
} bt_graph_connect_ports_status;
+/*!
+@brief
+ Connects the \bt_oport \bt_p{upstream_port} to the \bt_iport
+ \bt_p{downstream_port} within the trace processing graph
+ \bt_p{graph}, and sets \bt_p{*connection} to the resulting
+ \bt_conn.
+
+See \ref api-graph-lc-connect "Connect component ports" to learn more
+about connecting ports within a trace processing graph.
+
+Both \bt_p{upstream_port} and \bt_p{downstream_port} must be
+unconnected (bt_port_is_connected() returns #BT_FALSE) when you call
+this function.
+
+@param[in] graph
+ Trace processing graph containing the \bt_p_comp to which belong
+ \bt_p{upstream_port} and \bt_p{downstream_port}.
+@param[in] upstream_port
+ \bt_c_oport to connect to \bt_p{downstream_port}.
+@param[in] downstream_port
+ \bt_c_iport to connect to \bt_p{upstream_port}.
+@param[in] connection
+ <strong>On success, if not \c NULL</strong>, \bt_p{*connection} is
+ a \em borrowed reference of the resulting \bt_conn.
+
+@retval #BT_GRAPH_CONNECT_PORTS_STATUS_OK
+ Success.
+@retval #BT_GRAPH_CONNECT_PORTS_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_GRAPH_CONNECT_PORTS_STATUS_ERROR
+ Other error.
+
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_configured{graph}
+@bt_pre_graph_not_faulty{graph}
+@bt_pre_not_null{upstream_port}
+@pre
+ \bt_p{graph} contains the component of \bt_p{upstream_port},
+ as returned by bt_port_borrow_component_const().
+@pre
+ \bt_p{upstream_port} is unconnected
+ (bt_port_is_connected() returns #BT_FALSE).
+@bt_pre_not_null{downstream_port}
+@pre
+ \bt_p{graph} contains the component of \bt_p{downstream_port},
+ as returned by bt_port_borrow_component_const().
+@pre
+ \bt_p{downstream_port} is unconnected
+ (bt_port_is_connected() returns #BT_FALSE).
+@pre
+ Connecting \bt_p{upstream_port} to \bt_p{downstream_port} does not
+ form a connection cycle within \bt_p{graph}.
+*/
extern bt_graph_connect_ports_status bt_graph_connect_ports(bt_graph *graph,
- const bt_port_output *upstream,
- const bt_port_input *downstream,
+ const bt_port_output *upstream_port,
+ const bt_port_input *downstream_port,
const bt_connection **connection);
+/*! @} */
+
+/*!
+@name Running
+@{
+*/
+
+/*!
+@brief
+ Status codes for bt_graph_run().
+*/
typedef enum bt_graph_run_status {
+ /*!
+ @brief
+ Success.
+ */
BT_GRAPH_RUN_STATUS_OK = __BT_FUNC_STATUS_OK,
- BT_GRAPH_RUN_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
- BT_GRAPH_RUN_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+ /*!
+ @brief
+ Try again.
+ */
BT_GRAPH_RUN_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
+
+ /*!
+ @brief
+ Out of memory.
+ */
+ BT_GRAPH_RUN_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+ /*!
+ @brief
+ Other error.
+ */
+ BT_GRAPH_RUN_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
} bt_graph_run_status;
+/*!
+@brief
+ Runs the trace processing graph \bt_p{graph}, calling each
+ \bt_sink_comp's
+ \ref api-comp-cls-dev-meth-consume "consuming method" in a round
+ robin fashion until they are all done consuming or an exception
+ occurs.
+
+See \ref api-graph-lc-run "Run" to learn more about running a trace
+processing graph.
+
+This function does \em 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.
+
+- \bt_p{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 \bt_intr's state with bt_interrupter_is_set() to
+ distinguish between a sink component returning "try again" and
+ \bt_p{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,
+\bt_p{graph} becomes <em>configured</em>. See
+\ref api-graph-lc "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.
+
+@param[in] graph
+ Trace processing graph to run.
+
+@retval #BT_GRAPH_RUN_STATUS_OK
+ Success.
+@retval #BT_GRAPH_RUN_STATUS_AGAIN
+ Try again.
+@retval #BT_GRAPH_RUN_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_GRAPH_RUN_STATUS_ERROR
+ Other error.
+
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_faulty{graph}
+@pre
+ For each \bt_src_comp within \bt_p{graph}, at least one \bt_oport
+ is connected.
+@pre
+ For each \bt_flt_comp within \bt_p{graph}, at least one \bt_iport
+ and one \bt_iport are connected.
+@pre
+ For each \bt_sink_comp within \bt_p{graph}, at least one \bt_iport
+ is connected.
+@pre
+ \bt_p{graph} contains at least one sink component.
+
+@sa bt_graph_run_once() —
+ Calls a single trace processing graph's sink component's consuming
+ method once.
+*/
extern bt_graph_run_status bt_graph_run(bt_graph *graph);
+/*!
+@brief
+ Status codes for bt_graph_run().
+*/
typedef enum bt_graph_run_once_status {
+ /*!
+ @brief
+ Success.
+ */
BT_GRAPH_RUN_ONCE_STATUS_OK = __BT_FUNC_STATUS_OK,
- BT_GRAPH_RUN_ONCE_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
- BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
- BT_GRAPH_RUN_ONCE_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
+
+ /*!
+ @brief
+ All sink components are finished processing.
+ */
BT_GRAPH_RUN_ONCE_STATUS_END = __BT_FUNC_STATUS_END,
+
+ /*!
+ @brief
+ Try again.
+ */
+ BT_GRAPH_RUN_ONCE_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
+
+ /*!
+ @brief
+ Out of memory.
+ */
+ BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+ /*!
+ @brief
+ Other error.
+ */
+ BT_GRAPH_RUN_ONCE_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
} bt_graph_run_once_status;
+/*!
+@brief
+ Calls the \ref api-comp-cls-dev-meth-consume "consuming method" of
+ the next non-ended \bt_sink_comp to make consume within the trace
+ processing graph \bt_p{graph}.
+
+See \ref api-graph-lc-run "Run" to learn more about running a trace
+processing graph.
+
+This function makes the \em next non-ended sink component consume. For
+example, if \bt_p{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 \bt_p{graph} contains a single non-ended sink
+component, this function \em always makes this sink component consume.
+
+If the sink component's consuming method:
+
+<dl>
+ <dt>Succeeds</dt>
+ <dd>This function returns #BT_GRAPH_RUN_ONCE_STATUS_OK.</dd>
+
+ <dt>Returns "try again"</dt>
+ <dd>This function returns #BT_GRAPH_RUN_ONCE_STATUS_AGAIN.</dd>
+
+ <dt>Fails</dt>
+ <dd>
+ This function returns #BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR
+ or #BT_GRAPH_RUN_ONCE_STATUS_ERROR.
+ </dd>
+</dl>
+
+When all the sink components of \bt_p{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,
+\bt_p{graph} becomes <em>configured</em>. See
+\ref api-graph-lc "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.
+
+@param[in] graph
+ Trace processing graph of which to make the next sink component
+ consume.
+
+@retval #BT_GRAPH_RUN_ONCE_STATUS_OK
+ Success.
+@retval #BT_GRAPH_RUN_ONCE_STATUS_END
+ All sink components are finished processing.
+@retval #BT_GRAPH_RUN_ONCE_STATUS_AGAIN
+ Try again.
+@retval #BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_GRAPH_RUN_ONCE_STATUS_ERROR
+ Other error.
+
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_faulty{graph}
+
+@sa bt_graph_run() —
+ Runs a trace processing graph, making all its sink components
+ consume in a round robin fashion.
+*/
extern bt_graph_run_once_status bt_graph_run_once(bt_graph *graph);
+/*! @} */
+
+/*!
+@name Interruption
+@{
+*/
+
+/*!
+@brief
+ Status codes for bt_graph_add_interrupter().
+*/
+typedef enum bt_graph_add_interrupter_status {
+ /*!
+ @brief
+ Success.
+ */
+ BT_GRAPH_ADD_INTERRUPTER_STATUS_OK = __BT_FUNC_STATUS_OK,
+
+ /*!
+ @brief
+ Out of memory.
+ */
+ BT_GRAPH_ADD_INTERRUPTER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_graph_add_interrupter_status;
+
+/*!
+@brief
+ Adds the \bt_intr \bt_p{interrupter} to all the current and future
+ \bt_p_sink_comp and \bt_p_msg_iter of the trace processing graph
+ \bt_p{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
+ @parblock
+ bt_graph_create() returns a trace processing graph which comes
+ with its own <em>default interrupter</em>.
+
+ Instead of adding your own interrupter to \bt_p{graph}, you can
+ set its default interrupter with
+
+ @code
+ bt_interrupter_set(bt_graph_borrow_default_interrupter());
+ @endcode
+ @endparblock
+
+@param[in] graph
+ Trace processing graph to which to add \bt_p{interrupter}.
+@param[in] interrupter
+ Interrupter to add to \bt_p{graph}.
+
+@retval #BT_GRAPH_ADD_INTERRUPTER_STATUS_OK
+ Success.
+@retval #BT_GRAPH_ADD_INTERRUPTER_STATUS_MEMORY_ERROR
+ Out of memory.
+
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_faulty{graph}
+@bt_pre_not_null{interrupter}
+
+@sa bt_graph_borrow_default_interrupter() —
+ Borrows the default interrupter from a trace processing graph.
+*/
+extern bt_graph_add_interrupter_status bt_graph_add_interrupter(bt_graph *graph,
+ const bt_interrupter *interrupter);
+
+/*!
+@brief
+ Borrows the default \bt_intr from the trace processing graph
+ \bt_p{graph}.
+
+@param[in] graph
+ Trace processing graph from which to borrow the default interrupter.
+
+@returns
+ @parblock
+ \em Borrowed reference of the default interrupter of \bt_p{graph}.
+
+ The returned pointer remains valid as long as \bt_p{graph} exists.
+ @endparblock
+
+@bt_pre_not_null{graph}
+
+@sa bt_graph_add_interrupter() —
+ Adds an interrupter to a trace processing graph.
+*/
+extern bt_interrupter *bt_graph_borrow_default_interrupter(bt_graph *graph);
+
+/*! @} */
+
+/*!
+@name Listeners
+@{
+*/
+
+/*!
+@brief
+ Status codes for the
+ <code>bt_graph_add_*_component_*_port_added_listener()</code>
+ functions.
+*/
typedef enum bt_graph_add_listener_status {
+ /*!
+ @brief
+ Success.
+ */
BT_GRAPH_ADD_LISTENER_STATUS_OK = __BT_FUNC_STATUS_OK,
+
+ /*!
+ @brief
+ Out of memory.
+ */
BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
} bt_graph_add_listener_status;
+/*!
+@brief
+ Status codes for the
+ <code>bt_graph_*_component_*_port_added_listener_func()</code>
+ types.
+*/
+typedef enum bt_graph_listener_func_status {
+ /*!
+ @brief
+ Success.
+ */
+ BT_GRAPH_LISTENER_FUNC_STATUS_OK = __BT_FUNC_STATUS_OK,
+
+ /*!
+ @brief
+ Out of memory.
+ */
+ BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+ /*!
+ @brief
+ Other error.
+ */
+ BT_GRAPH_LISTENER_FUNC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
+} bt_graph_listener_func_status;
+
+/*!
+@brief
+ User function for
+ bt_graph_add_filter_component_input_port_added_listener().
+
+Such a function is called whenever a \bt_flt_comp within a trace
+processing graph adds an \bt_iport during the graph
+\ref api-graph-lc "configuration" phase.
+
+See \ref api-graph-listeners "Listeners" to learn more.
+
+@param[in] component
+ Filter component which added \bt_p{port}.
+@param[in] port
+ Input port added by \bt_p{component}.
+@param[in] user_data
+ User data, as passed as the \bt_p{user_data} parameter of
+ bt_graph_add_filter_component_input_port_added_listener().
+
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
+ Success.
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
+ Other error.
+
+@bt_pre_not_null{component}
+@bt_pre_not_null{port}
+
+@sa bt_graph_add_filter_component_input_port_added_listener() —
+ Adds a "filter component input port added" listener to a trace
+ processing graph.
+*/
+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);
+
+/*!
+@brief
+ Adds a \"\bt_flt_comp \bt_iport added\" listener to the trace
+ processing graph \bt_p{graph}.
+
+Once this function returns, \bt_p{user_func} is called whenever a
+filter component adds an input port within \bt_p{graph}.
+
+See \ref api-graph-listeners "Listeners" to learn more.
+
+@param[in] graph
+ Trace processing graph to add the "filter component input port
+ added" listener to.
+@param[in] user_func
+ User function of the "filter component input port added" listener to
+ add to \bt_p{graph}.
+@param[in] user_data
+ User data to pass as the \bt_p{user_data} parameter of
+ \bt_p{user_func}.
+@param[out] listener_id
+ <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
+ is the ID of the added listener within \bt_p{graph}.
+
+@retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
+ Success.
+@retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
+ Out of memory.
+
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_faulty{graph}
+@bt_pre_not_null{user_func}
+*/
extern 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 listener,
- void *data, bt_listener_id *listener_id);
+ bt_graph_filter_component_input_port_added_listener_func user_func,
+ void *user_data, bt_listener_id *listener_id);
+
+/*!
+@brief
+ User function for
+ bt_graph_add_sink_component_input_port_added_listener().
+
+Such a function is called whenever a \bt_sink_comp within a trace
+processing graph adds an \bt_iport during the graph
+\ref api-graph-lc "configuration" phase.
+
+See \ref api-graph-listeners "Listeners" to learn more.
+
+@param[in] component
+ Filter component which added \bt_p{port}.
+@param[in] port
+ Input port added by \bt_p{component}.
+@param[in] user_data
+ User data, as passed as the \bt_p{user_data} parameter of
+ bt_graph_add_sink_component_input_port_added_listener().
+
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
+ Success.
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
+ Other error.
+
+@bt_pre_not_null{component}
+@bt_pre_not_null{port}
+
+@sa bt_graph_add_sink_component_input_port_added_listener() —
+ Adds a "sink component input port added" listener to a trace
+ processing graph.
+*/
+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);
+
+/*!
+@brief
+ Adds a \"\bt_sink_comp \bt_iport added\" listener to the trace
+ processing graph \bt_p{graph}.
+
+Once this function returns, \bt_p{user_func} is called whenever a
+sink component adds an input port within \bt_p{graph}.
+
+See \ref api-graph-listeners "Listeners" to learn more.
+
+@param[in] graph
+ Trace processing graph to add the "sink component input port
+ added" listener to.
+@param[in] user_func
+ User function of the "sink component input port added" listener to
+ add to \bt_p{graph}.
+@param[in] user_data
+ User data to pass as the \bt_p{user_data} parameter of
+ \bt_p{user_func}.
+@param[out] listener_id
+ <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
+ is the ID of the added listener within \bt_p{graph}.
+
+@retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
+ Success.
+@retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
+ Out of memory.
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_faulty{graph}
+@bt_pre_not_null{user_func}
+*/
extern 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 listener,
- void *data, bt_listener_id *listener_id);
+ bt_graph_sink_component_input_port_added_listener_func user_func,
+ void *user_data, bt_listener_id *listener_id);
+/*!
+@brief
+ User function for
+ bt_graph_add_source_component_output_port_added_listener().
+
+Such a function is called whenever a \bt_src_comp within a trace
+processing graph adds an \bt_oport during the graph
+\ref api-graph-lc "configuration" phase.
+
+See \ref api-graph-listeners "Listeners" to learn more.
+
+@param[in] component
+ Filter component which added \bt_p{port}.
+@param[in] port
+ Input port added by \bt_p{component}.
+@param[in] user_data
+ User data, as passed as the \bt_p{user_data} parameter of
+ bt_graph_add_source_component_output_port_added_listener().
+
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
+ Success.
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
+ Other error.
+
+@bt_pre_not_null{component}
+@bt_pre_not_null{port}
+
+@sa bt_graph_add_source_component_output_port_added_listener() —
+ Adds a "source component output port added" listener to a trace
+ processing graph.
+*/
+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);
+
+/*!
+@brief
+ Adds a \"\bt_src_comp \bt_oport added\" listener to the trace
+ processing graph \bt_p{graph}.
+
+Once this function returns, \bt_p{user_func} is called whenever a
+source component adds an output port within \bt_p{graph}.
+
+See \ref api-graph-listeners "Listeners" to learn more.
+
+@param[in] graph
+ Trace processing graph to add the "source component output port
+ added" listener to.
+@param[in] user_func
+ User function of the "source component output port added" listener
+ to add to \bt_p{graph}.
+@param[in] user_data
+ User data to pass as the \bt_p{user_data} parameter of
+ \bt_p{user_func}.
+@param[out] listener_id
+ <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
+ is the ID of the added listener within \bt_p{graph}.
+
+@retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
+ Success.
+@retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
+ Out of memory.
+
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_faulty{graph}
+@bt_pre_not_null{user_func}
+*/
extern 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 listener,
- void *data, bt_listener_id *listener_id);
+ bt_graph_source_component_output_port_added_listener_func user_func,
+ void *user_data, bt_listener_id *listener_id);
+
+/*!
+@brief
+ User function for
+ bt_graph_add_filter_component_output_port_added_listener().
+
+Such a function is called whenever a \bt_flt_comp within a trace
+processing graph adds an \bt_oport during the graph
+\ref api-graph-lc "configuration" phase.
+
+See \ref api-graph-listeners "Listeners" to learn more.
+
+@param[in] component
+ Filter component which added \bt_p{port}.
+@param[in] port
+ Input port added by \bt_p{component}.
+@param[in] user_data
+ User data, as passed as the \bt_p{user_data} parameter of
+ bt_graph_add_filter_component_output_port_added_listener().
+
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
+ Success.
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
+ Other error.
+
+@bt_pre_not_null{component}
+@bt_pre_not_null{port}
+
+@sa bt_graph_add_filter_component_output_port_added_listener() —
+ Adds a "filter component output port added" listener to a trace
+ processing graph.
+*/
+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);
+
+/*!
+@brief
+ Adds a \"\bt_flt_comp \bt_oport added\" listener to the trace
+ processing graph \bt_p{graph}.
+
+Once this function returns, \bt_p{user_func} is called whenever a
+filter component adds an output port within \bt_p{graph}.
+
+See \ref api-graph-listeners "Listeners" to learn more.
+@param[in] graph
+ Trace processing graph to add the "filter component output port
+ added" listener to.
+@param[in] user_func
+ User function of the "filter component output port added" listener
+ to add to \bt_p{graph}.
+@param[in] user_data
+ User data to pass as the \bt_p{user_data} parameter of
+ \bt_p{user_func}.
+@param[out] listener_id
+ <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
+ is the ID of the added listener within \bt_p{graph}.
+
+@retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
+ Success.
+@retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
+ Out of memory.
+
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_faulty{graph}
+@bt_pre_not_null{user_func}
+*/
extern 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 listener,
- void *data, bt_listener_id *listener_id);
+ bt_graph_filter_component_output_port_added_listener_func user_func,
+ void *user_data, bt_listener_id *listener_id);
-typedef enum bt_graph_add_interrupter_status {
- BT_GRAPH_ADD_INTERRUPTER_STATUS_OK = __BT_FUNC_STATUS_OK,
- BT_GRAPH_ADD_INTERRUPTER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_graph_add_interrupter_status;
+/*! @} */
-extern bt_graph_add_interrupter_status bt_graph_add_interrupter(bt_graph *graph,
- const bt_interrupter *interrupter);
+/*!
+@name Reference count
+@{
+*/
-extern bt_interrupter *bt_graph_borrow_default_interrupter(bt_graph *graph);
+/*!
+@brief
+ Increments the \ref api-fund-shared-object "reference count" of
+ the trace processing graph \bt_p{graph}.
+
+@param[in] graph
+ @parblock
+ Trace processing graph of which to increment the reference count.
+
+ Can be \c NULL.
+ @endparblock
+
+@sa bt_graph_put_ref() —
+ Decrements the reference count of a trace processing graph.
+*/
+extern void bt_graph_get_ref(const bt_graph *graph);
+
+/*!
+@brief
+ Decrements the \ref api-fund-shared-object "reference count" of
+ the trace processing graph \bt_p{graph}.
+
+@param[in] graph
+ @parblock
+ Trace processing graph of which to decrement the reference count.
+
+ Can be \c NULL.
+ @endparblock
+
+@sa bt_graph_get_ref() —
+ Increments the reference count of a trace processing graph.
+*/
+extern void bt_graph_put_ref(const bt_graph *graph);
+
+/*!
+@brief
+ Decrements the reference count of the trace processing graph
+ \bt_p{_graph}, and then sets \bt_p{_graph} to \c NULL.
+
+@param _graph
+ @parblock
+ Trace processing graph of which to decrement the reference count.
+
+ Can contain \c NULL.
+ @endparblock
+
+@bt_pre_assign_expr{_graph}
+*/
+#define BT_GRAPH_PUT_REF_AND_RESET(_graph) \
+ do { \
+ bt_graph_put_ref(_graph); \
+ (_graph) = NULL; \
+ } while (0)
+
+/*!
+@brief
+ Decrements the reference count of the trace processing graph
+ \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets
+ \bt_p{_src} to \c NULL.
+
+This macro effectively moves a trace processing graph reference from the
+expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
+existing \bt_p{_dst} reference.
+
+@param _dst
+ @parblock
+ Destination expression.
+
+ Can contain \c NULL.
+ @endparblock
+@param _src
+ @parblock
+ Source expression.
+
+ Can contain \c NULL.
+ @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_GRAPH_MOVE_REF(_dst, _src) \
+ do { \
+ bt_graph_put_ref(_dst); \
+ (_dst) = (_src); \
+ (_src) = NULL; \
+ } while (0)
+
+/*! @} */
+
+/*! @} */
#ifdef __cplusplus
}
projects / babeltrace.git / blobdiff