+- There are two source components having the same
+ \ref api-tir-comp-cls "class": <code>source.ctf.fs</code>.
+
+- All components are instances of \bt_plugin-provided classes:
+ <code>babeltrace2-plugin-ctf.so</code>,
+ <code>user-plugin.so</code>,
+ <code>babeltrace2-plugin-utils.so</code>, and
+ <code>babeltrace2-plugin-text.so</code>.
+
+Of course the topology can be much more complex if needed:
+
+@image html complex-graph.png "Complex trace processing graph."
+
+In a trace processing graph, \bt_p_comp are instances of \bt_p_comp_cls.
+
+A \bt_plugin can provide a component class, but you can also create one
+dynamically (see \ref api-comp-cls-dev).
+
+The connections between component ports in a trace processing graph
+indicate the needed topology to achieve a trace processing task. That
+being said,
+\bt_p_msg do not flow within connections. Instead, a source-to-sink
+or filter-to-sink connection makes it
+possible for a sink component to create a \bt_msg_iter on its end of
+the connection (an \bt_iport). In turn, a filter component message
+iterator can create other message iterators on one or more of the
+component's input ports. For a single connection, there can exist
+multiple message iterators.
+
+A trace processing graph is a
+\ref api-fund-shared-object "shared object": get a new reference with
+bt_graph_get_ref() and put an existing reference with
+bt_graph_put_ref().
+
+The type of a trace processing graph is #bt_graph.
+
+Create a default trace processing graph with bt_graph_create(). You need
+to pass a \bt_mip (MIP) version number when you call this function.
+Then, see
+\ref api-graph-lc "Trace processing graph life cycle"
+to learn how to add components to the graph, connect their ports, and
+run it.
+
+To interrupt a \ref api-graph-lc-run "running" trace processing graph,
+either:
+
+- Borrow the graph's default \bt_intr with
+ bt_graph_borrow_default_interrupter() and set it with
+ bt_interrupter_set().
+
+ When you call bt_graph_create(), the returned trace processing
+ graph has a default interrupter.
+
+- Add your own interrupter with bt_graph_add_interrupter() \em before
+ you run the graph with bt_graph_run() or bt_graph_run_once().
+
+ Then, set the interrupter with bt_interrupter_set().
+
+<h1>\anchor api-graph-lc Trace processing graph life cycle</h1>
+
+The following diagram shows the life cycle of a trace processing
+graph:
+
+@image html graph-lifetime.png "Trace processing graph lifecycle."
+
+After you create a default (empty) trace processing graph with
+bt_graph_create(), there are three steps to make the trace processing
+task execute:
+
+-# \ref api-graph-lc-add "Add components" to the graph.
+-# \ref api-graph-lc-connect "Connect component ports".
+-# \ref api-graph-lc-run "Run the graph".
+
+You can repeat steps 1 and 2 before step 3, as connecting a
+component \bt_port can make this \bt_comp create a new port:
+you might want to add a component in reaction to this event
+(see \ref api-graph-listeners "Listeners").
+
+Steps 1 and 2 constitute the \em configuration phase of the trace
+processing graph. The first time you call bt_graph_run() or
+bt_graph_run_once() for a given graph (step 3), the graph becomes
+<em>configured</em>, and it notifies the sink components as such so that
+they can create their \bt_p_msg_iter.
+
+Once a trace processing graph becomes configured:
+
+- You cannot \ref api-graph-lc-add "add a component" to it.
+
+- You cannot \ref api-graph-lc-connect "connect component ports".
+
+- Components cannot add ports.
+
+In general, as of \bt_name_version_min_maj:
+
+- You cannot remove a component from a trace processing graph.
+
+- You cannot end (remove) a port \bt_conn.
+
+- Components cannot remove ports.
+
+If \em any error occurs (a function returns a status code which ends
+with <code>ERROR</code>) during step 1 or 2, the trace processing
+graph is considered <strong>faulty</strong>: you cannot use it anymore.
+The only functions you can call with a faulty graph are
+bt_graph_get_ref() and bt_graph_put_ref().
+
+<h2>\anchor api-graph-lc-add Add components</h2>
+
+Adding a \bt_comp to a trace processing graph is also known as
+<em>instantiating a \bt_comp_cls</em> because the graph must first
+create the component from its class before adding it.
+
+Because component and component class C types are
+\ref api-fund-c-typing "highly specific", there are six functions
+to add a component to a trace processing graph:
+
+<dl>
+ <dt>Source component</dt>
+ <dd>
+ <dl>
+ <dt>Without initialization method data</dt>
+ <dd>bt_graph_add_source_component()</dd>
+
+ <dt>With initialization method data</dt>
+ <dd>bt_graph_add_source_component_with_initialize_method_data()</dd>
+ </dl>
+ </dd>
+
+ <dt>Filter component</dt>
+ <dd>
+ <dl>
+ <dt>Without initialization method data</dt>
+ <dd>bt_graph_add_filter_component()</dd>
+
+ <dt>With initialization method data</dt>
+ <dd>bt_graph_add_filter_component_with_initialize_method_data()</dd>
+ </dl>
+ </dd>
+
+ <dt>Sink component</dt>
+ <dd>
+ <dl>
+ <dt>Without initialization method data</dt>
+ <dd>bt_graph_add_sink_component()</dd>
+
+ <dt>With initialization method data</dt>
+ <dd>bt_graph_add_sink_component_with_initialize_method_data()</dd>
+ </dl>
+ </dd>
+</dl>
+
+The <code>*_with_initialize_method_data()</code> versions can pass a
+custom, \bt_voidp pointer to the component's
+\ref api-comp-cls-dev-meth-init "initialization method".
+The other versions pass \c NULL as this parameter.
+
+All the functions above accept the same parameters:
+
+@param[in] graph
+ Trace processing graph to which to add the created component.
+@param[in] component_class
+ Class to instantiate within \bt_p{graph}.
+@param[in] name
+ Unique name of the component to add within \bt_p{graph}.
+@param[in] params
+ Initialization parameters to use when creating the component.
+@param[in] logging_level
+ Initial logging level of the component to create.
+@param[out] component
+ <strong>On success</strong>, \bt_p{*component} is the created
+ component.
+
+Once you have the created and added component (\bt_p{*component}),
+you can borrow its \bt_p_port to
+\ref api-graph-lc-connect "connect them".
+
+You can add as many components as needed to a trace processing graph,
+but they must all have a unique name.
+
+<h3>\anchor api-graph-lc-add-ss Add a simple sink component</h3>
+
+To add a very basic \bt_sink_comp which has a single \bt_iport and
+creates a single \bt_msg_iter when the trace processing graph becomes
+configured, use bt_graph_add_simple_sink_component(). When you call
+this function, you pass three user functions:
+
+<dl>
+ <dt>\bt_dt_opt Initialization</dt>
+ <dd>
+ Called when the trace processing graph becomes
+ configured and when the sink component created its single
+ message iterator.
+
+ You can do an initial action with the message iterator such as
+ making it seek a specific point in time or getting messages.
+ </dd>
+
+ <dt>Consume</dt>
+ <dd>
+ Called every time the sink component's
+ \ref api-comp-cls-dev-meth-consume "consuming method" is called.
+
+ You can get the next messages from the component's message
+ iterator and process them.
+ </dd>
+
+ <dt>\bt_dt_opt Finalization</dt>
+ <dd>
+ Called when the sink component is finalized.
+ </dd>
+</dl>
+
+The three functions above receive, as their last parameter, the user
+data you passed to bt_graph_add_simple_sink_component() .
+
+<h2>\anchor api-graph-lc-connect Connect component ports</h2>
+
+When you \ref api-graph-lc-add "add a component" to a trace processing
+graph with one of the <code>bt_graph_add_*_component*()</code>
+functions, the function sets \bt_p{*component} to the
+created and added component.
+
+With such a \bt_comp, you can borrow one of its \bt_p_port by index or
+by name.
+
+Connect two component ports within a trace processing graph with
+bt_graph_connect_ports().
+
+After you connect component ports, you can still
+\ref api-graph-lc-add "add" more components to the graph, and then
+connect more ports.
+
+You don't need to connect all the available ports of a given component,
+depending on the trace processing task you need to perform. However,
+when you \ref api-graph-lc-run "run" the trace processing graph:
+
+- At least one \bt_oport of any \bt_src_comp must be connected.
+- At least one \bt_iport and one output port of any \bt_flt_comp must
+ be connected.
+- At least one input port of any \bt_sink_comp must be connected.
+
+<h2>\anchor api-graph-lc-run Run</h2>
+
+When you are done configuring a trace processing graph, you can run it
+with bt_graph_run().
+
+bt_graph_run() does \em not return until one of:
+
+- All the sink components are ended: bt_graph_run() returns
+ #BT_GRAPH_RUN_STATUS_OK.
+
+- One of the sink component returns an error:
+ bt_graph_run() returns #BT_GRAPH_RUN_STATUS_ERROR or
+ #BT_GRAPH_RUN_STATUS_MEMORY_ERROR.
+
+- One of the sink component returns "try again":
+ bt_graph_run() returns #BT_GRAPH_RUN_STATUS_AGAIN.
+
+ In that case, you can call bt_graph_run() again later, usually after
+ waiting for some time.
+
+ This feature exists to allow blocking operations within components
+ to be postponed until they don't block. The graph user can perform
+ other tasks instead of the graph's thread blocking.
+
+- The trace processing graph is interrupted (see
+ bt_graph_borrow_default_interrupter() and bt_graph_add_interrupter()):
+ bt_graph_run() returns #BT_GRAPH_RUN_STATUS_AGAIN.
+
+ Check the \bt_intr's state with bt_interrupter_is_set() to
+ distinguish between a sink component returning "try again" and
+ the trace processing graph getting interrupted.
+
+If you want to make a single sink component consume and process a few
+\bt_p_msg before controlling the thread again, use bt_graph_run_once()
+instead of bt_graph_run().
+
+<h1>Standard \bt_name component classes</h1>
+
+The \bt_name project ships with project \bt_p_plugin which provide
+"standard" \bt_p_comp_cls.
+
+Those standard component classes can be useful in many trace processing
+graph topologies. They are:
+
+<dl>
+ <dt>\c ctf plugin</dt>
+ <dd>
+ <dl>
+ <dt>\c fs source component class</dt>
+ <dd>
+ Opens a
+ <a href="https://diamon.org/ctf/">CTF</a> trace on the file
+ system and emits the \bt_p_msg of their data stream files.
+
+ See \bt_man{babeltrace2-source.ctf.fs,7}.
+ </dd>
+
+ <dt>\c lttng-live source component class</dt>
+ <dd>
+ Connects to an <a href="https://lttng.org/">LTTng</a> relay
+ daemon and emits the messages of the received CTF data streams.