X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=include%2Fbabeltrace2%2Fgraph%2Fgraph.h;h=6c7b2d1b8cba495bb5ae7597e41c634fd2f14c59;hp=d562e366e41ace21e3efe49da982d8115eaf8e28;hb=43c59509042845f8d42c3e99ec74d45fa2dc0908;hpb=1cda4ff4025e4b3f7bd2a861baa51d2113c4cbf9 diff --git a/include/babeltrace2/graph/graph.h b/include/babeltrace2/graph/graph.h index d562e366..6c7b2d1b 100644 --- a/include/babeltrace2/graph/graph.h +++ b/include/babeltrace2/graph/graph.h @@ -34,213 +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). -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": 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(). + +

\anchor api-graph-lc Trace processing graph life cycle

+ +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 +configured, 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 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(). + +

\anchor api-graph-lc-add Add components

+ +Adding a \bt_comp to a trace processing graph is also known as +instantiating a \bt_comp_cls 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: + +
+
Source component
+
+
+
Without initialization method data
+
bt_graph_add_source_component()
+ +
With initialization method data
+
bt_graph_add_source_component_with_initialize_method_data()
+
+
+ +
Filter component
+
+
+
Without initialization method data
+
bt_graph_add_filter_component()
+ +
With initialization method data
+
bt_graph_add_filter_component_with_initialize_method_data()
+
+
+ +
Sink component
+
+
+
Without initialization method data
+
bt_graph_add_sink_component()
+ +
With initialization method data
+
bt_graph_add_sink_component_with_initialize_method_data()
+
+
+
+ +The *_with_initialize_method_data() versions can pass a +custom, \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. + +

\anchor api-graph-lc-add-ss Add a simple sink component

+ +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: + +
+
\bt_dt_opt Initialization
+
+ Called when the trace processing graph becomes + configured and when the sink component created its single + message iterator. + + You can do an initial action with the message iterator such as + making it seek a specific point in time or getting messages. +
+ +
Consume
+
+ Called every time the sink component's + \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. +
+ +
\bt_dt_opt Finalization
+
+ Called when the sink component is finalized. +
+
+ +The three functions above receive, as their last parameter, the user +data you passed to bt_graph_add_simple_sink_component() . + +

\anchor api-graph-lc-connect Connect component ports

+ +When you \ref api-graph-lc-add "add a component" to a trace processing +graph with one of the 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. + +

\anchor api-graph-lc-run Run

+ +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(). + +

Standard \bt_name component classes

-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: + +
+
\c ctf plugin
+
+
+
\c fs source component class
+
+ Opens a + CTF trace on the file + system and emits the \bt_p_msg of their data stream files. + + See \bt_man{babeltrace2-source.ctf.fs,7}. +
+ +
\c lttng-live source component class
+
+ Connects to an LTTng relay + daemon and emits the messages of the received CTF data streams. + + See \bt_man{babeltrace2-source.ctf.lttng-live,7}. +
+ +
\c fs sink component class
+
+ Writes the consumed messages as one or more CTF traces on the + file system. + + See \bt_man{babeltrace2-sink.ctf.fs,7}. +
+
+
+ +
\c lttng-utils plugin
+
+
+
\c debug-info filter component class
+
+ Adds debugging information to compatible LTTng event messages. + + This component class is only available if the project was + built with the \-\-enable-debug-info + configuration option. + + See \bt_man{babeltrace2-filter.lttng-utils.debug-info,7}. +
+
+
+ +
\c text plugin
+
+
+
\c dmesg source component class
+
+ Reads the lines of a Linux kernel ring buffer, that is, the + output of the + dmesg + tool, and emits each line as an \bt_ev_msg. + + See \bt_man{babeltrace2-source.text.dmesg,7}. +
+ +
\c details sink component class
+
+ Deterministically prints the messages it consumes with details + to the standard output. + + See \bt_man{babeltrace2-sink.text.details,7}. +
+ +
\c pretty sink component class
+
+ 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 + Babeltrace 1 + command-line tool. + + See \bt_man{babeltrace2-sink.text.pretty,7}. +
+
+
+ +
\c utils plugin
+
+
+
\c muxer filter component class
+
+ Muxes messages by time. + + See \bt_man{babeltrace2-filter.utils.muxer,7}. +
+ +
\c trimmer filter component class
+
+ 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}. +
+ +
\c counter sink component class
+
+ 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}. +
+ +
\c dummy sink component class
+
+ Consumes messages and discards them (does nothing with them). + + This is useful for testing and benchmarking a trace processing + graph application, for example. + + See \bt_man{babeltrace2-sink.utils.dummy,7}. +
+
+
+
+ +To access such a component class, get its plugin by name with +bt_plugin_find() and then borrow the component class by name +with bt_plugin_borrow_source_component_class_by_name_const(), +bt_plugin_borrow_filter_component_class_by_name_const(), or +bt_plugin_borrow_sink_component_class_by_name_const(). + +For example: + +@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 + +

\anchor api-graph-listeners Listeners

+ +A \bt_comp can add a \bt_port: + +- At initialization time, that is, when you call one of the + bt_graph_add_*_component*() functions. + +- When one of its ports gets connected, that is, when you call + bt_graph_connect_ports(). + +To get notified when any component of a given trace processing +graph adds a port, add one or more "port +added" listeners to the graph with: + +- 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_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_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_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 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 + 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, + + /*! + @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); +/*! +@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: + +
+
Succeeds
+
This function returns #BT_GRAPH_RUN_ONCE_STATUS_OK.
+ +
Returns "try again"
+
This function returns #BT_GRAPH_RUN_ONCE_STATUS_AGAIN.
+ +
Fails
+
+ This function returns #BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR + or #BT_GRAPH_RUN_ONCE_STATUS_ERROR. +
+
+ +When all the sink components of \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 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 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 default interrupter. + + 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 + 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, - 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 + 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, - 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 + 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, - 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 + 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, - 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 }