include/babeltrace2/graph/port.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
   5  */
   6
   7 #ifndef BABELTRACE2_GRAPH_PORT_H
   8 #define BABELTRACE2_GRAPH_PORT_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 <stdint.h>
  17
  18 #include <babeltrace2/types.h>
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 /*!
  25 @defgroup api-port Ports
  26 @ingroup api-comp
  27
  28 @brief
  29     \bt_c_comp input and output ports.
  30
  31 A <strong><em>port</em></strong> is a point of \bt_conn between
  32 \bt_p_comp:
  33
  34 @image html component-zoom.png
  35
  36 A port is a \ref api-fund-shared-object "shared object": get a new
  37 reference with bt_port_get_ref() and put an existing reference with
  38 bt_port_put_ref().
  39
  40 The common C&nbsp;type of a port is #bt_port.
  41
  42 There are two types of ports:
  43
  44 <dl>
  45   <dt>\anchor api-port-in Input port</dt>
  46   <dd>
  47     Input connection point from which \bt_p_msg are received.
  48
  49     Filter and sink components have input ports.
  50
  51     An input port's specific type is #bt_port_input and its type
  52     enumerator is #BT_PORT_TYPE_INPUT.
  53
  54     \ref api-fund-c-typing "Upcast" the #bt_port_input type to the
  55     #bt_port type with bt_port_input_as_port_const().
  56
  57     Get a new input port reference with bt_port_input_get_ref() and put
  58     an existing one with bt_port_input_put_ref().
  59   </dd>
  60
  61   <dt>\anchor api-port-out Output port</dt>
  62   <dd>
  63     Output connection point to which messages are sent.
  64
  65     Source and filter components have output ports.
  66
  67     An output port's specific type is #bt_port_output and its type
  68     enumerator is #BT_PORT_TYPE_OUTPUT.
  69
  70     \ref api-fund-c-typing "Upcast" the #bt_port_output type to the
  71     #bt_port type with bt_port_output_as_port_const().
  72
  73     Get a new output port reference with bt_port_output_get_ref() and
  74     put an existing one with bt_port_output_put_ref().
  75   </dd>
  76 </dl>
  77
  78 Get a port's type enumerator with bt_port_get_type(). You can also use
  79 the bt_port_is_input() and bt_port_is_output() helper functions.
  80
  81 A \bt_comp can add a port with:
  82
  83 - bt_self_component_source_add_output_port()
  84 - bt_self_component_filter_add_input_port()
  85 - bt_self_component_filter_add_output_port()
  86 - bt_self_component_sink_add_input_port()
  87
  88 Borrow a port's \bt_conn, if any, with
  89 bt_port_borrow_connection_const().
  90
  91 Borrow the component to which a port belongs with
  92 bt_port_borrow_component_const().
  93
  94 <h1>Properties</h1>
  95
  96 A port has the following common properties:
  97
  98 <dl>
  99   <dt>
 100     \anchor api-port-prop-name
 101     Name
 102   </dt>
 103   <dd>
 104     Name of the port.
 105
 106     For a given \bt_comp:
 107
 108     - Each input port has a unique name.
 109     - Each output port has a unique name.
 110
 111     A port's name is set when the component adds it; you cannot change
 112     it afterwards.
 113
 114     Get a port's name with bt_port_get_name().
 115   </dd>
 116
 117   <dt>
 118     \anchor api-port-prop-is-connected
 119     Is connected?
 120   </dt>
 121   <dd>
 122     Whether or not the port is currently connected to another port.
 123
 124     Get whether or not a port is connected with bt_port_is_connected().
 125
 126     When a port is unconnected, bt_port_borrow_connection_const()
 127     returns \c NULL.
 128   </dd>
 129 </dl>
 130 */
 131
 132 /*! @{ */
 133
 134 /*!
 135 @name Types
 136 @{
 137
 138 @typedef struct bt_port bt_port;
 139
 140 @brief
 141     Port.
 142
 143 @typedef struct bt_port_input bt_port_input;
 144
 145 @brief
 146     \bt_c_iport.
 147
 148 @typedef struct bt_port_output bt_port_output;
 149
 150 @brief
 151     \bt_c_oport.
 152
 153 @}
 154 */
 155
 156 /*!
 157 @name Type query
 158 @{
 159 */
 160
 161 /*!
 162 @brief
 163     Port type enumerators.
 164 */
 165 typedef enum bt_port_type {
 166         /*!
 167         @brief
 168             \bt_c_iport.
 169         */
 170         BT_PORT_TYPE_INPUT      = 1 << 0,
 171
 172         /*!
 173         @brief
 174             \bt_c_oport.
 175         */
 176         BT_PORT_TYPE_OUTPUT     = 1 << 1,
 177 } bt_port_type;
 178
 179 /*!
 180 @brief
 181     Returns the type enumerator of the port \bt_p{port}.
 182
 183 @param[in] port
 184     Port of which to get the type enumerator
 185
 186 @returns
 187     Type enumerator of \bt_p{port}.
 188
 189 @bt_pre_not_null{port}
 190
 191 @sa bt_port_is_input() &mdash;
 192     Returns whether or not a port is an \bt_iport.
 193 @sa bt_port_is_output() &mdash;
 194     Returns whether or not a port is an \bt_oport.
 195 */
 196 extern bt_port_type bt_port_get_type(const bt_port *port) __BT_NOEXCEPT;
 197
 198 /*!
 199 @brief
 200     Returns whether or not the port \bt_p{port} is an \bt_iport.
 201
 202 @param[in] port
 203     Port to check.
 204
 205 @returns
 206     #BT_TRUE if \bt_p{port} is an input port.
 207
 208 @bt_pre_not_null{port}
 209
 210 @sa bt_port_get_type() &mdash;
 211     Returns the type enumerator of a port.
 212 */
 213 static inline
 214 bt_bool bt_port_is_input(const bt_port *port) __BT_NOEXCEPT
 215 {
 216         return bt_port_get_type(port) == BT_PORT_TYPE_INPUT;
 217 }
 218
 219 /*!
 220 @brief
 221     Returns whether or not the port \bt_p{port} is an \bt_oport.
 222
 223 @param[in] port
 224     Port to check.
 225
 226 @returns
 227     #BT_TRUE if \bt_p{port} is an output port.
 228
 229 @bt_pre_not_null{port}
 230
 231 @sa bt_port_get_type() &mdash;
 232     Returns the type enumerator of a port.
 233 */
 234 static inline
 235 bt_bool bt_port_is_output(const bt_port *port) __BT_NOEXCEPT
 236 {
 237         return bt_port_get_type(port) == BT_PORT_TYPE_OUTPUT;
 238 }
 239
 240 /*! @} */
 241
 242 /*!
 243 @name Connection access
 244 @{
 245 */
 246
 247 /*!
 248 @brief
 249     Borrows the \bt_conn of the port \bt_p{port}.
 250
 251 This function returns \c NULL if \bt_p{port} is unconnected
 252 (bt_port_is_connected() returns #BT_FALSE).
 253
 254 @param[in] port
 255     Port of which to borrow the connection.
 256
 257 @returns
 258     \em Borrowed reference of the connection of \bt_p{port}.
 259
 260 @bt_pre_not_null{port}
 261 */
 262 extern const bt_connection *bt_port_borrow_connection_const(
 263                 const bt_port *port) __BT_NOEXCEPT;
 264
 265 /*! @} */
 266
 267 /*!
 268 @name Component access
 269 @{
 270 */
 271
 272 /*!
 273 @brief
 274     Borrows the \bt_comp to which the port \bt_p{port} belongs.
 275
 276 @param[in] port
 277     Port of which to borrow the component which owns it.
 278
 279 @returns
 280     \em Borrowed reference of the component which owns \bt_p{port}.
 281
 282 @bt_pre_not_null{port}
 283 */
 284 extern const bt_component *bt_port_borrow_component_const(
 285                 const bt_port *port) __BT_NOEXCEPT;
 286
 287 /*! @} */
 288
 289 /*!
 290 @name Properties
 291 @{
 292 */
 293
 294 /*!
 295 @brief
 296     Returns the name of the port \bt_p{port}.
 297
 298 See the \ref api-port-prop-name "name" property.
 299
 300 @param[in] port
 301     Port of which to get the name.
 302
 303 @returns
 304     @parblock
 305     Name of \bt_p{port}, or \c NULL if none.
 306
 307     The returned pointer remains valid as long as \bt_p{port} exists.
 308     @endparblock
 309
 310 @bt_pre_not_null{port}
 311 */
 312 extern const char *bt_port_get_name(const bt_port *port) __BT_NOEXCEPT;
 313
 314 /*!
 315 @brief
 316     Returns whether or not the port \bt_p{port} is connected.
 317
 318 See the \ref api-port-prop-is-connected "is connected?" property.
 319
 320 @param[in] port
 321     Port of which to get whether or not it's connected.
 322
 323 @returns
 324     #BT_TRUE if \bt_p{port} is connected.
 325
 326 @bt_pre_not_null{port}
 327 */
 328 extern bt_bool bt_port_is_connected(const bt_port *port) __BT_NOEXCEPT;
 329
 330 /*! @} */
 331
 332 /*!
 333 @name Reference count (common)
 334 @{
 335 */
 336
 337 /*!
 338 @brief
 339     Increments the \ref api-fund-shared-object "reference count" of
 340     the port \bt_p{port}.
 341
 342 @param[in] port
 343     @parblock
 344     Port of which to increment the reference count.
 345
 346     Can be \c NULL.
 347     @endparblock
 348
 349 @sa bt_port_put_ref() &mdash;
 350     Decrements the reference count of a port.
 351 */
 352 extern void bt_port_get_ref(const bt_port *port) __BT_NOEXCEPT;
 353
 354 /*!
 355 @brief
 356     Decrements the \ref api-fund-shared-object "reference count" of
 357     the port \bt_p{port}.
 358
 359 @param[in] port
 360     @parblock
 361     Port of which to decrement the reference count.
 362
 363     Can be \c NULL.
 364     @endparblock
 365
 366 @sa bt_port_get_ref() &mdash;
 367     Increments the reference count of a port.
 368 */
 369 extern void bt_port_put_ref(const bt_port *port) __BT_NOEXCEPT;
 370
 371 /*!
 372 @brief
 373     Decrements the reference count of the port
 374     \bt_p{_port}, and then sets \bt_p{_port} to \c NULL.
 375
 376 @param _port
 377     @parblock
 378     Port of which to decrement the reference count.
 379
 380     Can contain \c NULL.
 381     @endparblock
 382
 383 @bt_pre_assign_expr{_port}
 384 */
 385 #define BT_PORT_PUT_REF_AND_RESET(_port)        \
 386         do {                                    \
 387                 bt_port_put_ref(_port);         \
 388                 (_port) = NULL;                 \
 389         } while (0)
 390
 391 /*!
 392 @brief
 393     Decrements the reference count of the port \bt_p{_dst}, sets
 394     \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
 395
 396 This macro effectively moves a port reference from the
 397 expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
 398 existing \bt_p{_dst} reference.
 399
 400 @param _dst
 401     @parblock
 402     Destination expression.
 403
 404     Can contain \c NULL.
 405     @endparblock
 406 @param _src
 407     @parblock
 408     Source expression.
 409
 410     Can contain \c NULL.
 411     @endparblock
 412
 413 @bt_pre_assign_expr{_dst}
 414 @bt_pre_assign_expr{_src}
 415 */
 416 #define BT_PORT_MOVE_REF(_dst, _src)    \
 417         do {                            \
 418                 bt_port_put_ref(_dst);  \
 419                 (_dst) = (_src);        \
 420                 (_src) = NULL;          \
 421         } while (0)
 422
 423 /*! @} */
 424
 425 /*!
 426 @name Input port
 427 @{
 428 */
 429
 430 /*!
 431 @brief
 432     \ref api-fund-c-typing "Upcasts" the \bt_iport \bt_p{port} to the
 433     common #bt_port type.
 434
 435 @param[in] port
 436     @parblock
 437     Input port to upcast.
 438
 439     Can be \c NULL.
 440     @endparblock
 441
 442 @returns
 443     \bt_p{port} as a common port.
 444 */
 445 static inline
 446 const bt_port *bt_port_input_as_port_const(
 447                 const bt_port_input *port) __BT_NOEXCEPT
 448 {
 449         return __BT_UPCAST_CONST(bt_port, port);
 450 }
 451
 452 /*!
 453 @brief
 454     Increments the \ref api-fund-shared-object "reference count" of
 455     the \bt_iport \bt_p{port}.
 456
 457 @param[in] port
 458     @parblock
 459     Input port of which to increment the reference count.
 460
 461     Can be \c NULL.
 462     @endparblock
 463
 464 @sa bt_port_input_put_ref() &mdash;
 465     Decrements the reference count of an input port.
 466 */
 467 extern void bt_port_input_get_ref(const bt_port_input *port) __BT_NOEXCEPT;
 468
 469 /*!
 470 @brief
 471     Decrements the \ref api-fund-shared-object "reference count" of
 472     the \bt_iport \bt_p{port}.
 473
 474 @param[in] port
 475     @parblock
 476     Input port of which to decrement the reference count.
 477
 478     Can be \c NULL.
 479     @endparblock
 480
 481 @sa bt_port_input_get_ref() &mdash;
 482     Increments the reference count of an input port.
 483 */
 484 extern void bt_port_input_put_ref(const bt_port_input *port) __BT_NOEXCEPT;
 485
 486 /*!
 487 @brief
 488     Decrements the reference count of the \bt_iport
 489     \bt_p{_port}, and then sets \bt_p{_port} to \c NULL.
 490
 491 @param _port
 492     @parblock
 493     Input port of which to decrement the reference count.
 494
 495     Can contain \c NULL.
 496     @endparblock
 497
 498 @bt_pre_assign_expr{_port}
 499 */
 500 #define BT_PORT_INPUT_PUT_REF_AND_RESET(_port)          \
 501         do {                                            \
 502                 bt_port_input_put_ref(_port);           \
 503                 (_port) = NULL;                         \
 504         } while (0)
 505
 506 /*!
 507 @brief
 508     Decrements the reference count of the \bt_iport \bt_p{_dst}, sets
 509     \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
 510
 511 This macro effectively moves an \bt_iport reference from the
 512 expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
 513 existing \bt_p{_dst} reference.
 514
 515 @param _dst
 516     @parblock
 517     Destination expression.
 518
 519     Can contain \c NULL.
 520     @endparblock
 521 @param _src
 522     @parblock
 523     Source expression.
 524
 525     Can contain \c NULL.
 526     @endparblock
 527
 528 @bt_pre_assign_expr{_dst}
 529 @bt_pre_assign_expr{_src}
 530 */
 531 #define BT_PORT_INPUT_MOVE_REF(_dst, _src)      \
 532         do {                                    \
 533                 bt_port_input_put_ref(_dst);    \
 534                 (_dst) = (_src);                \
 535                 (_src) = NULL;                  \
 536         } while (0)
 537
 538 /*! @} */
 539
 540 /*!
 541 @name Output port
 542 @{
 543 */
 544
 545 /*!
 546 @brief
 547     \ref api-fund-c-typing "Upcasts" the \bt_oport \bt_p{port} to the
 548     common #bt_port type.
 549
 550 @param[in] port
 551     @parblock
 552     Output port to upcast.
 553
 554     Can be \c NULL.
 555     @endparblock
 556
 557 @returns
 558     \bt_p{port} as a common port.
 559 */
 560 static inline
 561 const bt_port *bt_port_output_as_port_const(
 562                 const bt_port_output *port) __BT_NOEXCEPT
 563 {
 564         return __BT_UPCAST_CONST(bt_port, port);
 565 }
 566
 567 /*!
 568 @brief
 569     Increments the \ref api-fund-shared-object "reference count" of
 570     the \bt_oport \bt_p{port}.
 571
 572 @param[in] port
 573     @parblock
 574     Output port of which to increment the reference count.
 575
 576     Can be \c NULL.
 577     @endparblock
 578
 579 @sa bt_port_output_put_ref() &mdash;
 580     Decrements the reference count of a \bt_oport.
 581 */
 582 extern void bt_port_output_get_ref(const bt_port_output *port) __BT_NOEXCEPT;
 583
 584 /*!
 585 @brief
 586     Decrements the \ref api-fund-shared-object "reference count" of
 587     the \bt_oport \bt_p{port}.
 588
 589 @param[in] port
 590     @parblock
 591     Output port of which to decrement the reference count.
 592
 593     Can be \c NULL.
 594     @endparblock
 595
 596 @sa bt_port_output_get_ref() &mdash;
 597     Increments the reference count of a \bt_oport.
 598 */
 599 extern void bt_port_output_put_ref(const bt_port_output *port) __BT_NOEXCEPT;
 600
 601 /*!
 602 @brief
 603     Decrements the reference count of the \bt_oport
 604     \bt_p{_port}, and then sets \bt_p{_port} to \c NULL.
 605
 606 @param _port
 607     @parblock
 608     Output port of which to decrement the reference count.
 609
 610     Can contain \c NULL.
 611     @endparblock
 612
 613 @bt_pre_assign_expr{_port}
 614 */
 615 #define BT_PORT_OUTPUT_PUT_REF_AND_RESET(_port)         \
 616         do {                                            \
 617                 bt_port_output_put_ref(_port);          \
 618                 (_port) = NULL;                         \
 619         } while (0)
 620
 621 /*!
 622 @brief
 623     Decrements the reference count of the \bt_oport \bt_p{_dst}, sets
 624     \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
 625
 626 This macro effectively moves an \bt_oport reference from the
 627 expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
 628 existing \bt_p{_dst} reference.
 629
 630 @param _dst
 631     @parblock
 632     Destination expression.
 633
 634     Can contain \c NULL.
 635     @endparblock
 636 @param _src
 637     @parblock
 638     Source expression.
 639
 640     Can contain \c NULL.
 641     @endparblock
 642
 643 @bt_pre_assign_expr{_dst}
 644 @bt_pre_assign_expr{_src}
 645 */
 646 #define BT_PORT_OUTPUT_MOVE_REF(_dst, _src)     \
 647         do {                                    \
 648                 bt_port_output_put_ref(_dst);   \
 649                 (_dst) = (_src);                \
 650                 (_src) = NULL;                  \
 651         } while (0)
 652
 653 /*! @} */
 654
 655 /*! @} */
 656
 657 #ifdef __cplusplus
 658 }
 659 #endif
 660
 661 #endif /* BABELTRACE2_GRAPH_PORT_H */