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);
 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)
 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)
 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);
 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);
 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);
 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);
 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);
 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);
 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(const bt_port_input *port)
 447 {
 448         return __BT_UPCAST_CONST(bt_port, port);
 449 }
 450
 451 /*!
 452 @brief
 453     Increments the \ref api-fund-shared-object "reference count" of
 454     the \bt_iport \bt_p{port}.
 455
 456 @param[in] port
 457     @parblock
 458     Input port of which to increment the reference count.
 459
 460     Can be \c NULL.
 461     @endparblock
 462
 463 @sa bt_port_input_put_ref() &mdash;
 464     Decrements the reference count of an input port.
 465 */
 466 extern void bt_port_input_get_ref(const bt_port_input *port);
 467
 468 /*!
 469 @brief
 470     Decrements the \ref api-fund-shared-object "reference count" of
 471     the \bt_iport \bt_p{port}.
 472
 473 @param[in] port
 474     @parblock
 475     Input port of which to decrement the reference count.
 476
 477     Can be \c NULL.
 478     @endparblock
 479
 480 @sa bt_port_input_get_ref() &mdash;
 481     Increments the reference count of an input port.
 482 */
 483 extern void bt_port_input_put_ref(const bt_port_input *port);
 484
 485 /*!
 486 @brief
 487     Decrements the reference count of the \bt_iport
 488     \bt_p{_port}, and then sets \bt_p{_port} to \c NULL.
 489
 490 @param _port
 491     @parblock
 492     Input port of which to decrement the reference count.
 493
 494     Can contain \c NULL.
 495     @endparblock
 496
 497 @bt_pre_assign_expr{_port}
 498 */
 499 #define BT_PORT_INPUT_PUT_REF_AND_RESET(_port)          \
 500         do {                                            \
 501                 bt_port_input_put_ref(_port);           \
 502                 (_port) = NULL;                         \
 503         } while (0)
 504
 505 /*!
 506 @brief
 507     Decrements the reference count of the \bt_iport \bt_p{_dst}, sets
 508     \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
 509
 510 This macro effectively moves an \bt_iport reference from the
 511 expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
 512 existing \bt_p{_dst} reference.
 513
 514 @param _dst
 515     @parblock
 516     Destination expression.
 517
 518     Can contain \c NULL.
 519     @endparblock
 520 @param _src
 521     @parblock
 522     Source expression.
 523
 524     Can contain \c NULL.
 525     @endparblock
 526
 527 @bt_pre_assign_expr{_dst}
 528 @bt_pre_assign_expr{_src}
 529 */
 530 #define BT_PORT_INPUT_MOVE_REF(_dst, _src)      \
 531         do {                                    \
 532                 bt_port_input_put_ref(_dst);    \
 533                 (_dst) = (_src);                \
 534                 (_src) = NULL;                  \
 535         } while (0)
 536
 537 /*! @} */
 538
 539 /*!
 540 @name Output port
 541 @{
 542 */
 543
 544 /*!
 545 @brief
 546     \ref api-fund-c-typing "Upcasts" the \bt_oport \bt_p{port} to the
 547     common #bt_port type.
 548
 549 @param[in] port
 550     @parblock
 551     Output port to upcast.
 552
 553     Can be \c NULL.
 554     @endparblock
 555
 556 @returns
 557     \bt_p{port} as a common port.
 558 */
 559 static inline
 560 const bt_port *bt_port_output_as_port_const(const bt_port_output *port)
 561 {
 562         return __BT_UPCAST_CONST(bt_port, port);
 563 }
 564
 565 /*!
 566 @brief
 567     Increments the \ref api-fund-shared-object "reference count" of
 568     the \bt_oport \bt_p{port}.
 569
 570 @param[in] port
 571     @parblock
 572     Output port of which to increment the reference count.
 573
 574     Can be \c NULL.
 575     @endparblock
 576
 577 @sa bt_port_output_put_ref() &mdash;
 578     Decrements the reference count of a \bt_oport.
 579 */
 580 extern void bt_port_output_get_ref(const bt_port_output *port);
 581
 582 /*!
 583 @brief
 584     Decrements the \ref api-fund-shared-object "reference count" of
 585     the \bt_oport \bt_p{port}.
 586
 587 @param[in] port
 588     @parblock
 589     Output port of which to decrement the reference count.
 590
 591     Can be \c NULL.
 592     @endparblock
 593
 594 @sa bt_port_output_get_ref() &mdash;
 595     Increments the reference count of a \bt_oport.
 596 */
 597 extern void bt_port_output_put_ref(const bt_port_output *port);
 598
 599 /*!
 600 @brief
 601     Decrements the reference count of the \bt_oport
 602     \bt_p{_port}, and then sets \bt_p{_port} to \c NULL.
 603
 604 @param _port
 605     @parblock
 606     Output port of which to decrement the reference count.
 607
 608     Can contain \c NULL.
 609     @endparblock
 610
 611 @bt_pre_assign_expr{_port}
 612 */
 613 #define BT_PORT_OUTPUT_PUT_REF_AND_RESET(_port)         \
 614         do {                                            \
 615                 bt_port_output_put_ref(_port);          \
 616                 (_port) = NULL;                         \
 617         } while (0)
 618
 619 /*!
 620 @brief
 621     Decrements the reference count of the \bt_oport \bt_p{_dst}, sets
 622     \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
 623
 624 This macro effectively moves an \bt_oport reference from the
 625 expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
 626 existing \bt_p{_dst} reference.
 627
 628 @param _dst
 629     @parblock
 630     Destination expression.
 631
 632     Can contain \c NULL.
 633     @endparblock
 634 @param _src
 635     @parblock
 636     Source expression.
 637
 638     Can contain \c NULL.
 639     @endparblock
 640
 641 @bt_pre_assign_expr{_dst}
 642 @bt_pre_assign_expr{_src}
 643 */
 644 #define BT_PORT_OUTPUT_MOVE_REF(_dst, _src)     \
 645         do {                                    \
 646                 bt_port_output_put_ref(_dst);   \
 647                 (_dst) = (_src);                \
 648                 (_src) = NULL;                  \
 649         } while (0)
 650
 651 /*! @} */
 652
 653 /*! @} */
 654
 655 #ifdef __cplusplus
 656 }
 657 #endif
 658
 659 #endif /* BABELTRACE2_GRAPH_PORT_H */