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