include/babeltrace2/graph/graph.h

   1 #ifndef BABELTRACE2_GRAPH_GRAPH_H
   2 #define BABELTRACE2_GRAPH_GRAPH_H
   3
   4 /*
   5  * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
   6  *
   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
  26 #ifndef __BT_IN_BABELTRACE_H
  27 # error "Please include <babeltrace2/babeltrace.h> instead."
  28 #endif
  29
  30 #include <babeltrace2/types.h>
  31 #include <babeltrace2/logging.h>
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 /*!
  38 @defgroup api-graph Graph
  39
  40 @brief
  41     Trace processing graph.
  42
  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.
  46
  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.
  50
  51 The following illustration shows a basic trace processing graph which
  52 converts many traces to a single log of pretty-printed lines:
  53
  54 @image html basic-convert-graph.png "Basic trace processing graph (conversion graph)."
  55
  56 In the illustrations above, notice that:
  57
  58 - The graph (blue) contains five components.
  59
  60 - Three source components (green) are connected to a single filter
  61   component (yellow).
  62
  63   There are five \bt_p_conn, from five \bt_p_oport
  64   to five \bt_p_iport.
  65
  66 - The filter component is connected to a single sink component (red).
  67
  68   There's a single connection.
  69
  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&nbsp;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&nbsp;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>
 351
 352 The \bt_name project ships with project \bt_p_plugin which provide
 353 "standard" \bt_p_comp_cls.
 354
 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&nbsp;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 */
 577 extern bt_graph *bt_graph_create(uint64_t mip_version);
 578
 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 */
 591 typedef enum bt_graph_add_component_status {
 592         /*!
 593         @brief
 594             Success.
 595         */
 596         BT_GRAPH_ADD_COMPONENT_STATUS_OK                = __BT_FUNC_STATUS_OK,
 597
 598         /*!
 599         @brief
 600             Out of memory.
 601         */
 602         BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
 603
 604         /*!
 605         @brief
 606             Other error.
 607         */
 608         BT_GRAPH_ADD_COMPONENT_STATUS_ERROR             = __BT_FUNC_STATUS_ERROR,
 609 } bt_graph_add_component_status;
 610
 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 */
 616 extern bt_graph_add_component_status
 617 bt_graph_add_source_component(bt_graph *graph,
 618                 const bt_component_class_source *component_class,
 619                 const char *name, const bt_value *params,
 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.
 692
 693 @bt_post_success_frozen{component_class}
 694 @bt_post_success_frozen{params}
 695 */
 696 extern bt_graph_add_component_status
 697 bt_graph_add_source_component_with_initialize_method_data(
 698                 bt_graph *graph,
 699                 const bt_component_class_source *component_class,
 700                 const char *name, const bt_value *params,
 701                 void *initialize_method_data, bt_logging_level logging_level,
 702                 const bt_component_source **component);
 703
 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 */
 709 extern bt_graph_add_component_status
 710 bt_graph_add_filter_component(bt_graph *graph,
 711                 const bt_component_class_filter *component_class,
 712                 const char *name, const bt_value *params,
 713                 bt_logging_level logging_level,
 714                 const bt_component_filter **component);
 715
 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 */
 789 extern bt_graph_add_component_status
 790 bt_graph_add_filter_component_with_initialize_method_data(
 791                 bt_graph *graph,
 792                 const bt_component_class_filter *component_class,
 793                 const char *name, const bt_value *params,
 794                 void *initialize_method_data, bt_logging_level logging_level,
 795                 const bt_component_filter **component);
 796
 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 */
 802 extern bt_graph_add_component_status
 803 bt_graph_add_sink_component(
 804                 bt_graph *graph, const bt_component_class_sink *component_class,
 805                 const char *name, const bt_value *params,
 806                 bt_logging_level logging_level,
 807                 const bt_component_sink **component);
 808
 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 */
 882 extern bt_graph_add_component_status
 883 bt_graph_add_sink_component_with_initialize_method_data(
 884                 bt_graph *graph, const bt_component_class_sink *component_class,
 885                 const char *name, const bt_value *params,
 886                 void *initialize_method_data, bt_logging_level logging_level,
 887                 const bt_component_sink **component);
 888
 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() &mdash;
 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() &mdash;
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() &mdash;
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 */
1142 extern bt_graph_add_component_status
1143 bt_graph_add_simple_sink_component(bt_graph *graph, const char *name,
1144                 bt_graph_simple_sink_component_initialize_func initialize_func,
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
1149 /*! @} */
1150
1151 /*!
1152 @name Component port connection
1153 @{
1154 */
1155
1156 /*!
1157 @brief
1158     Status codes for bt_graph_connect_ports().
1159 */
1160 typedef enum bt_graph_connect_ports_status {
1161         /*!
1162         @brief
1163             Success.
1164         */
1165         BT_GRAPH_CONNECT_PORTS_STATUS_OK                = __BT_FUNC_STATUS_OK,
1166
1167         /*!
1168         @brief
1169             Out of memory.
1170         */
1171         BT_GRAPH_CONNECT_PORTS_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
1172
1173         /*!
1174         @brief
1175             Other error.
1176         */
1177         BT_GRAPH_CONNECT_PORTS_STATUS_ERROR             = __BT_FUNC_STATUS_ERROR,
1178 } bt_graph_connect_ports_status;
1179
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 */
1233 extern bt_graph_connect_ports_status bt_graph_connect_ports(bt_graph *graph,
1234                 const bt_port_output *upstream_port,
1235                 const bt_port_input *downstream_port,
1236                 const bt_connection **connection);
1237
1238 /*! @} */
1239
1240 /*!
1241 @name Running
1242 @{
1243 */
1244
1245 /*!
1246 @brief
1247     Status codes for bt_graph_run().
1248 */
1249 typedef enum bt_graph_run_status {
1250         /*!
1251         @brief
1252             Success.
1253         */
1254         BT_GRAPH_RUN_STATUS_OK                  = __BT_FUNC_STATUS_OK,
1255
1256         /*!
1257         @brief
1258             Try again.
1259         */
1260         BT_GRAPH_RUN_STATUS_AGAIN               = __BT_FUNC_STATUS_AGAIN,
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,
1273 } bt_graph_run_status;
1274
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() &mdash;
1349     Calls a single trace processing graph's sink component's consuming
1350     method once.
1351 */
1352 extern bt_graph_run_status bt_graph_run(bt_graph *graph);
1353
1354 /*!
1355 @brief
1356     Status codes for bt_graph_run().
1357 */
1358 typedef enum bt_graph_run_once_status {
1359         /*!
1360         @brief
1361             Success.
1362         */
1363         BT_GRAPH_RUN_ONCE_STATUS_OK             = __BT_FUNC_STATUS_OK,
1364
1365         /*!
1366         @brief
1367             All sink components are finished processing.
1368         */
1369         BT_GRAPH_RUN_ONCE_STATUS_END            = __BT_FUNC_STATUS_END,
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,
1388 } bt_graph_run_once_status;
1389
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() &mdash;
1457     Runs a trace processing graph, making all its sink components
1458     consume in a round robin fashion.
1459 */
1460 extern bt_graph_run_once_status bt_graph_run_once(bt_graph *graph);
1461
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() &mdash;
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() &mdash;
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 */
1571 typedef enum bt_graph_add_listener_status {
1572         /*!
1573         @brief
1574             Success.
1575         */
1576         BT_GRAPH_ADD_LISTENER_STATUS_OK                 = __BT_FUNC_STATUS_OK,
1577
1578         /*!
1579         @brief
1580             Out of memory.
1581         */
1582         BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR       = __BT_FUNC_STATUS_MEMORY_ERROR,
1583 } bt_graph_add_listener_status;
1584
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() &mdash;
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 */
1681 extern bt_graph_add_listener_status
1682 bt_graph_add_filter_component_input_port_added_listener(
1683                 bt_graph *graph,
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() &mdash;
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.
1752
1753 @bt_pre_not_null{graph}
1754 @bt_pre_graph_not_faulty{graph}
1755 @bt_pre_not_null{user_func}
1756 */
1757 extern bt_graph_add_listener_status
1758 bt_graph_add_sink_component_input_port_added_listener(
1759                 bt_graph *graph,
1760                 bt_graph_sink_component_input_port_added_listener_func user_func,
1761                 void *user_data, bt_listener_id *listener_id);
1762
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() &mdash;
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 */
1833 extern bt_graph_add_listener_status
1834 bt_graph_add_source_component_output_port_added_listener(
1835                 bt_graph *graph,
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() &mdash;
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.
1886
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 */
1909 extern bt_graph_add_listener_status
1910 bt_graph_add_filter_component_output_port_added_listener(
1911                 bt_graph *graph,
1912                 bt_graph_filter_component_output_port_added_listener_func user_func,
1913                 void *user_data, bt_listener_id *listener_id);
1914
1915 /*! @} */
1916
1917 /*!
1918 @name Reference count
1919 @{
1920 */
1921
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() &mdash;
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() &mdash;
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 /*! @} */
2012
2013 #ifdef __cplusplus
2014 }
2015 #endif
2016
2017 #endif /* BABELTRACE2_GRAPH_GRAPH_H */