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