include/babeltrace2/graph/graph.h

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