Move to kernel style SPDX license identifiers
[babeltrace.git] / include / babeltrace2 / graph / graph.h
CommitLineData
c0418dd9 1/*
0235b0db 2 * SPDX-License-Identifier: MIT
c0418dd9 3 *
0235b0db 4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
c0418dd9
JG
5 */
6
0235b0db
MJ
7#ifndef BABELTRACE2_GRAPH_GRAPH_H
8#define BABELTRACE2_GRAPH_GRAPH_H
9
4fa90f32
PP
10#ifndef __BT_IN_BABELTRACE_H
11# error "Please include <babeltrace2/babeltrace.h> instead."
12#endif
13
3fadfbc0 14#include <babeltrace2/types.h>
e874da19
PP
15#include <babeltrace2/logging.h>
16
c0418dd9
JG
17#ifdef __cplusplus
18extern "C" {
19#endif
20
43c59509
PP
21/*!
22@defgroup api-graph Graph
8cc56726 23
43c59509
PP
24@brief
25 Trace processing graph.
0d72b8c3 26
43c59509
PP
27A <strong><em>trace processing graph</em></strong> is a specialized
28<a href="https://en.wikipedia.org/wiki/Filter_graph">filter graph</a>
29to manipulate one or more traces.
0d72b8c3 30
43c59509
PP
31Whereas the nodes of a multimedia filter graph typically exchange
32video frames and audio samples, the nodes, or \bt_p_comp, of a trace
33processing graph exchange immutable \bt_p_msg containing trace data.
0d72b8c3 34
43c59509
PP
35The following illustration shows a basic trace processing graph which
36converts many traces to a single log of pretty-printed lines:
0d72b8c3 37
43c59509 38@image html basic-convert-graph.png "Basic trace processing graph (conversion graph)."
0d72b8c3 39
43c59509 40In the illustrations above, notice that:
0d72b8c3 41
43c59509 42- The graph (blue) contains five components.
9c0a126a 43
43c59509
PP
44- Three source components (green) are connected to a single filter
45 component (yellow).
0d72b8c3 46
43c59509
PP
47 There are five \bt_p_conn, from five \bt_p_oport
48 to five \bt_p_iport.
21a9f056 49
43c59509 50- The filter component is connected to a single sink component (red).
078033ed 51
43c59509 52 There's a single connection.
078033ed 53
43c59509
PP
54- Source components read external resources while the sink component
55 writes to the standard output or to a file.
56
57- There are two source components having the same
58 \ref api-tir-comp-cls "class": <code>source.ctf.fs</code>.
59
60- All components are instances of \bt_plugin-provided classes:
61 <code>babeltrace2-plugin-ctf.so</code>,
62 <code>user-plugin.so</code>,
63 <code>babeltrace2-plugin-utils.so</code>, and
64 <code>babeltrace2-plugin-text.so</code>.
65
66Of course the topology can be much more complex if needed:
67
68@image html complex-graph.png "Complex trace processing graph."
69
70In a trace processing graph, \bt_p_comp are instances of \bt_p_comp_cls.
71
72A \bt_plugin can provide a component class, but you can also create one
73dynamically (see \ref api-comp-cls-dev).
74
75The connections between component ports in a trace processing graph
76indicate the needed topology to achieve a trace processing task. That
77being said,
78\bt_p_msg do not flow within connections. Instead, a source-to-sink
79or filter-to-sink connection makes it
80possible for a sink component to create a \bt_msg_iter on its end of
81the connection (an \bt_iport). In turn, a filter component message
82iterator can create other message iterators on one or more of the
83component's input ports. For a single connection, there can exist
84multiple message iterators.
85
86A trace processing graph is a
87\ref api-fund-shared-object "shared object": get a new reference with
88bt_graph_get_ref() and put an existing reference with
89bt_graph_put_ref().
90
91The type of a trace processing graph is #bt_graph.
92
93Create a default trace processing graph with bt_graph_create(). You need
94to pass a \bt_mip (MIP) version number when you call this function.
95Then, see
96\ref api-graph-lc "Trace processing graph life cycle"
97to learn how to add components to the graph, connect their ports, and
98run it.
99
100To interrupt a \ref api-graph-lc-run "running" trace processing graph,
101either:
102
103- Borrow the graph's default \bt_intr with
104 bt_graph_borrow_default_interrupter() and set it with
105 bt_interrupter_set().
106
107 When you call bt_graph_create(), the returned trace processing
108 graph has a default interrupter.
109
110- Add your own interrupter with bt_graph_add_interrupter() \em before
111 you run the graph with bt_graph_run() or bt_graph_run_once().
112
113 Then, set the interrupter with bt_interrupter_set().
114
115<h1>\anchor api-graph-lc Trace processing graph life cycle</h1>
116
117The following diagram shows the life cycle of a trace processing
118graph:
119
120@image html graph-lifetime.png "Trace processing graph lifecycle."
121
122After you create a default (empty) trace processing graph with
123bt_graph_create(), there are three steps to make the trace processing
124task execute:
125
126-# \ref api-graph-lc-add "Add components" to the graph.
127-# \ref api-graph-lc-connect "Connect component ports".
128-# \ref api-graph-lc-run "Run the graph".
129
130You can repeat steps 1 and 2 before step 3, as connecting a
131component \bt_port can make this \bt_comp create a new port:
132you might want to add a component in reaction to this event
133(see \ref api-graph-listeners "Listeners").
134
135Steps 1 and 2 constitute the \em configuration phase of the trace
136processing graph. The first time you call bt_graph_run() or
137bt_graph_run_once() for a given graph (step&nbsp;3), the graph becomes
138<em>configured</em>, and it notifies the sink components as such so that
139they can create their \bt_p_msg_iter.
140
141Once a trace processing graph becomes configured:
142
143- You cannot \ref api-graph-lc-add "add a component" to it.
144
145- You cannot \ref api-graph-lc-connect "connect component ports".
146
147- Components cannot add ports.
148
149In general, as of \bt_name_version_min_maj:
150
151- You cannot remove a component from a trace processing graph.
152
153- You cannot end (remove) a port \bt_conn.
154
155- Components cannot remove ports.
156
157If \em any error occurs (a function returns a status code which ends
158with <code>ERROR</code>) during step 1 or 2, the trace processing
159graph is considered <strong>faulty</strong>: you cannot use it anymore.
160The only functions you can call with a faulty graph are
161bt_graph_get_ref() and bt_graph_put_ref().
162
163<h2>\anchor api-graph-lc-add Add components</h2>
164
165Adding a \bt_comp to a trace processing graph is also known as
166<em>instantiating a \bt_comp_cls</em> because the graph must first
167create the component from its class before adding it.
168
169Because component and component class C&nbsp;types are
170\ref api-fund-c-typing "highly specific", there are six functions
171to add a component to a trace processing graph:
172
173<dl>
174 <dt>Source component</dt>
175 <dd>
176 <dl>
177 <dt>Without initialization method data</dt>
178 <dd>bt_graph_add_source_component()</dd>
179
180 <dt>With initialization method data</dt>
181 <dd>bt_graph_add_source_component_with_initialize_method_data()</dd>
182 </dl>
183 </dd>
184
185 <dt>Filter component</dt>
186 <dd>
187 <dl>
188 <dt>Without initialization method data</dt>
189 <dd>bt_graph_add_filter_component()</dd>
190
191 <dt>With initialization method data</dt>
192 <dd>bt_graph_add_filter_component_with_initialize_method_data()</dd>
193 </dl>
194 </dd>
195
196 <dt>Sink component</dt>
197 <dd>
198 <dl>
199 <dt>Without initialization method data</dt>
200 <dd>bt_graph_add_sink_component()</dd>
201
202 <dt>With initialization method data</dt>
203 <dd>bt_graph_add_sink_component_with_initialize_method_data()</dd>
204 </dl>
205 </dd>
206</dl>
207
208The <code>*_with_initialize_method_data()</code> versions can pass a
209custom, \bt_voidp pointer to the component's
210\ref api-comp-cls-dev-meth-init "initialization method".
211The other versions pass \c NULL as this parameter.
212
213All the functions above accept the same parameters:
214
215@param[in] graph
216 Trace processing graph to which to add the created component.
217@param[in] component_class
218 Class to instantiate within \bt_p{graph}.
219@param[in] name
220 Unique name of the component to add within \bt_p{graph}.
221@param[in] params
222 Initialization parameters to use when creating the component.
223@param[in] logging_level
224 Initial logging level of the component to create.
225@param[out] component
226 <strong>On success</strong>, \bt_p{*component} is the created
227 component.
228
229Once you have the created and added component (\bt_p{*component}),
230you can borrow its \bt_p_port to
231\ref api-graph-lc-connect "connect them".
232
233You can add as many components as needed to a trace processing graph,
234but they must all have a unique name.
235
236<h3>\anchor api-graph-lc-add-ss Add a simple sink component</h3>
237
238To add a very basic \bt_sink_comp which has a single \bt_iport and
239creates a single \bt_msg_iter when the trace processing graph becomes
240configured, use bt_graph_add_simple_sink_component(). When you call
241this function, you pass three user functions:
242
243<dl>
244 <dt>\bt_dt_opt Initialization</dt>
245 <dd>
246 Called when the trace processing graph becomes
247 configured and when the sink component created its single
248 message iterator.
249
250 You can do an initial action with the message iterator such as
251 making it seek a specific point in time or getting messages.
252 </dd>
253
254 <dt>Consume</dt>
255 <dd>
256 Called every time the sink component's
257 \ref api-comp-cls-dev-meth-consume "consuming method" is called.
258
259 You can get the next messages from the component's message
260 iterator and process them.
261 </dd>
262
263 <dt>\bt_dt_opt Finalization</dt>
264 <dd>
265 Called when the sink component is finalized.
266 </dd>
267</dl>
268
269The three functions above receive, as their last parameter, the user
270data you passed to bt_graph_add_simple_sink_component() .
271
272<h2>\anchor api-graph-lc-connect Connect component ports</h2>
273
274When you \ref api-graph-lc-add "add a component" to a trace processing
275graph with one of the <code>bt_graph_add_*_component*()</code>
276functions, the function sets \bt_p{*component} to the
277created and added component.
278
279With such a \bt_comp, you can borrow one of its \bt_p_port by index or
280by name.
281
282Connect two component ports within a trace processing graph with
283bt_graph_connect_ports().
284
285After you connect component ports, you can still
286\ref api-graph-lc-add "add" more components to the graph, and then
287connect more ports.
288
289You don't need to connect all the available ports of a given component,
290depending on the trace processing task you need to perform. However,
291when you \ref api-graph-lc-run "run" the trace processing graph:
292
293- At least one \bt_oport of any \bt_src_comp must be connected.
294- At least one \bt_iport and one output port of any \bt_flt_comp must
295 be connected.
296- At least one input port of any \bt_sink_comp must be connected.
297
298<h2>\anchor api-graph-lc-run Run</h2>
299
300When you are done configuring a trace processing graph, you can run it
301with bt_graph_run().
302
303bt_graph_run() does \em not return until one of:
304
305- All the sink components are ended: bt_graph_run() returns
306 #BT_GRAPH_RUN_STATUS_OK.
307
308- One of the sink component returns an error:
309 bt_graph_run() returns #BT_GRAPH_RUN_STATUS_ERROR or
310 #BT_GRAPH_RUN_STATUS_MEMORY_ERROR.
311
312- One of the sink component returns "try again":
313 bt_graph_run() returns #BT_GRAPH_RUN_STATUS_AGAIN.
314
315 In that case, you can call bt_graph_run() again later, usually after
316 waiting for some time.
317
318 This feature exists to allow blocking operations within components
319 to be postponed until they don't block. The graph user can perform
320 other tasks instead of the graph's thread blocking.
321
322- The trace processing graph is interrupted (see
323 bt_graph_borrow_default_interrupter() and bt_graph_add_interrupter()):
324 bt_graph_run() returns #BT_GRAPH_RUN_STATUS_AGAIN.
325
326 Check the \bt_intr's state with bt_interrupter_is_set() to
327 distinguish between a sink component returning "try again" and
328 the trace processing graph getting interrupted.
329
330If you want to make a single sink component consume and process a few
331\bt_p_msg before controlling the thread again, use bt_graph_run_once()
332instead of bt_graph_run().
333
334<h1>Standard \bt_name component classes</h1>
078033ed 335
43c59509
PP
336The \bt_name project ships with project \bt_p_plugin which provide
337"standard" \bt_p_comp_cls.
078033ed 338
43c59509
PP
339Those standard component classes can be useful in many trace processing
340graph topologies. They are:
341
342<dl>
343 <dt>\c ctf plugin</dt>
344 <dd>
345 <dl>
346 <dt>\c fs source component class</dt>
347 <dd>
348 Opens a
349 <a href="https://diamon.org/ctf/">CTF</a> trace on the file
350 system and emits the \bt_p_msg of their data stream files.
351
352 See \bt_man{babeltrace2-source.ctf.fs,7}.
353 </dd>
354
355 <dt>\c lttng-live source component class</dt>
356 <dd>
357 Connects to an <a href="https://lttng.org/">LTTng</a> relay
358 daemon and emits the messages of the received CTF data streams.
359
360 See \bt_man{babeltrace2-source.ctf.lttng-live,7}.
361 </dd>
362
363 <dt>\c fs sink component class</dt>
364 <dd>
365 Writes the consumed messages as one or more CTF traces on the
366 file system.
367
368 See \bt_man{babeltrace2-sink.ctf.fs,7}.
369 </dd>
370 </dl>
371 </dd>
372
373 <dt>\c lttng-utils plugin</dt>
374 <dd>
375 <dl>
376 <dt>\c debug-info filter component class</dt>
377 <dd>
378 Adds debugging information to compatible LTTng event messages.
379
380 This component class is only available if the project was
381 built with the <code>\-\-enable-debug-info</code>
382 configuration option.
383
384 See \bt_man{babeltrace2-filter.lttng-utils.debug-info,7}.
385 </dd>
386 </dl>
387 </dd>
388
389 <dt>\c text plugin</dt>
390 <dd>
391 <dl>
392 <dt>\c dmesg source component class</dt>
393 <dd>
394 Reads the lines of a Linux kernel ring buffer, that is, the
395 output of the
396 <a href="http://man7.org/linux/man-pages/man1/dmesg.1.html"><code>dmesg</code></a>
397 tool, and emits each line as an \bt_ev_msg.
398
399 See \bt_man{babeltrace2-source.text.dmesg,7}.
400 </dd>
401
402 <dt>\c details sink component class</dt>
403 <dd>
404 Deterministically prints the messages it consumes with details
405 to the standard output.
406
407 See \bt_man{babeltrace2-sink.text.details,7}.
408 </dd>
409
410 <dt>\c pretty sink component class</dt>
411 <dd>
412 Pretty-prints the messages it consumes to the standard output or
413 to a file.
414
415 This is equivalent to the \c text output format of the
ceb29cf8 416 <a href="https://manpages.debian.org/stretch/babeltrace/babeltrace.1.en.html">Babeltrace&nbsp;1
43c59509
PP
417 command-line tool</a>.
418
419 See \bt_man{babeltrace2-sink.text.pretty,7}.
420 </dd>
421 </dl>
422 </dd>
423
424 <dt>\c utils plugin</dt>
425 <dd>
426 <dl>
427 <dt>\c muxer filter component class</dt>
428 <dd>
429 Muxes messages by time.
430
431 See \bt_man{babeltrace2-filter.utils.muxer,7}.
432 </dd>
433
434 <dt>\c trimmer filter component class</dt>
435 <dd>
436 Discards all the consumed messages with a time outside a given
437 time range, effectively "cutting" \bt_p_stream.
438
439 See \bt_man{babeltrace2-filter.utils.trimmer,7}.
440 </dd>
441
442 <dt>\c counter sink component class</dt>
443 <dd>
444 Prints the number of consumed messages, either once at the end
445 or periodically, to the standard output.
446
447 See \bt_man{babeltrace2-sink.utils.counter,7}.
448 </dd>
449
450 <dt>\c dummy sink component class</dt>
451 <dd>
452 Consumes messages and discards them (does nothing with them).
453
454 This is useful for testing and benchmarking a trace processing
455 graph application, for example.
456
457 See \bt_man{babeltrace2-sink.utils.dummy,7}.
458 </dd>
459 </dl>
460 </dd>
461</dl>
462
463To access such a component class, get its plugin by name with
464bt_plugin_find() and then borrow the component class by name
465with bt_plugin_borrow_source_component_class_by_name_const(),
466bt_plugin_borrow_filter_component_class_by_name_const(), or
467bt_plugin_borrow_sink_component_class_by_name_const().
468
469For example:
470
471@code
472const bt_plugin *plugin;
473
474if (bt_plugin_find("utils", BT_TRUE, BT_TRUE, BT_TRUE, BT_TRUE, BT_TRUE,
475 &plugin) != BT_PLUGIN_FIND_STATUS_OK) {
476 // handle error
477}
478
479const bt_component_class_filter *muxer_component_class =
480 bt_plugin_borrow_filter_component_class_by_name_const(plugin, "muxer");
481
482if (!muxer_component_class) {
483 // handle error
484}
485@endcode
486
487<h1>\anchor api-graph-listeners Listeners</h1>
488
489A \bt_comp can add a \bt_port:
490
491- At initialization time, that is, when you call one of the
492 <code>bt_graph_add_*_component*()</code> functions.
493
494- When one of its ports gets connected, that is, when you call
495 bt_graph_connect_ports().
496
497To get notified when any component of a given trace processing
498graph adds a port, add one or more "port
499added" listeners to the graph with:
500
501- bt_graph_add_source_component_output_port_added_listener()
502- bt_graph_add_filter_component_input_port_added_listener()
503- bt_graph_add_filter_component_output_port_added_listener()
504- bt_graph_add_sink_component_input_port_added_listener()
505
506Within a "port added" listener function, you can
507\ref api-graph-lc-add "add more components"
508and \ref api-graph-lc-connect "connect more component ports".
509*/
510
511/*! @{ */
512
513/*!
514@name Type
515@{
516
517@typedef struct bt_graph bt_graph;
518
519@brief
520 Trace processing graph.
521
522@}
523*/
524
525/*!
526@name Creation
527@{
528*/
529
530/*!
531@brief
532 Creates a default, empty trace processing graph honouring version
533 \bt_p{mip_version} of the \bt_mip.
534
535On success, the returned graph contains no components (see
536\ref api-graph-lc-add "Add components").
537
538The graph is configured as operating following version
539\bt_p{mip_version} of the Message Interchange Protocol, so that
540bt_self_component_get_graph_mip_version() returns this version when
541components call it.
542
543@note
544 As of \bt_name_version_min_maj, the only available MIP version is 0.
545
546The returned graph has a default \bt_intr. Any \bt_comp you add with the
547<code>bt_graph_add_*_component*()</code> functions and all their
548\bt_p_msg_iter also have this same default interrupter. Borrow the graph's
549default interrupter with bt_graph_borrow_default_interrupter().
550
551@param[in] mip_version
552 Version of the Message Interchange Protocol to use within the
553 graph to create.
554
555@returns
556 New trace processing graph reference, or \c NULL on memory error.
557
558@pre
559 \bt_p{mip_version} is 0.
560*/
056deb59 561extern bt_graph *bt_graph_create(uint64_t mip_version);
0d72b8c3 562
43c59509
PP
563/*! @} */
564
565/*!
566@name Component adding
567@{
568*/
569
570/*!
571@brief
572 Status codes for the
573 <code>bt_graph_add_*_component*()</code> functions.
574*/
d24d5663 575typedef enum bt_graph_add_component_status {
43c59509
PP
576 /*!
577 @brief
578 Success.
579 */
d24d5663 580 BT_GRAPH_ADD_COMPONENT_STATUS_OK = __BT_FUNC_STATUS_OK,
43c59509
PP
581
582 /*!
583 @brief
584 Out of memory.
585 */
d24d5663 586 BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
43c59509
PP
587
588 /*!
589 @brief
590 Other error.
591 */
592 BT_GRAPH_ADD_COMPONENT_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
d24d5663
PP
593} bt_graph_add_component_status;
594
43c59509
PP
595/*!
596@brief
597 Alias of bt_graph_add_source_component_with_initialize_method_data()
598 with the \bt_p{initialize_method_data} parameter set to \c NULL.
599*/
d24d5663
PP
600extern bt_graph_add_component_status
601bt_graph_add_source_component(bt_graph *graph,
b19ff26f
PP
602 const bt_component_class_source *component_class,
603 const char *name, const bt_value *params,
43c59509
PP
604 bt_logging_level logging_level,
605 const bt_component_source **component);
606
607/*!
608@brief
609 Creates a \bt_src_comp from the
610 \ref api-tir-comp-cls "class" \bt_p{component_class}
611 with the initialization parameters \bt_p{params}, the initialization
612 user data \bt_p{initialize_method_data}, and the initial
613 logging level \bt_p{logging_level}, adds it to the trace processing
614 graph \bt_p{graph} with the name \bt_p{name}, and sets
615 \bt_p{*component} to the resulting component.
616
617See \ref api-graph-lc-add "Add components" to learn more about adding
618components to a trace processing graph.
619
620This function calls the source component's
621\ref api-comp-cls-dev-meth-init "initialization method" after
622creating it.
623
624The created source component's initialization method receives:
625
626- \bt_p{params} as its own \bt_p{params} parameter (or an empty
627 \bt_map_val if \bt_p{params} is \c NULL).
628
629- \bt_p{initialize_method_data} as its own \bt_p{initialize_method_data}
630 parameter.
631
632The created source component can get its logging level
633(\bt_p{logging_level}) with bt_component_get_logging_level().
634
635@param[in] graph
636 Trace processing graph to which to add the created source component.
637@param[in] component_class
638 Class to instantiate within \bt_p{graph}.
639@param[in] name
640 Unique name, within \bt_p{graph}, of the component to create.
641@param[in] params
642 @parblock
643 Initialization parameters to use when creating the source component.
644
645 Can be \c NULL, in which case the created source component's
646 initialization method receives an empty \bt_map_val as its
647 \bt_p{params} parameter.
648 @endparblock
649@param[in] initialize_method_data
650 User data passed as is to the created source component's
651 initialization method.
652@param[in] logging_level
653 Initial logging level of the source component to create.
654@param[out] component
655 <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
656 a \em borrowed reference of the created source component.
657
658@retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
659 Success.
660@retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
661 Out of memory.
662@retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
663 Other error, for example, the created source component's
664 initialization method failed.
665
666@bt_pre_not_null{graph}
667@bt_pre_graph_not_configured{graph}
668@bt_pre_graph_not_faulty{graph}
669@bt_pre_not_null{component_class}
670@bt_pre_not_null{name}
671@pre
672 No other component within \bt_p{graph} has the name \bt_p{name}.
673@pre
674 \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
675 or is \c NULL.
0d72b8c3 676
43c59509
PP
677@bt_post_success_frozen{component_class}
678@bt_post_success_frozen{params}
679*/
d24d5663 680extern bt_graph_add_component_status
21a9f056 681bt_graph_add_source_component_with_initialize_method_data(
b19ff26f
PP
682 bt_graph *graph,
683 const bt_component_class_source *component_class,
684 const char *name, const bt_value *params,
43c59509 685 void *initialize_method_data, bt_logging_level logging_level,
b19ff26f 686 const bt_component_source **component);
0d72b8c3 687
43c59509
PP
688/*!
689@brief
690 Alias of bt_graph_add_filter_component_with_initialize_method_data()
691 with the \bt_p{initialize_method_data} parameter set to \c NULL.
692*/
d24d5663
PP
693extern bt_graph_add_component_status
694bt_graph_add_filter_component(bt_graph *graph,
b19ff26f
PP
695 const bt_component_class_filter *component_class,
696 const char *name, const bt_value *params,
43c59509 697 bt_logging_level logging_level,
b19ff26f 698 const bt_component_filter **component);
0d72b8c3 699
43c59509
PP
700/*!
701@brief
702 Creates a \bt_flt_comp from the
703 \ref api-tir-comp-cls "class" \bt_p{component_class}
704 with the initialization parameters \bt_p{params}, the initialization
705 user data \bt_p{initialize_method_data}, and the initial
706 logging level \bt_p{logging_level}, adds it to the trace processing
707 graph \bt_p{graph} with the name \bt_p{name}, and sets
708 \bt_p{*component} to the resulting component.
709
710See \ref api-graph-lc-add "Add components" to learn more about adding
711components to a trace processing graph.
712
713This function calls the filter component's
714\ref api-comp-cls-dev-meth-init "initialization method" after
715creating it.
716
717The created filter component's initialization method receives:
718
719- \bt_p{params} as its own \bt_p{params} parameter (or an empty
720 \bt_map_val if \bt_p{params} is \c NULL).
721
722- \bt_p{initialize_method_data} as its own \bt_p{initialize_method_data}
723 parameter.
724
725The created filter component can get its logging level
726(\bt_p{logging_level}) with bt_component_get_logging_level().
727
728@param[in] graph
729 Trace processing graph to which to add the created filter component.
730@param[in] component_class
731 Class to instantiate within \bt_p{graph}.
732@param[in] name
733 Unique name, within \bt_p{graph}, of the component to create.
734@param[in] params
735 @parblock
736 Initialization parameters to use when creating the filter component.
737
738 Can be \c NULL, in which case the created filter component's
739 initialization method receives an empty \bt_map_val as its
740 \bt_p{params} parameter.
741 @endparblock
742@param[in] initialize_method_data
743 User data passed as is to the created filter component's
744 initialization method.
745@param[in] logging_level
746 Initial logging level of the filter component to create.
747@param[out] component
748 <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
749 a \em borrowed reference of the created filter component.
750
751@retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
752 Success.
753@retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
754 Out of memory.
755@retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
756 Other error, for example, the created filter component's
757 initialization method failed.
758
759@bt_pre_not_null{graph}
760@bt_pre_graph_not_configured{graph}
761@bt_pre_graph_not_faulty{graph}
762@bt_pre_not_null{component_class}
763@bt_pre_not_null{name}
764@pre
765 No other component within \bt_p{graph} has the name \bt_p{name}.
766@pre
767 \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
768 or is \c NULL.
769
770@bt_post_success_frozen{component_class}
771@bt_post_success_frozen{params}
772*/
d24d5663 773extern bt_graph_add_component_status
21a9f056 774bt_graph_add_filter_component_with_initialize_method_data(
b19ff26f
PP
775 bt_graph *graph,
776 const bt_component_class_filter *component_class,
777 const char *name, const bt_value *params,
43c59509 778 void *initialize_method_data, bt_logging_level logging_level,
b19ff26f 779 const bt_component_filter **component);
0d72b8c3 780
43c59509
PP
781/*!
782@brief
783 Alias of bt_graph_add_sink_component_with_initialize_method_data()
784 with the \bt_p{initialize_method_data} parameter set to \c NULL.
785*/
d24d5663
PP
786extern bt_graph_add_component_status
787bt_graph_add_sink_component(
4cdfc5e8 788 bt_graph *graph, const bt_component_class_sink *component_class,
b19ff26f 789 const char *name, const bt_value *params,
43c59509 790 bt_logging_level logging_level,
b19ff26f 791 const bt_component_sink **component);
0d72b8c3 792
43c59509
PP
793/*!
794@brief
795 Creates a \bt_sink_comp from the
796 \ref api-tir-comp-cls "class" \bt_p{component_class}
797 with the initialization parameters \bt_p{params}, the initialization
798 user data \bt_p{initialize_method_data}, and the initial
799 logging level \bt_p{logging_level}, adds it to the trace processing
800 graph \bt_p{graph} with the name \bt_p{name}, and sets
801 \bt_p{*component} to the resulting component.
802
803See \ref api-graph-lc-add "Add components" to learn more about adding
804components to a trace processing graph.
805
806This function calls the sink component's
807\ref api-comp-cls-dev-meth-init "initialization method" after
808creating it.
809
810The created sink component's initialization method receives:
811
812- \bt_p{params} as its own \bt_p{params} parameter (or an empty
813 \bt_map_val if \bt_p{params} is \c NULL).
814
815- \bt_p{initialize_method_data} as its own \bt_p{initialize_method_data}
816 parameter.
817
818The created sink component can get its logging level
819(\bt_p{logging_level}) with bt_component_get_logging_level().
820
821@param[in] graph
822 Trace processing graph to which to add the created sink component.
823@param[in] component_class
824 Class to instantiate within \bt_p{graph}.
825@param[in] name
826 Unique name, within \bt_p{graph}, of the component to create.
827@param[in] params
828 @parblock
829 Initialization parameters to use when creating the sink component.
830
831 Can be \c NULL, in which case the created sink component's
832 initialization method receives an empty \bt_map_val as its
833 \bt_p{params} parameter.
834 @endparblock
835@param[in] initialize_method_data
836 User data passed as is to the created sink component's
837 initialization method.
838@param[in] logging_level
839 Initial logging level of the sink component to create.
840@param[out] component
841 <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
842 a \em borrowed reference of the created sink component.
843
844@retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
845 Success.
846@retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
847 Out of memory.
848@retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
849 Other error, for example, the created sink component's
850 initialization method failed.
851
852@bt_pre_not_null{graph}
853@bt_pre_graph_not_configured{graph}
854@bt_pre_graph_not_faulty{graph}
855@bt_pre_not_null{component_class}
856@bt_pre_not_null{name}
857@pre
858 No other component within \bt_p{graph} has the name \bt_p{name}.
859@pre
860 \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
861 or is \c NULL.
862
863@bt_post_success_frozen{component_class}
864@bt_post_success_frozen{params}
865*/
d24d5663 866extern bt_graph_add_component_status
21a9f056 867bt_graph_add_sink_component_with_initialize_method_data(
4cdfc5e8 868 bt_graph *graph, const bt_component_class_sink *component_class,
b19ff26f 869 const char *name, const bt_value *params,
43c59509 870 void *initialize_method_data, bt_logging_level logging_level,
b19ff26f 871 const bt_component_sink **component);
0d72b8c3 872
43c59509
PP
873/*! @} */
874
875/*!
876@name Simple sink component adding
877@{
878*/
879
880/*!
881@brief
882 Status codes for the #bt_graph_simple_sink_component_initialize_func
883 type.
884*/
885typedef enum bt_graph_simple_sink_component_initialize_func_status {
886 /*!
887 @brief
888 Success.
889 */
890 BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_OK = __BT_FUNC_STATUS_OK,
891
892 /*!
893 @brief
894 Out of memory.
895 */
896 BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
897
898 /*!
899 @brief
900 Other error.
901 */
902 BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
903} bt_graph_simple_sink_component_initialize_func_status;
904
905/*!
906@brief
907 User initialization function for
908 bt_graph_add_simple_sink_component().
909
910Such an initialization function is called when the trace processing
911graph becomes configured and when the simple sink component has created
912its single \bt_msg_iter. This occurs the first time you call
913bt_graph_run() or bt_graph_run_once() on the trace processing graph.
914
915See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
916about adding a simple component to a trace processing graph.
917
918@param[in] message_iterator
919 @parblock
920 Simple sink component's upstream message iterator.
921
922 This user function is free to get the message iterator's next
923 message or to make it seek.
924 @endparblock
925@param[in] user_data
926 User data, as passed as the \bt_p{user_data} parameter of
927 bt_graph_add_simple_sink_component().
928
929@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_OK
930 Success.
931@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_MEMORY_ERROR
932 Out of memory.
933@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_ERROR
934 Other error.
935
936@bt_pre_not_null{message_iterator}
937
938@post
939 The reference count of \bt_p{message_iterator} is not changed.
940
941@sa bt_graph_add_simple_sink_component() &mdash;
942 Creates and adds a simple sink component to a trace processing
943 graph.
944*/
945typedef bt_graph_simple_sink_component_initialize_func_status
946(*bt_graph_simple_sink_component_initialize_func)(
947 bt_message_iterator *message_iterator,
948 void *user_data);
949
950/*!
951@brief
952 Status codes for the #bt_graph_simple_sink_component_consume_func
953 type.
954*/
955typedef enum bt_graph_simple_sink_component_consume_func_status {
956 /*!
957 @brief
958 Success.
959 */
960 BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK = __BT_FUNC_STATUS_OK,
961
962 /*!
963 @brief
964 End of processing.
965 */
966 BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END = __BT_FUNC_STATUS_END,
967
968 /*!
969 @brief
970 Try again.
971 */
972 BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
973
974 /*!
975 @brief
976 Out of memory.
977 */
978 BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
979
980 /*!
981 @brief
982 Other error.
983 */
984 BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
985} bt_graph_simple_sink_component_consume_func_status;
986
987/*!
988@brief
989 User consuming function for bt_graph_add_simple_sink_component().
990
991Such a consuming function is called when the simple sink component's own
992\ref api-comp-cls-dev-meth-consume "consuming method" is called. This
993occurs in a loop within bt_graph_run() or when it's this sink
994component's turn to consume in
995bt_graph_run_once().
996
997See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
998about adding a simple component to a trace processing graph.
999
1000If you are not done consuming messages, return
1001#BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK.
1002
1003If you are done consuming messages, return
1004#BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END.
1005
1006If you wish to avoid a blocking operation and make
1007bt_graph_run() or bt_graph_run_once() aware, return
1008#BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN.
1009
1010@param[in] message_iterator
1011 @parblock
1012 Simple sink component's upstream message iterator.
1013
1014 This user function is free to get the message iterator's next
1015 message or to make it seek.
1016 @endparblock
1017@param[in] user_data
1018 User data, as passed as the \bt_p{user_data} parameter of
1019 bt_graph_add_simple_sink_component().
1020
1021@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK
1022 Success.
1023@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END
1024 End of processing.
1025@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN
1026 Try again.
1027@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_MEMORY_ERROR
1028 Out of memory.
1029@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_ERROR
1030 Other error.
1031
1032@bt_pre_not_null{message_iterator}
1033
1034@post
1035 The reference count of \bt_p{message_iterator} is not changed.
1036
1037@sa bt_graph_add_simple_sink_component() &mdash;
1038 Creates and adds a simple sink component to a trace processing
1039 graph.
1040*/
1041typedef bt_graph_simple_sink_component_consume_func_status
1042(*bt_graph_simple_sink_component_consume_func)(
1043 bt_message_iterator *message_iterator,
1044 void *user_data);
1045
1046/*!
1047@brief
1048 User finalization function for bt_graph_add_simple_sink_component().
1049
1050Such a finalization function is called when the simple sink component
1051is finalized. This occurs when the trace processing graph is destroyed
1052(you put its last strong \ref api-fund-shared-object "reference"
1053with bt_graph_put_ref()).
1054
1055See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
1056about adding a simple component to a trace processing graph.
1057
1058@param[in] user_data
1059 User data, as passed as the \bt_p{user_data} parameter of
1060 bt_graph_add_simple_sink_component().
1061
1062@bt_post_no_error
1063
1064@sa bt_graph_add_simple_sink_component() &mdash;
1065 Creates and adds a simple sink component to a trace processing
1066 graph.
1067*/
1068typedef void (*bt_graph_simple_sink_component_finalize_func)(void *user_data);
1069
1070/*!
1071@brief
1072 Creates a simple \bt_sink_comp, adds it to the trace processing
1073 graph \bt_p{graph} with the name \bt_p{name}, and sets
1074 \bt_p{*component} to the resulting component.
1075
1076See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
1077about adding a simple component to a trace processing graph.
1078
1079\bt_p{initialize_func} (if not \c NULL), \bt_p{consume_func},
1080and \bt_p{finalize_func} (if not \c NULL) receive \bt_p{user_data}
1081as their own \bt_p{user_data} parameter.
1082
1083@param[in] graph
1084 Trace processing graph to which to add the created simple sink
1085 component.
1086@param[in] name
1087 Unique name, within \bt_p{graph}, of the component to create.
1088@param[in] initialize_func
1089 @parblock
1090 User initialization function.
1091
1092 Can be \c NULL.
1093 @endparblock
1094@param[in] consume_func
1095 User consuming function.
1096@param[in] finalize_func
1097 @parblock
1098 User finalization function.
1099
1100 Can be \c NULL.
1101 @endparblock
1102@param[in] user_data
1103 User data to pass as the \bt_p{user_data} parameter of
1104 \bt_p{initialize_func}, \bt_p{consume_func}, and
1105 \bt_p{finalize_func}.
1106@param[out] component
1107 <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
1108 a \em borrowed reference of the created simple sink component.
1109
1110@retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
1111 Success.
1112@retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
1113 Out of memory.
1114@retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
1115 Other error, for example, the created sink component's
1116 \ref api-comp-cls-dev-meth-init "initialization method" failed.
1117
1118@bt_pre_not_null{graph}
1119@bt_pre_graph_not_configured{graph}
1120@bt_pre_graph_not_faulty{graph}
1121@bt_pre_not_null{name}
1122@pre
1123 No other component within \bt_p{graph} has the name \bt_p{name}.
1124@bt_pre_not_null{consume_func}
1125*/
078033ed
PP
1126extern bt_graph_add_component_status
1127bt_graph_add_simple_sink_component(bt_graph *graph, const char *name,
43c59509 1128 bt_graph_simple_sink_component_initialize_func initialize_func,
078033ed
PP
1129 bt_graph_simple_sink_component_consume_func consume_func,
1130 bt_graph_simple_sink_component_finalize_func finalize_func,
1131 void *user_data, const bt_component_sink **component);
1132
43c59509
PP
1133/*! @} */
1134
1135/*!
1136@name Component port connection
1137@{
1138*/
1139
1140/*!
1141@brief
1142 Status codes for bt_graph_connect_ports().
1143*/
d24d5663 1144typedef enum bt_graph_connect_ports_status {
43c59509
PP
1145 /*!
1146 @brief
1147 Success.
1148 */
d24d5663 1149 BT_GRAPH_CONNECT_PORTS_STATUS_OK = __BT_FUNC_STATUS_OK,
43c59509
PP
1150
1151 /*!
1152 @brief
1153 Out of memory.
1154 */
d24d5663 1155 BT_GRAPH_CONNECT_PORTS_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
43c59509
PP
1156
1157 /*!
1158 @brief
1159 Other error.
1160 */
1161 BT_GRAPH_CONNECT_PORTS_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
d24d5663
PP
1162} bt_graph_connect_ports_status;
1163
43c59509
PP
1164/*!
1165@brief
1166 Connects the \bt_oport \bt_p{upstream_port} to the \bt_iport
1167 \bt_p{downstream_port} within the trace processing graph
1168 \bt_p{graph}, and sets \bt_p{*connection} to the resulting
1169 \bt_conn.
1170
1171See \ref api-graph-lc-connect "Connect component ports" to learn more
1172about connecting ports within a trace processing graph.
1173
1174Both \bt_p{upstream_port} and \bt_p{downstream_port} must be
1175unconnected (bt_port_is_connected() returns #BT_FALSE) when you call
1176this function.
1177
1178@param[in] graph
1179 Trace processing graph containing the \bt_p_comp to which belong
1180 \bt_p{upstream_port} and \bt_p{downstream_port}.
1181@param[in] upstream_port
1182 \bt_c_oport to connect to \bt_p{downstream_port}.
1183@param[in] downstream_port
1184 \bt_c_iport to connect to \bt_p{upstream_port}.
1185@param[in] connection
1186 <strong>On success, if not \c NULL</strong>, \bt_p{*connection} is
1187 a \em borrowed reference of the resulting \bt_conn.
1188
1189@retval #BT_GRAPH_CONNECT_PORTS_STATUS_OK
1190 Success.
1191@retval #BT_GRAPH_CONNECT_PORTS_STATUS_MEMORY_ERROR
1192 Out of memory.
1193@retval #BT_GRAPH_CONNECT_PORTS_STATUS_ERROR
1194 Other error.
1195
1196@bt_pre_not_null{graph}
1197@bt_pre_graph_not_configured{graph}
1198@bt_pre_graph_not_faulty{graph}
1199@bt_pre_not_null{upstream_port}
1200@pre
1201 \bt_p{graph} contains the component of \bt_p{upstream_port},
1202 as returned by bt_port_borrow_component_const().
1203@pre
1204 \bt_p{upstream_port} is unconnected
1205 (bt_port_is_connected() returns #BT_FALSE).
1206@bt_pre_not_null{downstream_port}
1207@pre
1208 \bt_p{graph} contains the component of \bt_p{downstream_port},
1209 as returned by bt_port_borrow_component_const().
1210@pre
1211 \bt_p{downstream_port} is unconnected
1212 (bt_port_is_connected() returns #BT_FALSE).
1213@pre
1214 Connecting \bt_p{upstream_port} to \bt_p{downstream_port} does not
1215 form a connection cycle within \bt_p{graph}.
1216*/
d24d5663 1217extern bt_graph_connect_ports_status bt_graph_connect_ports(bt_graph *graph,
43c59509
PP
1218 const bt_port_output *upstream_port,
1219 const bt_port_input *downstream_port,
b19ff26f 1220 const bt_connection **connection);
0d72b8c3 1221
43c59509
PP
1222/*! @} */
1223
1224/*!
1225@name Running
1226@{
1227*/
1228
1229/*!
1230@brief
1231 Status codes for bt_graph_run().
1232*/
d24d5663 1233typedef enum bt_graph_run_status {
43c59509
PP
1234 /*!
1235 @brief
1236 Success.
1237 */
d24d5663 1238 BT_GRAPH_RUN_STATUS_OK = __BT_FUNC_STATUS_OK,
43c59509
PP
1239
1240 /*!
1241 @brief
1242 Try again.
1243 */
d24d5663 1244 BT_GRAPH_RUN_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
43c59509
PP
1245
1246 /*!
1247 @brief
1248 Out of memory.
1249 */
1250 BT_GRAPH_RUN_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
1251
1252 /*!
1253 @brief
1254 Other error.
1255 */
1256 BT_GRAPH_RUN_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
d24d5663
PP
1257} bt_graph_run_status;
1258
43c59509
PP
1259/*!
1260@brief
1261 Runs the trace processing graph \bt_p{graph}, calling each
1262 \bt_sink_comp's
1263 \ref api-comp-cls-dev-meth-consume "consuming method" in a round
1264 robin fashion until they are all done consuming or an exception
1265 occurs.
1266
1267See \ref api-graph-lc-run "Run" to learn more about running a trace
1268processing graph.
1269
1270This function does \em not return until one of:
1271
1272- All the sink components are ended, in which case this function
1273 returns #BT_GRAPH_RUN_STATUS_OK.
1274
1275- One of the sink component returns an error, in which case this
1276 function returns #BT_GRAPH_RUN_STATUS_ERROR or
1277 #BT_GRAPH_RUN_STATUS_MEMORY_ERROR.
1278
1279- One of the sink component returns "try again", in which case
1280 this function returns #BT_GRAPH_RUN_STATUS_AGAIN.
1281
1282 In that case, you can call this function again later, usually after
1283 waiting for some time.
1284
1285 This feature exists to allow blocking operations within components
1286 to be postponed until they don't block. The graph user can perform
1287 other tasks instead of the graph's thread blocking.
1288
1289- \bt_p{graph} is interrupted (see bt_graph_borrow_default_interrupter()
1290 and bt_graph_add_interrupter()), in which case this function returns
1291 #BT_GRAPH_RUN_STATUS_AGAIN.
1292
1293 Check the \bt_intr's state with bt_interrupter_is_set() to
1294 distinguish between a sink component returning "try again" and
1295 \bt_p{graph} getting interrupted.
1296
1297To make a single sink component consume, then get the thread's control
1298back, use bt_graph_run_once().
1299
1300When you call this function or bt_graph_run_once() for the first time,
1301\bt_p{graph} becomes <em>configured</em>. See
1302\ref api-graph-lc "Trace processing graph life cycle"
1303to learn what happens when a trace processing graph becomes configured,
1304and what you can and cannot do with a configured graph.
1305
1306@param[in] graph
1307 Trace processing graph to run.
1308
1309@retval #BT_GRAPH_RUN_STATUS_OK
1310 Success.
1311@retval #BT_GRAPH_RUN_STATUS_AGAIN
1312 Try again.
1313@retval #BT_GRAPH_RUN_STATUS_MEMORY_ERROR
1314 Out of memory.
1315@retval #BT_GRAPH_RUN_STATUS_ERROR
1316 Other error.
1317
1318@bt_pre_not_null{graph}
1319@bt_pre_graph_not_faulty{graph}
1320@pre
1321 For each \bt_src_comp within \bt_p{graph}, at least one \bt_oport
1322 is connected.
1323@pre
1324 For each \bt_flt_comp within \bt_p{graph}, at least one \bt_iport
1325 and one \bt_iport are connected.
1326@pre
1327 For each \bt_sink_comp within \bt_p{graph}, at least one \bt_iport
1328 is connected.
1329@pre
1330 \bt_p{graph} contains at least one sink component.
1331
1332@sa bt_graph_run_once() &mdash;
1333 Calls a single trace processing graph's sink component's consuming
1334 method once.
1335*/
d24d5663
PP
1336extern bt_graph_run_status bt_graph_run(bt_graph *graph);
1337
43c59509
PP
1338/*!
1339@brief
1340 Status codes for bt_graph_run().
1341*/
648dab91 1342typedef enum bt_graph_run_once_status {
43c59509
PP
1343 /*!
1344 @brief
1345 Success.
1346 */
648dab91 1347 BT_GRAPH_RUN_ONCE_STATUS_OK = __BT_FUNC_STATUS_OK,
43c59509
PP
1348
1349 /*!
1350 @brief
1351 All sink components are finished processing.
1352 */
648dab91 1353 BT_GRAPH_RUN_ONCE_STATUS_END = __BT_FUNC_STATUS_END,
43c59509
PP
1354
1355 /*!
1356 @brief
1357 Try again.
1358 */
1359 BT_GRAPH_RUN_ONCE_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
1360
1361 /*!
1362 @brief
1363 Out of memory.
1364 */
1365 BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
1366
1367 /*!
1368 @brief
1369 Other error.
1370 */
1371 BT_GRAPH_RUN_ONCE_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
648dab91
PP
1372} bt_graph_run_once_status;
1373
43c59509
PP
1374/*!
1375@brief
1376 Calls the \ref api-comp-cls-dev-meth-consume "consuming method" of
1377 the next non-ended \bt_sink_comp to make consume within the trace
1378 processing graph \bt_p{graph}.
1379
1380See \ref api-graph-lc-run "Run" to learn more about running a trace
1381processing graph.
1382
1383This function makes the \em next non-ended sink component consume. For
1384example, if \bt_p{graph} has two non-ended sink components A and B:
1385
1386- Calling bt_graph_run_once() makes sink component A consume.
1387- Calling bt_graph_run_once() again makes sink component B consume.
1388- Calling bt_graph_run_once() again makes sink component A consume.
1389- ...
1390
1391Considering this, if \bt_p{graph} contains a single non-ended sink
1392component, this function \em always makes this sink component consume.
1393
1394If the sink component's consuming method:
1395
1396<dl>
1397 <dt>Succeeds</dt>
1398 <dd>This function returns #BT_GRAPH_RUN_ONCE_STATUS_OK.</dd>
1399
1400 <dt>Returns "try again"</dt>
1401 <dd>This function returns #BT_GRAPH_RUN_ONCE_STATUS_AGAIN.</dd>
1402
1403 <dt>Fails</dt>
1404 <dd>
1405 This function returns #BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR
1406 or #BT_GRAPH_RUN_ONCE_STATUS_ERROR.
1407 </dd>
1408</dl>
1409
1410When all the sink components of \bt_p{graph} are finished processing
1411(ended), this function returns #BT_GRAPH_RUN_ONCE_STATUS_END.
1412
1413bt_graph_run() calls this function in a loop until are the sink
1414components are ended or an exception occurs.
1415
1416When you call this function or bt_graph_run() for the first time,
1417\bt_p{graph} becomes <em>configured</em>. See
1418\ref api-graph-lc "Trace processing graph life cycle"
1419to learn what happens when a trace processing graph becomes configured,
1420and what you can and cannot do with a configured graph.
1421
1422@param[in] graph
1423 Trace processing graph of which to make the next sink component
1424 consume.
1425
1426@retval #BT_GRAPH_RUN_ONCE_STATUS_OK
1427 Success.
1428@retval #BT_GRAPH_RUN_ONCE_STATUS_END
1429 All sink components are finished processing.
1430@retval #BT_GRAPH_RUN_ONCE_STATUS_AGAIN
1431 Try again.
1432@retval #BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR
1433 Out of memory.
1434@retval #BT_GRAPH_RUN_ONCE_STATUS_ERROR
1435 Other error.
1436
1437@bt_pre_not_null{graph}
1438@bt_pre_graph_not_faulty{graph}
1439
1440@sa bt_graph_run() &mdash;
1441 Runs a trace processing graph, making all its sink components
1442 consume in a round robin fashion.
1443*/
648dab91 1444extern bt_graph_run_once_status bt_graph_run_once(bt_graph *graph);
d24d5663 1445
43c59509
PP
1446/*! @} */
1447
1448/*!
1449@name Interruption
1450@{
1451*/
1452
1453/*!
1454@brief
1455 Status codes for bt_graph_add_interrupter().
1456*/
1457typedef enum bt_graph_add_interrupter_status {
1458 /*!
1459 @brief
1460 Success.
1461 */
1462 BT_GRAPH_ADD_INTERRUPTER_STATUS_OK = __BT_FUNC_STATUS_OK,
1463
1464 /*!
1465 @brief
1466 Out of memory.
1467 */
1468 BT_GRAPH_ADD_INTERRUPTER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
1469} bt_graph_add_interrupter_status;
1470
1471/*!
1472@brief
1473 Adds the \bt_intr \bt_p{interrupter} to all the current and future
1474 \bt_p_sink_comp and \bt_p_msg_iter of the trace processing graph
1475 \bt_p{graph}, as well as to the graph itself.
1476
1477Sink components can check whether or not they are interrupted
1478with bt_self_component_sink_is_interrupted().
1479
1480Message iterators can check whether or not they are interrupted
1481with bt_self_message_iterator_is_interrupted().
1482
1483The bt_graph_run() loop intermittently checks whether or not any of the
1484graph's interrupters is set. If so, bt_graph_run() returns
1485#BT_GRAPH_RUN_STATUS_AGAIN.
1486
1487@note
1488 @parblock
1489 bt_graph_create() returns a trace processing graph which comes
1490 with its own <em>default interrupter</em>.
1491
1492 Instead of adding your own interrupter to \bt_p{graph}, you can
1493 set its default interrupter with
1494
1495 @code
1496 bt_interrupter_set(bt_graph_borrow_default_interrupter());
1497 @endcode
1498 @endparblock
1499
1500@param[in] graph
1501 Trace processing graph to which to add \bt_p{interrupter}.
1502@param[in] interrupter
1503 Interrupter to add to \bt_p{graph}.
1504
1505@retval #BT_GRAPH_ADD_INTERRUPTER_STATUS_OK
1506 Success.
1507@retval #BT_GRAPH_ADD_INTERRUPTER_STATUS_MEMORY_ERROR
1508 Out of memory.
1509
1510@bt_pre_not_null{graph}
1511@bt_pre_graph_not_faulty{graph}
1512@bt_pre_not_null{interrupter}
1513
1514@sa bt_graph_borrow_default_interrupter() &mdash;
1515 Borrows the default interrupter from a trace processing graph.
1516*/
1517extern bt_graph_add_interrupter_status bt_graph_add_interrupter(bt_graph *graph,
1518 const bt_interrupter *interrupter);
1519
1520/*!
1521@brief
1522 Borrows the default \bt_intr from the trace processing graph
1523 \bt_p{graph}.
1524
1525@param[in] graph
1526 Trace processing graph from which to borrow the default interrupter.
1527
1528@returns
1529 @parblock
1530 \em Borrowed reference of the default interrupter of \bt_p{graph}.
1531
1532 The returned pointer remains valid as long as \bt_p{graph} exists.
1533 @endparblock
1534
1535@bt_pre_not_null{graph}
1536
1537@sa bt_graph_add_interrupter() &mdash;
1538 Adds an interrupter to a trace processing graph.
1539*/
1540extern bt_interrupter *bt_graph_borrow_default_interrupter(bt_graph *graph);
1541
1542/*! @} */
1543
1544/*!
1545@name Listeners
1546@{
1547*/
1548
1549/*!
1550@brief
1551 Status codes for the
1552 <code>bt_graph_add_*_component_*_port_added_listener()</code>
1553 functions.
1554*/
d24d5663 1555typedef enum bt_graph_add_listener_status {
43c59509
PP
1556 /*!
1557 @brief
1558 Success.
1559 */
d24d5663 1560 BT_GRAPH_ADD_LISTENER_STATUS_OK = __BT_FUNC_STATUS_OK,
43c59509
PP
1561
1562 /*!
1563 @brief
1564 Out of memory.
1565 */
d24d5663
PP
1566 BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
1567} bt_graph_add_listener_status;
1568
43c59509
PP
1569/*!
1570@brief
1571 Status codes for the
1572 <code>bt_graph_*_component_*_port_added_listener_func()</code>
1573 types.
1574*/
1575typedef enum bt_graph_listener_func_status {
1576 /*!
1577 @brief
1578 Success.
1579 */
1580 BT_GRAPH_LISTENER_FUNC_STATUS_OK = __BT_FUNC_STATUS_OK,
1581
1582 /*!
1583 @brief
1584 Out of memory.
1585 */
1586 BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
1587
1588 /*!
1589 @brief
1590 Other error.
1591 */
1592 BT_GRAPH_LISTENER_FUNC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
1593} bt_graph_listener_func_status;
1594
1595/*!
1596@brief
1597 User function for
1598 bt_graph_add_filter_component_input_port_added_listener().
1599
1600Such a function is called whenever a \bt_flt_comp within a trace
1601processing graph adds an \bt_iport during the graph
1602\ref api-graph-lc "configuration" phase.
1603
1604See \ref api-graph-listeners "Listeners" to learn more.
1605
1606@param[in] component
1607 Filter component which added \bt_p{port}.
1608@param[in] port
1609 Input port added by \bt_p{component}.
1610@param[in] user_data
1611 User data, as passed as the \bt_p{user_data} parameter of
1612 bt_graph_add_filter_component_input_port_added_listener().
1613
1614@retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
1615 Success.
1616@retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
1617 Out of memory.
1618@retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
1619 Other error.
1620
1621@bt_pre_not_null{component}
1622@bt_pre_not_null{port}
1623
1624@sa bt_graph_add_filter_component_input_port_added_listener() &mdash;
1625 Adds a "filter component input port added" listener to a trace
1626 processing graph.
1627*/
1628typedef bt_graph_listener_func_status
1629(*bt_graph_filter_component_input_port_added_listener_func)(
1630 const bt_component_filter *component,
1631 const bt_port_input *port, void *user_data);
1632
1633/*!
1634@brief
1635 Adds a \"\bt_flt_comp \bt_iport added\" listener to the trace
1636 processing graph \bt_p{graph}.
1637
1638Once this function returns, \bt_p{user_func} is called whenever a
1639filter component adds an input port within \bt_p{graph}.
1640
1641See \ref api-graph-listeners "Listeners" to learn more.
1642
1643@param[in] graph
1644 Trace processing graph to add the "filter component input port
1645 added" listener to.
1646@param[in] user_func
1647 User function of the "filter component input port added" listener to
1648 add to \bt_p{graph}.
1649@param[in] user_data
1650 User data to pass as the \bt_p{user_data} parameter of
1651 \bt_p{user_func}.
1652@param[out] listener_id
1653 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
1654 is the ID of the added listener within \bt_p{graph}.
1655
1656@retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
1657 Success.
1658@retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
1659 Out of memory.
1660
1661@bt_pre_not_null{graph}
1662@bt_pre_graph_not_faulty{graph}
1663@bt_pre_not_null{user_func}
1664*/
d24d5663
PP
1665extern bt_graph_add_listener_status
1666bt_graph_add_filter_component_input_port_added_listener(
b19ff26f 1667 bt_graph *graph,
43c59509
PP
1668 bt_graph_filter_component_input_port_added_listener_func user_func,
1669 void *user_data, bt_listener_id *listener_id);
1670
1671/*!
1672@brief
1673 User function for
1674 bt_graph_add_sink_component_input_port_added_listener().
1675
1676Such a function is called whenever a \bt_sink_comp within a trace
1677processing graph adds an \bt_iport during the graph
1678\ref api-graph-lc "configuration" phase.
1679
1680See \ref api-graph-listeners "Listeners" to learn more.
1681
1682@param[in] component
1683 Filter component which added \bt_p{port}.
1684@param[in] port
1685 Input port added by \bt_p{component}.
1686@param[in] user_data
1687 User data, as passed as the \bt_p{user_data} parameter of
1688 bt_graph_add_sink_component_input_port_added_listener().
1689
1690@retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
1691 Success.
1692@retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
1693 Out of memory.
1694@retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
1695 Other error.
1696
1697@bt_pre_not_null{component}
1698@bt_pre_not_null{port}
1699
1700@sa bt_graph_add_sink_component_input_port_added_listener() &mdash;
1701 Adds a "sink component input port added" listener to a trace
1702 processing graph.
1703*/
1704typedef bt_graph_listener_func_status
1705(*bt_graph_sink_component_input_port_added_listener_func)(
1706 const bt_component_sink *component,
1707 const bt_port_input *port, void *user_data);
1708
1709/*!
1710@brief
1711 Adds a \"\bt_sink_comp \bt_iport added\" listener to the trace
1712 processing graph \bt_p{graph}.
1713
1714Once this function returns, \bt_p{user_func} is called whenever a
1715sink component adds an input port within \bt_p{graph}.
1716
1717See \ref api-graph-listeners "Listeners" to learn more.
1718
1719@param[in] graph
1720 Trace processing graph to add the "sink component input port
1721 added" listener to.
1722@param[in] user_func
1723 User function of the "sink component input port added" listener to
1724 add to \bt_p{graph}.
1725@param[in] user_data
1726 User data to pass as the \bt_p{user_data} parameter of
1727 \bt_p{user_func}.
1728@param[out] listener_id
1729 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
1730 is the ID of the added listener within \bt_p{graph}.
1731
1732@retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
1733 Success.
1734@retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
1735 Out of memory.
0d72b8c3 1736
43c59509
PP
1737@bt_pre_not_null{graph}
1738@bt_pre_graph_not_faulty{graph}
1739@bt_pre_not_null{user_func}
1740*/
d24d5663
PP
1741extern bt_graph_add_listener_status
1742bt_graph_add_sink_component_input_port_added_listener(
b19ff26f 1743 bt_graph *graph,
43c59509
PP
1744 bt_graph_sink_component_input_port_added_listener_func user_func,
1745 void *user_data, bt_listener_id *listener_id);
0d72b8c3 1746
43c59509
PP
1747/*!
1748@brief
1749 User function for
1750 bt_graph_add_source_component_output_port_added_listener().
1751
1752Such a function is called whenever a \bt_src_comp within a trace
1753processing graph adds an \bt_oport during the graph
1754\ref api-graph-lc "configuration" phase.
1755
1756See \ref api-graph-listeners "Listeners" to learn more.
1757
1758@param[in] component
1759 Filter component which added \bt_p{port}.
1760@param[in] port
1761 Input port added by \bt_p{component}.
1762@param[in] user_data
1763 User data, as passed as the \bt_p{user_data} parameter of
1764 bt_graph_add_source_component_output_port_added_listener().
1765
1766@retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
1767 Success.
1768@retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
1769 Out of memory.
1770@retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
1771 Other error.
1772
1773@bt_pre_not_null{component}
1774@bt_pre_not_null{port}
1775
1776@sa bt_graph_add_source_component_output_port_added_listener() &mdash;
1777 Adds a "source component output port added" listener to a trace
1778 processing graph.
1779*/
1780typedef bt_graph_listener_func_status
1781(*bt_graph_source_component_output_port_added_listener_func)(
1782 const bt_component_source *component,
1783 const bt_port_output *port, void *user_data);
1784
1785/*!
1786@brief
1787 Adds a \"\bt_src_comp \bt_oport added\" listener to the trace
1788 processing graph \bt_p{graph}.
1789
1790Once this function returns, \bt_p{user_func} is called whenever a
1791source component adds an output port within \bt_p{graph}.
1792
1793See \ref api-graph-listeners "Listeners" to learn more.
1794
1795@param[in] graph
1796 Trace processing graph to add the "source component output port
1797 added" listener to.
1798@param[in] user_func
1799 User function of the "source component output port added" listener
1800 to add to \bt_p{graph}.
1801@param[in] user_data
1802 User data to pass as the \bt_p{user_data} parameter of
1803 \bt_p{user_func}.
1804@param[out] listener_id
1805 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
1806 is the ID of the added listener within \bt_p{graph}.
1807
1808@retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
1809 Success.
1810@retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
1811 Out of memory.
1812
1813@bt_pre_not_null{graph}
1814@bt_pre_graph_not_faulty{graph}
1815@bt_pre_not_null{user_func}
1816*/
d24d5663
PP
1817extern bt_graph_add_listener_status
1818bt_graph_add_source_component_output_port_added_listener(
b19ff26f 1819 bt_graph *graph,
43c59509
PP
1820 bt_graph_source_component_output_port_added_listener_func user_func,
1821 void *user_data, bt_listener_id *listener_id);
1822
1823/*!
1824@brief
1825 User function for
1826 bt_graph_add_filter_component_output_port_added_listener().
1827
1828Such a function is called whenever a \bt_flt_comp within a trace
1829processing graph adds an \bt_oport during the graph
1830\ref api-graph-lc "configuration" phase.
1831
1832See \ref api-graph-listeners "Listeners" to learn more.
1833
1834@param[in] component
1835 Filter component which added \bt_p{port}.
1836@param[in] port
1837 Input port added by \bt_p{component}.
1838@param[in] user_data
1839 User data, as passed as the \bt_p{user_data} parameter of
1840 bt_graph_add_filter_component_output_port_added_listener().
1841
1842@retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
1843 Success.
1844@retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
1845 Out of memory.
1846@retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
1847 Other error.
1848
1849@bt_pre_not_null{component}
1850@bt_pre_not_null{port}
1851
1852@sa bt_graph_add_filter_component_output_port_added_listener() &mdash;
1853 Adds a "filter component output port added" listener to a trace
1854 processing graph.
1855*/
1856typedef bt_graph_listener_func_status
1857(*bt_graph_filter_component_output_port_added_listener_func)(
1858 const bt_component_filter *component,
1859 const bt_port_output *port, void *user_data);
1860
1861/*!
1862@brief
1863 Adds a \"\bt_flt_comp \bt_oport added\" listener to the trace
1864 processing graph \bt_p{graph}.
1865
1866Once this function returns, \bt_p{user_func} is called whenever a
1867filter component adds an output port within \bt_p{graph}.
1868
1869See \ref api-graph-listeners "Listeners" to learn more.
0d72b8c3 1870
43c59509
PP
1871@param[in] graph
1872 Trace processing graph to add the "filter component output port
1873 added" listener to.
1874@param[in] user_func
1875 User function of the "filter component output port added" listener
1876 to add to \bt_p{graph}.
1877@param[in] user_data
1878 User data to pass as the \bt_p{user_data} parameter of
1879 \bt_p{user_func}.
1880@param[out] listener_id
1881 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
1882 is the ID of the added listener within \bt_p{graph}.
1883
1884@retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
1885 Success.
1886@retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
1887 Out of memory.
1888
1889@bt_pre_not_null{graph}
1890@bt_pre_graph_not_faulty{graph}
1891@bt_pre_not_null{user_func}
1892*/
d24d5663
PP
1893extern bt_graph_add_listener_status
1894bt_graph_add_filter_component_output_port_added_listener(
b19ff26f 1895 bt_graph *graph,
43c59509
PP
1896 bt_graph_filter_component_output_port_added_listener_func user_func,
1897 void *user_data, bt_listener_id *listener_id);
0d72b8c3 1898
43c59509 1899/*! @} */
d24d5663 1900
43c59509
PP
1901/*!
1902@name Reference count
1903@{
1904*/
9b4f9b42 1905
43c59509
PP
1906/*!
1907@brief
1908 Increments the \ref api-fund-shared-object "reference count" of
1909 the trace processing graph \bt_p{graph}.
1910
1911@param[in] graph
1912 @parblock
1913 Trace processing graph of which to increment the reference count.
1914
1915 Can be \c NULL.
1916 @endparblock
1917
1918@sa bt_graph_put_ref() &mdash;
1919 Decrements the reference count of a trace processing graph.
1920*/
1921extern void bt_graph_get_ref(const bt_graph *graph);
1922
1923/*!
1924@brief
1925 Decrements the \ref api-fund-shared-object "reference count" of
1926 the trace processing graph \bt_p{graph}.
1927
1928@param[in] graph
1929 @parblock
1930 Trace processing graph of which to decrement the reference count.
1931
1932 Can be \c NULL.
1933 @endparblock
1934
1935@sa bt_graph_get_ref() &mdash;
1936 Increments the reference count of a trace processing graph.
1937*/
1938extern void bt_graph_put_ref(const bt_graph *graph);
1939
1940/*!
1941@brief
1942 Decrements the reference count of the trace processing graph
1943 \bt_p{_graph}, and then sets \bt_p{_graph} to \c NULL.
1944
1945@param _graph
1946 @parblock
1947 Trace processing graph of which to decrement the reference count.
1948
1949 Can contain \c NULL.
1950 @endparblock
1951
1952@bt_pre_assign_expr{_graph}
1953*/
1954#define BT_GRAPH_PUT_REF_AND_RESET(_graph) \
1955 do { \
1956 bt_graph_put_ref(_graph); \
1957 (_graph) = NULL; \
1958 } while (0)
1959
1960/*!
1961@brief
1962 Decrements the reference count of the trace processing graph
1963 \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets
1964 \bt_p{_src} to \c NULL.
1965
1966This macro effectively moves a trace processing graph reference from the
1967expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
1968existing \bt_p{_dst} reference.
1969
1970@param _dst
1971 @parblock
1972 Destination expression.
1973
1974 Can contain \c NULL.
1975 @endparblock
1976@param _src
1977 @parblock
1978 Source expression.
1979
1980 Can contain \c NULL.
1981 @endparblock
1982
1983@bt_pre_assign_expr{_dst}
1984@bt_pre_assign_expr{_src}
1985*/
1986#define BT_GRAPH_MOVE_REF(_dst, _src) \
1987 do { \
1988 bt_graph_put_ref(_dst); \
1989 (_dst) = (_src); \
1990 (_src) = NULL; \
1991 } while (0)
1992
1993/*! @} */
1994
1995/*! @} */
202a3a13 1996
c0418dd9
JG
1997#ifdef __cplusplus
1998}
1999#endif
2000
924dc299 2001#endif /* BABELTRACE2_GRAPH_GRAPH_H */
This page took 0.159418 seconds and 4 git commands to generate.