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 | ||
f38da6ca SM |
10 | /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */ |
11 | ||
4fa90f32 PP |
12 | #ifndef __BT_IN_BABELTRACE_H |
13 | # error "Please include <babeltrace2/babeltrace.h> instead." | |
14 | #endif | |
15 | ||
3fadfbc0 | 16 | #include <babeltrace2/types.h> |
e874da19 PP |
17 | #include <babeltrace2/logging.h> |
18 | ||
c0418dd9 JG |
19 | #ifdef __cplusplus |
20 | extern "C" { | |
21 | #endif | |
22 | ||
43c59509 PP |
23 | /*! |
24 | @defgroup api-graph Graph | |
8cc56726 | 25 | |
43c59509 PP |
26 | @brief |
27 | Trace processing graph. | |
0d72b8c3 | 28 | |
43c59509 PP |
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. | |
0d72b8c3 | 32 | |
43c59509 PP |
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. | |
0d72b8c3 | 36 | |
43c59509 PP |
37 | The following illustration shows a basic trace processing graph which |
38 | converts many traces to a single log of pretty-printed lines: | |
0d72b8c3 | 39 | |
43c59509 | 40 | @image html basic-convert-graph.png "Basic trace processing graph (conversion graph)." |
0d72b8c3 | 41 | |
43c59509 | 42 | In the illustrations above, notice that: |
0d72b8c3 | 43 | |
43c59509 | 44 | - The graph (blue) contains five components. |
9c0a126a | 45 | |
43c59509 PP |
46 | - Three source components (green) are connected to a single filter |
47 | component (yellow). | |
0d72b8c3 | 48 | |
43c59509 PP |
49 | There are five \bt_p_conn, from five \bt_p_oport |
50 | to five \bt_p_iport. | |
21a9f056 | 51 | |
43c59509 | 52 | - The filter component is connected to a single sink component (red). |
078033ed | 53 | |
43c59509 | 54 | There's a single connection. |
078033ed | 55 | |
43c59509 PP |
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 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 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> | |
078033ed | 337 | |
43c59509 PP |
338 | The \bt_name project ships with project \bt_p_plugin which provide |
339 | "standard" \bt_p_comp_cls. | |
078033ed | 340 | |
43c59509 PP |
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 | |
ceb29cf8 | 418 | <a href="https://manpages.debian.org/stretch/babeltrace/babeltrace.1.en.html">Babeltrace 1 |
43c59509 PP |
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 | */ | |
4c81a2b7 | 563 | extern bt_graph *bt_graph_create(uint64_t mip_version) __BT_NOEXCEPT; |
0d72b8c3 | 564 | |
43c59509 PP |
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 | */ | |
d24d5663 | 577 | typedef enum bt_graph_add_component_status { |
43c59509 PP |
578 | /*! |
579 | @brief | |
580 | Success. | |
581 | */ | |
d24d5663 | 582 | BT_GRAPH_ADD_COMPONENT_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
583 | |
584 | /*! | |
585 | @brief | |
586 | Out of memory. | |
587 | */ | |
d24d5663 | 588 | BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, |
43c59509 PP |
589 | |
590 | /*! | |
591 | @brief | |
592 | Other error. | |
593 | */ | |
594 | BT_GRAPH_ADD_COMPONENT_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
d24d5663 PP |
595 | } bt_graph_add_component_status; |
596 | ||
43c59509 PP |
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 | */ | |
d24d5663 PP |
602 | extern bt_graph_add_component_status |
603 | bt_graph_add_source_component(bt_graph *graph, | |
b19ff26f PP |
604 | const bt_component_class_source *component_class, |
605 | const char *name, const bt_value *params, | |
43c59509 | 606 | bt_logging_level logging_level, |
4c81a2b7 | 607 | const bt_component_source **component) __BT_NOEXCEPT; |
43c59509 PP |
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. | |
0d72b8c3 | 678 | |
43c59509 PP |
679 | @bt_post_success_frozen{component_class} |
680 | @bt_post_success_frozen{params} | |
681 | */ | |
d24d5663 | 682 | extern bt_graph_add_component_status |
21a9f056 | 683 | bt_graph_add_source_component_with_initialize_method_data( |
b19ff26f PP |
684 | bt_graph *graph, |
685 | const bt_component_class_source *component_class, | |
686 | const char *name, const bt_value *params, | |
43c59509 | 687 | void *initialize_method_data, bt_logging_level logging_level, |
4c81a2b7 | 688 | const bt_component_source **component) __BT_NOEXCEPT; |
0d72b8c3 | 689 | |
43c59509 PP |
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 | */ | |
d24d5663 PP |
695 | extern bt_graph_add_component_status |
696 | bt_graph_add_filter_component(bt_graph *graph, | |
b19ff26f PP |
697 | const bt_component_class_filter *component_class, |
698 | const char *name, const bt_value *params, | |
43c59509 | 699 | bt_logging_level logging_level, |
4c81a2b7 | 700 | const bt_component_filter **component) __BT_NOEXCEPT; |
0d72b8c3 | 701 | |
43c59509 PP |
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 | */ | |
d24d5663 | 775 | extern bt_graph_add_component_status |
21a9f056 | 776 | bt_graph_add_filter_component_with_initialize_method_data( |
b19ff26f PP |
777 | bt_graph *graph, |
778 | const bt_component_class_filter *component_class, | |
779 | const char *name, const bt_value *params, | |
43c59509 | 780 | void *initialize_method_data, bt_logging_level logging_level, |
4c81a2b7 | 781 | const bt_component_filter **component) __BT_NOEXCEPT; |
0d72b8c3 | 782 | |
43c59509 PP |
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 | */ | |
d24d5663 PP |
788 | extern bt_graph_add_component_status |
789 | bt_graph_add_sink_component( | |
4cdfc5e8 | 790 | bt_graph *graph, const bt_component_class_sink *component_class, |
b19ff26f | 791 | const char *name, const bt_value *params, |
43c59509 | 792 | bt_logging_level logging_level, |
4c81a2b7 | 793 | const bt_component_sink **component) __BT_NOEXCEPT; |
0d72b8c3 | 794 | |
43c59509 PP |
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 | */ | |
d24d5663 | 868 | extern bt_graph_add_component_status |
21a9f056 | 869 | bt_graph_add_sink_component_with_initialize_method_data( |
4cdfc5e8 | 870 | bt_graph *graph, const bt_component_class_sink *component_class, |
b19ff26f | 871 | const char *name, const bt_value *params, |
43c59509 | 872 | void *initialize_method_data, bt_logging_level logging_level, |
4c81a2b7 | 873 | const bt_component_sink **component) __BT_NOEXCEPT; |
0d72b8c3 | 874 | |
43c59509 PP |
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() — | |
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() — | |
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() — | |
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 | */ | |
078033ed PP |
1128 | extern bt_graph_add_component_status |
1129 | bt_graph_add_simple_sink_component(bt_graph *graph, const char *name, | |
43c59509 | 1130 | bt_graph_simple_sink_component_initialize_func initialize_func, |
078033ed PP |
1131 | bt_graph_simple_sink_component_consume_func consume_func, |
1132 | bt_graph_simple_sink_component_finalize_func finalize_func, | |
4c81a2b7 | 1133 | void *user_data, const bt_component_sink **component) __BT_NOEXCEPT; |
078033ed | 1134 | |
43c59509 PP |
1135 | /*! @} */ |
1136 | ||
1137 | /*! | |
1138 | @name Component port connection | |
1139 | @{ | |
1140 | */ | |
1141 | ||
1142 | /*! | |
1143 | @brief | |
1144 | Status codes for bt_graph_connect_ports(). | |
1145 | */ | |
d24d5663 | 1146 | typedef enum bt_graph_connect_ports_status { |
43c59509 PP |
1147 | /*! |
1148 | @brief | |
1149 | Success. | |
1150 | */ | |
d24d5663 | 1151 | BT_GRAPH_CONNECT_PORTS_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
1152 | |
1153 | /*! | |
1154 | @brief | |
1155 | Out of memory. | |
1156 | */ | |
d24d5663 | 1157 | BT_GRAPH_CONNECT_PORTS_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, |
43c59509 PP |
1158 | |
1159 | /*! | |
1160 | @brief | |
1161 | Other error. | |
1162 | */ | |
1163 | BT_GRAPH_CONNECT_PORTS_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
d24d5663 PP |
1164 | } bt_graph_connect_ports_status; |
1165 | ||
43c59509 PP |
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 | */ | |
d24d5663 | 1219 | extern bt_graph_connect_ports_status bt_graph_connect_ports(bt_graph *graph, |
43c59509 PP |
1220 | const bt_port_output *upstream_port, |
1221 | const bt_port_input *downstream_port, | |
4c81a2b7 | 1222 | const bt_connection **connection) __BT_NOEXCEPT; |
0d72b8c3 | 1223 | |
43c59509 PP |
1224 | /*! @} */ |
1225 | ||
1226 | /*! | |
1227 | @name Running | |
1228 | @{ | |
1229 | */ | |
1230 | ||
1231 | /*! | |
1232 | @brief | |
1233 | Status codes for bt_graph_run(). | |
1234 | */ | |
d24d5663 | 1235 | typedef enum bt_graph_run_status { |
43c59509 PP |
1236 | /*! |
1237 | @brief | |
1238 | Success. | |
1239 | */ | |
d24d5663 | 1240 | BT_GRAPH_RUN_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
1241 | |
1242 | /*! | |
1243 | @brief | |
1244 | Try again. | |
1245 | */ | |
d24d5663 | 1246 | BT_GRAPH_RUN_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN, |
43c59509 PP |
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, | |
d24d5663 PP |
1259 | } bt_graph_run_status; |
1260 | ||
43c59509 PP |
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() — | |
1335 | Calls a single trace processing graph's sink component's consuming | |
1336 | method once. | |
1337 | */ | |
4c81a2b7 | 1338 | extern bt_graph_run_status bt_graph_run(bt_graph *graph) __BT_NOEXCEPT; |
d24d5663 | 1339 | |
43c59509 PP |
1340 | /*! |
1341 | @brief | |
1342 | Status codes for bt_graph_run(). | |
1343 | */ | |
648dab91 | 1344 | typedef enum bt_graph_run_once_status { |
43c59509 PP |
1345 | /*! |
1346 | @brief | |
1347 | Success. | |
1348 | */ | |
648dab91 | 1349 | BT_GRAPH_RUN_ONCE_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
1350 | |
1351 | /*! | |
1352 | @brief | |
1353 | All sink components are finished processing. | |
1354 | */ | |
648dab91 | 1355 | BT_GRAPH_RUN_ONCE_STATUS_END = __BT_FUNC_STATUS_END, |
43c59509 PP |
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, | |
648dab91 PP |
1374 | } bt_graph_run_once_status; |
1375 | ||
43c59509 PP |
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() — | |
1443 | Runs a trace processing graph, making all its sink components | |
1444 | consume in a round robin fashion. | |
1445 | */ | |
4c81a2b7 | 1446 | extern bt_graph_run_once_status bt_graph_run_once(bt_graph *graph) __BT_NOEXCEPT; |
d24d5663 | 1447 | |
43c59509 PP |
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() — | |
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, | |
4c81a2b7 | 1520 | const bt_interrupter *interrupter) __BT_NOEXCEPT; |
43c59509 PP |
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() — | |
1540 | Adds an interrupter to a trace processing graph. | |
1541 | */ | |
4c81a2b7 PP |
1542 | extern bt_interrupter *bt_graph_borrow_default_interrupter(bt_graph *graph) |
1543 | __BT_NOEXCEPT; | |
43c59509 PP |
1544 | |
1545 | /*! @} */ | |
1546 | ||
1547 | /*! | |
1548 | @name Listeners | |
1549 | @{ | |
1550 | */ | |
1551 | ||
1552 | /*! | |
1553 | @brief | |
1554 | Status codes for the | |
1555 | <code>bt_graph_add_*_component_*_port_added_listener()</code> | |
1556 | functions. | |
1557 | */ | |
d24d5663 | 1558 | typedef enum bt_graph_add_listener_status { |
43c59509 PP |
1559 | /*! |
1560 | @brief | |
1561 | Success. | |
1562 | */ | |
d24d5663 | 1563 | BT_GRAPH_ADD_LISTENER_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
1564 | |
1565 | /*! | |
1566 | @brief | |
1567 | Out of memory. | |
1568 | */ | |
d24d5663 PP |
1569 | BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, |
1570 | } bt_graph_add_listener_status; | |
1571 | ||
43c59509 PP |
1572 | /*! |
1573 | @brief | |
1574 | Status codes for the | |
1575 | <code>bt_graph_*_component_*_port_added_listener_func()</code> | |
1576 | types. | |
1577 | */ | |
1578 | typedef enum bt_graph_listener_func_status { | |
1579 | /*! | |
1580 | @brief | |
1581 | Success. | |
1582 | */ | |
1583 | BT_GRAPH_LISTENER_FUNC_STATUS_OK = __BT_FUNC_STATUS_OK, | |
1584 | ||
1585 | /*! | |
1586 | @brief | |
1587 | Out of memory. | |
1588 | */ | |
1589 | BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
1590 | ||
1591 | /*! | |
1592 | @brief | |
1593 | Other error. | |
1594 | */ | |
1595 | BT_GRAPH_LISTENER_FUNC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
1596 | } bt_graph_listener_func_status; | |
1597 | ||
1598 | /*! | |
1599 | @brief | |
1600 | User function for | |
1601 | bt_graph_add_filter_component_input_port_added_listener(). | |
1602 | ||
1603 | Such a function is called whenever a \bt_flt_comp within a trace | |
1604 | processing graph adds an \bt_iport during the graph | |
1605 | \ref api-graph-lc "configuration" phase. | |
1606 | ||
1607 | See \ref api-graph-listeners "Listeners" to learn more. | |
1608 | ||
1609 | @param[in] component | |
1610 | Filter component which added \bt_p{port}. | |
1611 | @param[in] port | |
1612 | Input port added by \bt_p{component}. | |
1613 | @param[in] user_data | |
1614 | User data, as passed as the \bt_p{user_data} parameter of | |
1615 | bt_graph_add_filter_component_input_port_added_listener(). | |
1616 | ||
1617 | @retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK | |
1618 | Success. | |
1619 | @retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR | |
1620 | Out of memory. | |
1621 | @retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR | |
1622 | Other error. | |
1623 | ||
1624 | @bt_pre_not_null{component} | |
1625 | @bt_pre_not_null{port} | |
1626 | ||
1627 | @sa bt_graph_add_filter_component_input_port_added_listener() — | |
1628 | Adds a "filter component input port added" listener to a trace | |
1629 | processing graph. | |
1630 | */ | |
1631 | typedef bt_graph_listener_func_status | |
1632 | (*bt_graph_filter_component_input_port_added_listener_func)( | |
1633 | const bt_component_filter *component, | |
1634 | const bt_port_input *port, void *user_data); | |
1635 | ||
1636 | /*! | |
1637 | @brief | |
1638 | Adds a \"\bt_flt_comp \bt_iport added\" listener to the trace | |
1639 | processing graph \bt_p{graph}. | |
1640 | ||
1641 | Once this function returns, \bt_p{user_func} is called whenever a | |
1642 | filter component adds an input port within \bt_p{graph}. | |
1643 | ||
1644 | See \ref api-graph-listeners "Listeners" to learn more. | |
1645 | ||
1646 | @param[in] graph | |
1647 | Trace processing graph to add the "filter component input port | |
1648 | added" listener to. | |
1649 | @param[in] user_func | |
1650 | User function of the "filter component input port added" listener to | |
1651 | add to \bt_p{graph}. | |
1652 | @param[in] user_data | |
1653 | User data to pass as the \bt_p{user_data} parameter of | |
1654 | \bt_p{user_func}. | |
1655 | @param[out] listener_id | |
1656 | <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id} | |
1657 | is the ID of the added listener within \bt_p{graph}. | |
1658 | ||
1659 | @retval #BT_GRAPH_ADD_LISTENER_STATUS_OK | |
1660 | Success. | |
1661 | @retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR | |
1662 | Out of memory. | |
1663 | ||
1664 | @bt_pre_not_null{graph} | |
1665 | @bt_pre_graph_not_faulty{graph} | |
1666 | @bt_pre_not_null{user_func} | |
1667 | */ | |
d24d5663 PP |
1668 | extern bt_graph_add_listener_status |
1669 | bt_graph_add_filter_component_input_port_added_listener( | |
b19ff26f | 1670 | bt_graph *graph, |
43c59509 | 1671 | bt_graph_filter_component_input_port_added_listener_func user_func, |
4c81a2b7 | 1672 | void *user_data, bt_listener_id *listener_id) __BT_NOEXCEPT; |
43c59509 PP |
1673 | |
1674 | /*! | |
1675 | @brief | |
1676 | User function for | |
1677 | bt_graph_add_sink_component_input_port_added_listener(). | |
1678 | ||
1679 | Such a function is called whenever a \bt_sink_comp within a trace | |
1680 | processing graph adds an \bt_iport during the graph | |
1681 | \ref api-graph-lc "configuration" phase. | |
1682 | ||
1683 | See \ref api-graph-listeners "Listeners" to learn more. | |
1684 | ||
1685 | @param[in] component | |
1686 | Filter component which added \bt_p{port}. | |
1687 | @param[in] port | |
1688 | Input port added by \bt_p{component}. | |
1689 | @param[in] user_data | |
1690 | User data, as passed as the \bt_p{user_data} parameter of | |
1691 | bt_graph_add_sink_component_input_port_added_listener(). | |
1692 | ||
1693 | @retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK | |
1694 | Success. | |
1695 | @retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR | |
1696 | Out of memory. | |
1697 | @retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR | |
1698 | Other error. | |
1699 | ||
1700 | @bt_pre_not_null{component} | |
1701 | @bt_pre_not_null{port} | |
1702 | ||
1703 | @sa bt_graph_add_sink_component_input_port_added_listener() — | |
1704 | Adds a "sink component input port added" listener to a trace | |
1705 | processing graph. | |
1706 | */ | |
1707 | typedef bt_graph_listener_func_status | |
1708 | (*bt_graph_sink_component_input_port_added_listener_func)( | |
1709 | const bt_component_sink *component, | |
1710 | const bt_port_input *port, void *user_data); | |
1711 | ||
1712 | /*! | |
1713 | @brief | |
1714 | Adds a \"\bt_sink_comp \bt_iport added\" listener to the trace | |
1715 | processing graph \bt_p{graph}. | |
1716 | ||
1717 | Once this function returns, \bt_p{user_func} is called whenever a | |
1718 | sink component adds an input port within \bt_p{graph}. | |
1719 | ||
1720 | See \ref api-graph-listeners "Listeners" to learn more. | |
1721 | ||
1722 | @param[in] graph | |
1723 | Trace processing graph to add the "sink component input port | |
1724 | added" listener to. | |
1725 | @param[in] user_func | |
1726 | User function of the "sink component input port added" listener to | |
1727 | add to \bt_p{graph}. | |
1728 | @param[in] user_data | |
1729 | User data to pass as the \bt_p{user_data} parameter of | |
1730 | \bt_p{user_func}. | |
1731 | @param[out] listener_id | |
1732 | <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id} | |
1733 | is the ID of the added listener within \bt_p{graph}. | |
1734 | ||
1735 | @retval #BT_GRAPH_ADD_LISTENER_STATUS_OK | |
1736 | Success. | |
1737 | @retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR | |
1738 | Out of memory. | |
0d72b8c3 | 1739 | |
43c59509 PP |
1740 | @bt_pre_not_null{graph} |
1741 | @bt_pre_graph_not_faulty{graph} | |
1742 | @bt_pre_not_null{user_func} | |
1743 | */ | |
d24d5663 PP |
1744 | extern bt_graph_add_listener_status |
1745 | bt_graph_add_sink_component_input_port_added_listener( | |
b19ff26f | 1746 | bt_graph *graph, |
43c59509 | 1747 | bt_graph_sink_component_input_port_added_listener_func user_func, |
4c81a2b7 | 1748 | void *user_data, bt_listener_id *listener_id) __BT_NOEXCEPT; |
0d72b8c3 | 1749 | |
43c59509 PP |
1750 | /*! |
1751 | @brief | |
1752 | User function for | |
1753 | bt_graph_add_source_component_output_port_added_listener(). | |
1754 | ||
1755 | Such a function is called whenever a \bt_src_comp within a trace | |
1756 | processing graph adds an \bt_oport during the graph | |
1757 | \ref api-graph-lc "configuration" phase. | |
1758 | ||
1759 | See \ref api-graph-listeners "Listeners" to learn more. | |
1760 | ||
1761 | @param[in] component | |
1762 | Filter component which added \bt_p{port}. | |
1763 | @param[in] port | |
1764 | Input port added by \bt_p{component}. | |
1765 | @param[in] user_data | |
1766 | User data, as passed as the \bt_p{user_data} parameter of | |
1767 | bt_graph_add_source_component_output_port_added_listener(). | |
1768 | ||
1769 | @retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK | |
1770 | Success. | |
1771 | @retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR | |
1772 | Out of memory. | |
1773 | @retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR | |
1774 | Other error. | |
1775 | ||
1776 | @bt_pre_not_null{component} | |
1777 | @bt_pre_not_null{port} | |
1778 | ||
1779 | @sa bt_graph_add_source_component_output_port_added_listener() — | |
1780 | Adds a "source component output port added" listener to a trace | |
1781 | processing graph. | |
1782 | */ | |
1783 | typedef bt_graph_listener_func_status | |
1784 | (*bt_graph_source_component_output_port_added_listener_func)( | |
1785 | const bt_component_source *component, | |
1786 | const bt_port_output *port, void *user_data); | |
1787 | ||
1788 | /*! | |
1789 | @brief | |
1790 | Adds a \"\bt_src_comp \bt_oport added\" listener to the trace | |
1791 | processing graph \bt_p{graph}. | |
1792 | ||
1793 | Once this function returns, \bt_p{user_func} is called whenever a | |
1794 | source component adds an output port within \bt_p{graph}. | |
1795 | ||
1796 | See \ref api-graph-listeners "Listeners" to learn more. | |
1797 | ||
1798 | @param[in] graph | |
1799 | Trace processing graph to add the "source component output port | |
1800 | added" listener to. | |
1801 | @param[in] user_func | |
1802 | User function of the "source component output port added" listener | |
1803 | to add to \bt_p{graph}. | |
1804 | @param[in] user_data | |
1805 | User data to pass as the \bt_p{user_data} parameter of | |
1806 | \bt_p{user_func}. | |
1807 | @param[out] listener_id | |
1808 | <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id} | |
1809 | is the ID of the added listener within \bt_p{graph}. | |
1810 | ||
1811 | @retval #BT_GRAPH_ADD_LISTENER_STATUS_OK | |
1812 | Success. | |
1813 | @retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR | |
1814 | Out of memory. | |
1815 | ||
1816 | @bt_pre_not_null{graph} | |
1817 | @bt_pre_graph_not_faulty{graph} | |
1818 | @bt_pre_not_null{user_func} | |
1819 | */ | |
d24d5663 PP |
1820 | extern bt_graph_add_listener_status |
1821 | bt_graph_add_source_component_output_port_added_listener( | |
b19ff26f | 1822 | bt_graph *graph, |
43c59509 | 1823 | bt_graph_source_component_output_port_added_listener_func user_func, |
4c81a2b7 | 1824 | void *user_data, bt_listener_id *listener_id) __BT_NOEXCEPT; |
43c59509 PP |
1825 | |
1826 | /*! | |
1827 | @brief | |
1828 | User function for | |
1829 | bt_graph_add_filter_component_output_port_added_listener(). | |
1830 | ||
1831 | Such a function is called whenever a \bt_flt_comp within a trace | |
1832 | processing graph adds an \bt_oport during the graph | |
1833 | \ref api-graph-lc "configuration" phase. | |
1834 | ||
1835 | See \ref api-graph-listeners "Listeners" to learn more. | |
1836 | ||
1837 | @param[in] component | |
1838 | Filter component which added \bt_p{port}. | |
1839 | @param[in] port | |
1840 | Input port added by \bt_p{component}. | |
1841 | @param[in] user_data | |
1842 | User data, as passed as the \bt_p{user_data} parameter of | |
1843 | bt_graph_add_filter_component_output_port_added_listener(). | |
1844 | ||
1845 | @retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK | |
1846 | Success. | |
1847 | @retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR | |
1848 | Out of memory. | |
1849 | @retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR | |
1850 | Other error. | |
1851 | ||
1852 | @bt_pre_not_null{component} | |
1853 | @bt_pre_not_null{port} | |
1854 | ||
1855 | @sa bt_graph_add_filter_component_output_port_added_listener() — | |
1856 | Adds a "filter component output port added" listener to a trace | |
1857 | processing graph. | |
1858 | */ | |
1859 | typedef bt_graph_listener_func_status | |
1860 | (*bt_graph_filter_component_output_port_added_listener_func)( | |
1861 | const bt_component_filter *component, | |
1862 | const bt_port_output *port, void *user_data); | |
1863 | ||
1864 | /*! | |
1865 | @brief | |
1866 | Adds a \"\bt_flt_comp \bt_oport added\" listener to the trace | |
1867 | processing graph \bt_p{graph}. | |
1868 | ||
1869 | Once this function returns, \bt_p{user_func} is called whenever a | |
1870 | filter component adds an output port within \bt_p{graph}. | |
1871 | ||
1872 | See \ref api-graph-listeners "Listeners" to learn more. | |
0d72b8c3 | 1873 | |
43c59509 PP |
1874 | @param[in] graph |
1875 | Trace processing graph to add the "filter component output port | |
1876 | added" listener to. | |
1877 | @param[in] user_func | |
1878 | User function of the "filter component output port added" listener | |
1879 | to add to \bt_p{graph}. | |
1880 | @param[in] user_data | |
1881 | User data to pass as the \bt_p{user_data} parameter of | |
1882 | \bt_p{user_func}. | |
1883 | @param[out] listener_id | |
1884 | <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id} | |
1885 | is the ID of the added listener within \bt_p{graph}. | |
1886 | ||
1887 | @retval #BT_GRAPH_ADD_LISTENER_STATUS_OK | |
1888 | Success. | |
1889 | @retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR | |
1890 | Out of memory. | |
1891 | ||
1892 | @bt_pre_not_null{graph} | |
1893 | @bt_pre_graph_not_faulty{graph} | |
1894 | @bt_pre_not_null{user_func} | |
1895 | */ | |
d24d5663 PP |
1896 | extern bt_graph_add_listener_status |
1897 | bt_graph_add_filter_component_output_port_added_listener( | |
b19ff26f | 1898 | bt_graph *graph, |
43c59509 | 1899 | bt_graph_filter_component_output_port_added_listener_func user_func, |
4c81a2b7 | 1900 | void *user_data, bt_listener_id *listener_id) __BT_NOEXCEPT; |
0d72b8c3 | 1901 | |
43c59509 | 1902 | /*! @} */ |
d24d5663 | 1903 | |
43c59509 PP |
1904 | /*! |
1905 | @name Reference count | |
1906 | @{ | |
1907 | */ | |
9b4f9b42 | 1908 | |
43c59509 PP |
1909 | /*! |
1910 | @brief | |
1911 | Increments the \ref api-fund-shared-object "reference count" of | |
1912 | the trace processing graph \bt_p{graph}. | |
1913 | ||
1914 | @param[in] graph | |
1915 | @parblock | |
1916 | Trace processing graph of which to increment the reference count. | |
1917 | ||
1918 | Can be \c NULL. | |
1919 | @endparblock | |
1920 | ||
1921 | @sa bt_graph_put_ref() — | |
1922 | Decrements the reference count of a trace processing graph. | |
1923 | */ | |
4c81a2b7 | 1924 | extern void bt_graph_get_ref(const bt_graph *graph) __BT_NOEXCEPT; |
43c59509 PP |
1925 | |
1926 | /*! | |
1927 | @brief | |
1928 | Decrements the \ref api-fund-shared-object "reference count" of | |
1929 | the trace processing graph \bt_p{graph}. | |
1930 | ||
1931 | @param[in] graph | |
1932 | @parblock | |
1933 | Trace processing graph of which to decrement the reference count. | |
1934 | ||
1935 | Can be \c NULL. | |
1936 | @endparblock | |
1937 | ||
1938 | @sa bt_graph_get_ref() — | |
1939 | Increments the reference count of a trace processing graph. | |
1940 | */ | |
4c81a2b7 | 1941 | extern void bt_graph_put_ref(const bt_graph *graph) __BT_NOEXCEPT; |
43c59509 PP |
1942 | |
1943 | /*! | |
1944 | @brief | |
1945 | Decrements the reference count of the trace processing graph | |
1946 | \bt_p{_graph}, and then sets \bt_p{_graph} to \c NULL. | |
1947 | ||
1948 | @param _graph | |
1949 | @parblock | |
1950 | Trace processing graph of which to decrement the reference count. | |
1951 | ||
1952 | Can contain \c NULL. | |
1953 | @endparblock | |
1954 | ||
1955 | @bt_pre_assign_expr{_graph} | |
1956 | */ | |
1957 | #define BT_GRAPH_PUT_REF_AND_RESET(_graph) \ | |
1958 | do { \ | |
1959 | bt_graph_put_ref(_graph); \ | |
1960 | (_graph) = NULL; \ | |
1961 | } while (0) | |
1962 | ||
1963 | /*! | |
1964 | @brief | |
1965 | Decrements the reference count of the trace processing graph | |
1966 | \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets | |
1967 | \bt_p{_src} to \c NULL. | |
1968 | ||
1969 | This macro effectively moves a trace processing graph reference from the | |
1970 | expression \bt_p{_src} to the expression \bt_p{_dst}, putting the | |
1971 | existing \bt_p{_dst} reference. | |
1972 | ||
1973 | @param _dst | |
1974 | @parblock | |
1975 | Destination expression. | |
1976 | ||
1977 | Can contain \c NULL. | |
1978 | @endparblock | |
1979 | @param _src | |
1980 | @parblock | |
1981 | Source expression. | |
1982 | ||
1983 | Can contain \c NULL. | |
1984 | @endparblock | |
1985 | ||
1986 | @bt_pre_assign_expr{_dst} | |
1987 | @bt_pre_assign_expr{_src} | |
1988 | */ | |
1989 | #define BT_GRAPH_MOVE_REF(_dst, _src) \ | |
1990 | do { \ | |
1991 | bt_graph_put_ref(_dst); \ | |
1992 | (_dst) = (_src); \ | |
1993 | (_src) = NULL; \ | |
1994 | } while (0) | |
1995 | ||
1996 | /*! @} */ | |
1997 | ||
1998 | /*! @} */ | |
202a3a13 | 1999 | |
c0418dd9 JG |
2000 | #ifdef __cplusplus |
2001 | } | |
2002 | #endif | |
2003 | ||
924dc299 | 2004 | #endif /* BABELTRACE2_GRAPH_GRAPH_H */ |