Commit | Line | Data |
---|---|---|
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 |
18 | extern "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 |
27 | A <strong><em>trace processing graph</em></strong> is a specialized |
28 | <a href="https://en.wikipedia.org/wiki/Filter_graph">filter graph</a> | |
29 | to manipulate one or more traces. | |
0d72b8c3 | 30 | |
43c59509 PP |
31 | Whereas the nodes of a multimedia filter graph typically exchange |
32 | video frames and audio samples, the nodes, or \bt_p_comp, of a trace | |
33 | processing graph exchange immutable \bt_p_msg containing trace data. | |
0d72b8c3 | 34 | |
43c59509 PP |
35 | The following illustration shows a basic trace processing graph which |
36 | converts 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 | 40 | In 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 | ||
66 | Of course the topology can be much more complex if needed: | |
67 | ||
68 | @image html complex-graph.png "Complex trace processing graph." | |
69 | ||
70 | In a trace processing graph, \bt_p_comp are instances of \bt_p_comp_cls. | |
71 | ||
72 | A \bt_plugin can provide a component class, but you can also create one | |
73 | dynamically (see \ref api-comp-cls-dev). | |
74 | ||
75 | The connections between component ports in a trace processing graph | |
76 | indicate the needed topology to achieve a trace processing task. That | |
77 | being said, | |
78 | \bt_p_msg do not flow within connections. Instead, a source-to-sink | |
79 | or filter-to-sink connection makes it | |
80 | possible for a sink component to create a \bt_msg_iter on its end of | |
81 | the connection (an \bt_iport). In turn, a filter component message | |
82 | iterator can create other message iterators on one or more of the | |
83 | component's input ports. For a single connection, there can exist | |
84 | multiple message iterators. | |
85 | ||
86 | A trace processing graph is a | |
87 | \ref api-fund-shared-object "shared object": get a new reference with | |
88 | bt_graph_get_ref() and put an existing reference with | |
89 | bt_graph_put_ref(). | |
90 | ||
91 | The type of a trace processing graph is #bt_graph. | |
92 | ||
93 | Create a default trace processing graph with bt_graph_create(). You need | |
94 | to pass a \bt_mip (MIP) version number when you call this function. | |
95 | Then, see | |
96 | \ref api-graph-lc "Trace processing graph life cycle" | |
97 | to learn how to add components to the graph, connect their ports, and | |
98 | run it. | |
99 | ||
100 | To interrupt a \ref api-graph-lc-run "running" trace processing graph, | |
101 | either: | |
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 | ||
117 | The following diagram shows the life cycle of a trace processing | |
118 | graph: | |
119 | ||
120 | @image html graph-lifetime.png "Trace processing graph lifecycle." | |
121 | ||
122 | After you create a default (empty) trace processing graph with | |
123 | bt_graph_create(), there are three steps to make the trace processing | |
124 | task 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 | ||
130 | You can repeat steps 1 and 2 before step 3, as connecting a | |
131 | component \bt_port can make this \bt_comp create a new port: | |
132 | you might want to add a component in reaction to this event | |
133 | (see \ref api-graph-listeners "Listeners"). | |
134 | ||
135 | Steps 1 and 2 constitute the \em configuration phase of the trace | |
136 | processing graph. The first time you call bt_graph_run() or | |
137 | bt_graph_run_once() for a given graph (step 3), the graph becomes | |
138 | <em>configured</em>, and it notifies the sink components as such so that | |
139 | they can create their \bt_p_msg_iter. | |
140 | ||
141 | Once 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 | ||
149 | In 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 | ||
157 | If \em any error occurs (a function returns a status code which ends | |
158 | with <code>ERROR</code>) during step 1 or 2, the trace processing | |
159 | graph is considered <strong>faulty</strong>: you cannot use it anymore. | |
160 | The only functions you can call with a faulty graph are | |
161 | bt_graph_get_ref() and bt_graph_put_ref(). | |
162 | ||
163 | <h2>\anchor api-graph-lc-add Add components</h2> | |
164 | ||
165 | Adding 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 | |
167 | create the component from its class before adding it. | |
168 | ||
169 | Because component and component class C types are | |
170 | \ref api-fund-c-typing "highly specific", there are six functions | |
171 | to 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 | ||
208 | The <code>*_with_initialize_method_data()</code> versions can pass a | |
209 | custom, \bt_voidp pointer to the component's | |
210 | \ref api-comp-cls-dev-meth-init "initialization method". | |
211 | The other versions pass \c NULL as this parameter. | |
212 | ||
213 | All 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 | ||
229 | Once you have the created and added component (\bt_p{*component}), | |
230 | you can borrow its \bt_p_port to | |
231 | \ref api-graph-lc-connect "connect them". | |
232 | ||
233 | You can add as many components as needed to a trace processing graph, | |
234 | but they must all have a unique name. | |
235 | ||
236 | <h3>\anchor api-graph-lc-add-ss Add a simple sink component</h3> | |
237 | ||
238 | To add a very basic \bt_sink_comp which has a single \bt_iport and | |
239 | creates a single \bt_msg_iter when the trace processing graph becomes | |
240 | configured, use bt_graph_add_simple_sink_component(). When you call | |
241 | this 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 | ||
269 | The three functions above receive, as their last parameter, the user | |
270 | data you passed to bt_graph_add_simple_sink_component() . | |
271 | ||
272 | <h2>\anchor api-graph-lc-connect Connect component ports</h2> | |
273 | ||
274 | When you \ref api-graph-lc-add "add a component" to a trace processing | |
275 | graph with one of the <code>bt_graph_add_*_component*()</code> | |
276 | functions, the function sets \bt_p{*component} to the | |
277 | created and added component. | |
278 | ||
279 | With such a \bt_comp, you can borrow one of its \bt_p_port by index or | |
280 | by name. | |
281 | ||
282 | Connect two component ports within a trace processing graph with | |
283 | bt_graph_connect_ports(). | |
284 | ||
285 | After you connect component ports, you can still | |
286 | \ref api-graph-lc-add "add" more components to the graph, and then | |
287 | connect more ports. | |
288 | ||
289 | You don't need to connect all the available ports of a given component, | |
290 | depending on the trace processing task you need to perform. However, | |
291 | when 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 | ||
300 | When you are done configuring a trace processing graph, you can run it | |
301 | with bt_graph_run(). | |
302 | ||
303 | bt_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 | ||
330 | If 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() | |
332 | instead of bt_graph_run(). | |
333 | ||
334 | <h1>Standard \bt_name component classes</h1> | |
078033ed | 335 | |
43c59509 PP |
336 | The \bt_name project ships with project \bt_p_plugin which provide |
337 | "standard" \bt_p_comp_cls. | |
078033ed | 338 | |
43c59509 PP |
339 | Those standard component classes can be useful in many trace processing |
340 | graph 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 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 | ||
463 | To access such a component class, get its plugin by name with | |
464 | bt_plugin_find() and then borrow the component class by name | |
465 | with bt_plugin_borrow_source_component_class_by_name_const(), | |
466 | bt_plugin_borrow_filter_component_class_by_name_const(), or | |
467 | bt_plugin_borrow_sink_component_class_by_name_const(). | |
468 | ||
469 | For example: | |
470 | ||
471 | @code | |
472 | const bt_plugin *plugin; | |
473 | ||
474 | if (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 | ||
479 | const bt_component_class_filter *muxer_component_class = | |
480 | bt_plugin_borrow_filter_component_class_by_name_const(plugin, "muxer"); | |
481 | ||
482 | if (!muxer_component_class) { | |
483 | // handle error | |
484 | } | |
485 | @endcode | |
486 | ||
487 | <h1>\anchor api-graph-listeners Listeners</h1> | |
488 | ||
489 | A \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 | ||
497 | To get notified when any component of a given trace processing | |
498 | graph adds a port, add one or more "port | |
499 | added" 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 | ||
506 | Within a "port added" listener function, you can | |
507 | \ref api-graph-lc-add "add more components" | |
508 | and \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 | ||
535 | On success, the returned graph contains no components (see | |
536 | \ref api-graph-lc-add "Add components"). | |
537 | ||
538 | The graph is configured as operating following version | |
539 | \bt_p{mip_version} of the Message Interchange Protocol, so that | |
540 | bt_self_component_get_graph_mip_version() returns this version when | |
541 | components call it. | |
542 | ||
543 | @note | |
544 | As of \bt_name_version_min_maj, the only available MIP version is 0. | |
545 | ||
546 | The 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 | |
549 | default 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 | 561 | extern 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 | 575 | typedef 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 |
600 | extern bt_graph_add_component_status |
601 | bt_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 | ||
617 | See \ref api-graph-lc-add "Add components" to learn more about adding | |
618 | components to a trace processing graph. | |
619 | ||
620 | This function calls the source component's | |
621 | \ref api-comp-cls-dev-meth-init "initialization method" after | |
622 | creating it. | |
623 | ||
624 | The 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 | ||
632 | The 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 | 680 | extern bt_graph_add_component_status |
21a9f056 | 681 | bt_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 |
693 | extern bt_graph_add_component_status |
694 | bt_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 | ||
710 | See \ref api-graph-lc-add "Add components" to learn more about adding | |
711 | components to a trace processing graph. | |
712 | ||
713 | This function calls the filter component's | |
714 | \ref api-comp-cls-dev-meth-init "initialization method" after | |
715 | creating it. | |
716 | ||
717 | The 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 | ||
725 | The 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 | 773 | extern bt_graph_add_component_status |
21a9f056 | 774 | bt_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 |
786 | extern bt_graph_add_component_status |
787 | bt_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 | ||
803 | See \ref api-graph-lc-add "Add components" to learn more about adding | |
804 | components to a trace processing graph. | |
805 | ||
806 | This function calls the sink component's | |
807 | \ref api-comp-cls-dev-meth-init "initialization method" after | |
808 | creating it. | |
809 | ||
810 | The 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 | ||
818 | The 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 | 866 | extern bt_graph_add_component_status |
21a9f056 | 867 | bt_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 | */ | |
885 | typedef 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 | ||
910 | Such an initialization function is called when the trace processing | |
911 | graph becomes configured and when the simple sink component has created | |
912 | its single \bt_msg_iter. This occurs the first time you call | |
913 | bt_graph_run() or bt_graph_run_once() on the trace processing graph. | |
914 | ||
915 | See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more | |
916 | about 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() — | |
942 | Creates and adds a simple sink component to a trace processing | |
943 | graph. | |
944 | */ | |
945 | typedef 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 | */ | |
955 | typedef 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 | ||
991 | Such 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 | |
993 | occurs in a loop within bt_graph_run() or when it's this sink | |
994 | component's turn to consume in | |
995 | bt_graph_run_once(). | |
996 | ||
997 | See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more | |
998 | about adding a simple component to a trace processing graph. | |
999 | ||
1000 | If you are not done consuming messages, return | |
1001 | #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK. | |
1002 | ||
1003 | If you are done consuming messages, return | |
1004 | #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END. | |
1005 | ||
1006 | If you wish to avoid a blocking operation and make | |
1007 | bt_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() — | |
1038 | Creates and adds a simple sink component to a trace processing | |
1039 | graph. | |
1040 | */ | |
1041 | typedef 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 | ||
1050 | Such a finalization function is called when the simple sink component | |
1051 | is finalized. This occurs when the trace processing graph is destroyed | |
1052 | (you put its last strong \ref api-fund-shared-object "reference" | |
1053 | with bt_graph_put_ref()). | |
1054 | ||
1055 | See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more | |
1056 | about 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() — | |
1065 | Creates and adds a simple sink component to a trace processing | |
1066 | graph. | |
1067 | */ | |
1068 | typedef 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 | ||
1076 | See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more | |
1077 | about adding a simple component to a trace processing graph. | |
1078 | ||
1079 | \bt_p{initialize_func} (if not \c NULL), \bt_p{consume_func}, | |
1080 | and \bt_p{finalize_func} (if not \c NULL) receive \bt_p{user_data} | |
1081 | as 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 |
1126 | extern bt_graph_add_component_status |
1127 | bt_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 | 1144 | typedef 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 | ||
1171 | See \ref api-graph-lc-connect "Connect component ports" to learn more | |
1172 | about connecting ports within a trace processing graph. | |
1173 | ||
1174 | Both \bt_p{upstream_port} and \bt_p{downstream_port} must be | |
1175 | unconnected (bt_port_is_connected() returns #BT_FALSE) when you call | |
1176 | this 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 | 1217 | extern 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 | 1233 | typedef 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 | ||
1267 | See \ref api-graph-lc-run "Run" to learn more about running a trace | |
1268 | processing graph. | |
1269 | ||
1270 | This 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 | ||
1297 | To make a single sink component consume, then get the thread's control | |
1298 | back, use bt_graph_run_once(). | |
1299 | ||
1300 | When 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" | |
1303 | to learn what happens when a trace processing graph becomes configured, | |
1304 | and 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() — | |
1333 | Calls a single trace processing graph's sink component's consuming | |
1334 | method once. | |
1335 | */ | |
d24d5663 PP |
1336 | extern 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 | 1342 | typedef 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 | ||
1380 | See \ref api-graph-lc-run "Run" to learn more about running a trace | |
1381 | processing graph. | |
1382 | ||
1383 | This function makes the \em next non-ended sink component consume. For | |
1384 | example, 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 | ||
1391 | Considering this, if \bt_p{graph} contains a single non-ended sink | |
1392 | component, this function \em always makes this sink component consume. | |
1393 | ||
1394 | If 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 | ||
1410 | When all the sink components of \bt_p{graph} are finished processing | |
1411 | (ended), this function returns #BT_GRAPH_RUN_ONCE_STATUS_END. | |
1412 | ||
1413 | bt_graph_run() calls this function in a loop until are the sink | |
1414 | components are ended or an exception occurs. | |
1415 | ||
1416 | When 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" | |
1419 | to learn what happens when a trace processing graph becomes configured, | |
1420 | and 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() — | |
1441 | Runs a trace processing graph, making all its sink components | |
1442 | consume in a round robin fashion. | |
1443 | */ | |
648dab91 | 1444 | extern 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 | */ | |
1457 | typedef 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 | ||
1477 | Sink components can check whether or not they are interrupted | |
1478 | with bt_self_component_sink_is_interrupted(). | |
1479 | ||
1480 | Message iterators can check whether or not they are interrupted | |
1481 | with bt_self_message_iterator_is_interrupted(). | |
1482 | ||
1483 | The bt_graph_run() loop intermittently checks whether or not any of the | |
1484 | graph'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() — | |
1515 | Borrows the default interrupter from a trace processing graph. | |
1516 | */ | |
1517 | extern 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() — | |
1538 | Adds an interrupter to a trace processing graph. | |
1539 | */ | |
1540 | extern 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 | 1555 | typedef 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 | */ | |
1575 | typedef 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 | ||
1600 | Such a function is called whenever a \bt_flt_comp within a trace | |
1601 | processing graph adds an \bt_iport during the graph | |
1602 | \ref api-graph-lc "configuration" phase. | |
1603 | ||
1604 | See \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() — | |
1625 | Adds a "filter component input port added" listener to a trace | |
1626 | processing graph. | |
1627 | */ | |
1628 | typedef 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 | ||
1638 | Once this function returns, \bt_p{user_func} is called whenever a | |
1639 | filter component adds an input port within \bt_p{graph}. | |
1640 | ||
1641 | See \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 |
1665 | extern bt_graph_add_listener_status |
1666 | bt_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 | ||
1676 | Such a function is called whenever a \bt_sink_comp within a trace | |
1677 | processing graph adds an \bt_iport during the graph | |
1678 | \ref api-graph-lc "configuration" phase. | |
1679 | ||
1680 | See \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() — | |
1701 | Adds a "sink component input port added" listener to a trace | |
1702 | processing graph. | |
1703 | */ | |
1704 | typedef 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 | ||
1714 | Once this function returns, \bt_p{user_func} is called whenever a | |
1715 | sink component adds an input port within \bt_p{graph}. | |
1716 | ||
1717 | See \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 |
1741 | extern bt_graph_add_listener_status |
1742 | bt_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 | ||
1752 | Such a function is called whenever a \bt_src_comp within a trace | |
1753 | processing graph adds an \bt_oport during the graph | |
1754 | \ref api-graph-lc "configuration" phase. | |
1755 | ||
1756 | See \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() — | |
1777 | Adds a "source component output port added" listener to a trace | |
1778 | processing graph. | |
1779 | */ | |
1780 | typedef 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 | ||
1790 | Once this function returns, \bt_p{user_func} is called whenever a | |
1791 | source component adds an output port within \bt_p{graph}. | |
1792 | ||
1793 | See \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 |
1817 | extern bt_graph_add_listener_status |
1818 | bt_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 | ||
1828 | Such a function is called whenever a \bt_flt_comp within a trace | |
1829 | processing graph adds an \bt_oport during the graph | |
1830 | \ref api-graph-lc "configuration" phase. | |
1831 | ||
1832 | See \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() — | |
1853 | Adds a "filter component output port added" listener to a trace | |
1854 | processing graph. | |
1855 | */ | |
1856 | typedef 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 | ||
1866 | Once this function returns, \bt_p{user_func} is called whenever a | |
1867 | filter component adds an output port within \bt_p{graph}. | |
1868 | ||
1869 | See \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 |
1893 | extern bt_graph_add_listener_status |
1894 | bt_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() — | |
1919 | Decrements the reference count of a trace processing graph. | |
1920 | */ | |
1921 | extern 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() — | |
1936 | Increments the reference count of a trace processing graph. | |
1937 | */ | |
1938 | extern 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 | ||
1966 | This macro effectively moves a trace processing graph reference from the | |
1967 | expression \bt_p{_src} to the expression \bt_p{_dst}, putting the | |
1968 | existing \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 */ |