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