X-Git-Url: https://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace2%2Fgraph%2Fgraph.h;h=6c7b2d1b8cba495bb5ae7597e41c634fd2f14c59;hb=7704a0af9f2275321f8294df8c02f8a299b3134e;hp=059992c22244c3d2652cf012d4b0620e9a12b481;hpb=0dcb770f6937931cd08a8046fc17b03e54d43aa4;p=babeltrace.git
diff --git a/include/babeltrace2/graph/graph.h b/include/babeltrace2/graph/graph.h
index 059992c2..6c7b2d1b 100644
--- a/include/babeltrace2/graph/graph.h
+++ b/include/babeltrace2/graph/graph.h
@@ -34,214 +34,1981 @@
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 trace processing graph is a specialized
+filter graph
+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).
+
+ There are five \bt_p_conn, from five \bt_p_oport
+ to five \bt_p_iport.
+
+- 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
+ \ref api-tir-comp-cls "class": source.ctf.fs
.
+
+- All components are instances of \bt_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:
+
+@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().
+
+
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().
+
+*_with_initialize_method_data()
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
+ On success, \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.
+
+bt_graph_add_*_component*()
+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.
+
+\-\-enable-debug-info
+ configuration option.
+
+ See \bt_man{babeltrace2-filter.lttng-utils.debug-info,7}.
+ dmesg
+ tool, and emits each line as an \bt_ev_msg.
+
+ See \bt_man{babeltrace2-source.text.dmesg,7}.
+ 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:
+
+- 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
+bt_graph_add_*_component*()
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
+ bt_graph_add_*_component*()
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
+ On success, if not \c NULL, \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_init_method_data(
+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
+ On success, if not \c NULL, \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_init_method_data(
+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
+ On success, if not \c NULL, \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_init_method_data(
+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
+ On success, if not \c NULL, \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 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,
- BT_GRAPH_CONNECT_PORTS_STATUS_CANCELED = __BT_FUNC_STATUS_CANCELED,
+
+ /*!
+ @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
+ On success, if not \c NULL, \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,
- BT_GRAPH_RUN_STATUS_END = __BT_FUNC_STATUS_END,
- BT_GRAPH_RUN_STATUS_CANCELED = __BT_FUNC_STATUS_CANCELED,
+
+ /*!
+ @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 configured. 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);
-typedef enum bt_graph_consume_status {
- BT_GRAPH_CONSUME_STATUS_OK = __BT_FUNC_STATUS_OK,
- BT_GRAPH_CONSUME_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
- BT_GRAPH_CONSUME_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
- BT_GRAPH_CONSUME_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
- BT_GRAPH_CONSUME_STATUS_END = __BT_FUNC_STATUS_END,
- BT_GRAPH_CONSUME_STATUS_CANCELED = __BT_FUNC_STATUS_CANCELED,
-} bt_graph_consume_status;
+/*!
+@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,
+
+ /*!
+ @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:
+
+bt_graph_add_*_component_*_port_added_listener()
+ 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
+ bt_graph_*_component_*_port_added_listener_func()
+ 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
+ On success and if not \c NULL, \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,
- bt_graph_listener_removed_func listener_removed, void *data,
- int *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
+ On success and if not \c NULL, \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,
- bt_graph_listener_removed_func listener_removed, void *data,
- int *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
+ On success and if not \c NULL, \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,
- bt_graph_listener_removed_func listener_removed, void *data,
- int *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
+ On success and if not \c NULL, \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,
- bt_graph_listener_removed_func listener_removed, void *data,
- int *listener_id);
+ bt_graph_filter_component_output_port_added_listener_func user_func,
+ void *user_data, bt_listener_id *listener_id);
-extern bt_graph_add_listener_status
-bt_graph_add_source_filter_component_ports_connected_listener(
- bt_graph *graph,
- bt_graph_source_filter_component_ports_connected_listener_func listener,
- bt_graph_listener_removed_func listener_removed, void *data,
- int *listener_id);
+/*! @} */
-extern bt_graph_add_listener_status
-bt_graph_add_filter_filter_component_ports_connected_listener(
- bt_graph *graph,
- bt_graph_filter_filter_component_ports_connected_listener_func listener,
- bt_graph_listener_removed_func listener_removed, void *data,
- int *listener_id);
+/*!
+@name Reference count
+@{
+*/
-extern bt_graph_add_listener_status
-bt_graph_add_source_sink_component_ports_connected_listener(
- bt_graph *graph,
- bt_graph_source_sink_component_ports_connected_listener_func listener,
- bt_graph_listener_removed_func listener_removed, void *data,
- int *listener_id);
+/*!
+@brief
+ Increments the \ref api-fund-shared-object "reference count" of
+ the trace processing graph \bt_p{graph}.
-extern bt_graph_add_listener_status
-bt_graph_add_filter_sink_component_ports_connected_listener(
- bt_graph *graph,
- bt_graph_filter_sink_component_ports_connected_listener_func listener,
- bt_graph_listener_removed_func listener_removed, void *data,
- int *listener_id);
+@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)
-typedef enum bt_graph_cancel_status {
- BT_GRAPH_CANCEL_STATUS_OK = __BT_FUNC_STATUS_OK,
-} bt_graph_cancel_status;
+/*! @} */
-extern bt_graph_cancel_status bt_graph_cancel(bt_graph *graph);
+/*! @} */
#ifdef __cplusplus
}