include/babeltrace2/graph/connection.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
   5  */
   6
   7 #ifndef BABELTRACE2_GRAPH_CONNECTION_H
   8 #define BABELTRACE2_GRAPH_CONNECTION_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
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif
  21
  22 /*!
  23 @defgroup api-conn Connection
  24 @ingroup api-graph
  25
  26 @brief
  27     \bt_c_comp \bt_port connection.
  28
  29 A <strong><em>connection</em></strong> is a link between an \bt_oport
  30 and an \bt_iport.
  31
  32 @image html component-zoom.png
  33
  34 A connection is a \ref api-fund-shared-object "shared object": get a new
  35 reference with bt_connection_get_ref() and put an existing reference with
  36 bt_connection_put_ref().
  37
  38 The type of a connection is #bt_connection.
  39
  40 Borrow the upstream (output) port and downstream (input) port of a
  41 connection with bt_connection_borrow_upstream_port_const() and
  42 bt_connection_borrow_downstream_port_const().
  43 */
  44
  45 /*! @{ */
  46
  47 /*!
  48 @name Type
  49 @{
  50
  51 @typedef struct bt_connection bt_connection;
  52
  53 @brief
  54     Connection.
  55
  56 @}
  57 */
  58
  59 /*!
  60 @name Port access
  61 @{
  62 */
  63
  64 /*!
  65 @brief
  66     Borrows the upstream \bt_iport of the connection \bt_p{connection}.
  67
  68 @param[in] connection
  69     Connection of which to borrow the upstream port.
  70
  71 @returns
  72     \em Borrowed reference of the upstream port of \bt_p{connection}.
  73
  74 @bt_pre_not_null{connection}
  75 */
  76 extern const bt_port_input *bt_connection_borrow_downstream_port_const(
  77                 const bt_connection *connection) __BT_NOEXCEPT;
  78
  79 /*!
  80 @brief
  81     Borrows the downstream \bt_oport of the connection
  82     \bt_p{connection}.
  83
  84 @param[in] connection
  85     Connection of which to borrow the downstream port.
  86
  87 @returns
  88     \em Borrowed reference of the downstream port of \bt_p{connection}.
  89
  90 @bt_pre_not_null{connection}
  91 */
  92 extern const bt_port_output *bt_connection_borrow_upstream_port_const(
  93                 const bt_connection *connection) __BT_NOEXCEPT;
  94
  95 /*! @} */
  96
  97 /*!
  98 @name Reference count
  99 @{
 100 */
 101
 102 /*!
 103 @brief
 104     Increments the \ref api-fund-shared-object "reference count" of
 105     the connection \bt_p{connection}.
 106
 107 @param[in] connection
 108     @parblock
 109     Connection of which to increment the reference count.
 110
 111     Can be \c NULL.
 112     @endparblock
 113
 114 @sa bt_connection_put_ref() &mdash;
 115     Decrements the reference count of a connection.
 116 */
 117 extern void bt_connection_get_ref(const bt_connection *connection)
 118                 __BT_NOEXCEPT;
 119
 120 /*!
 121 @brief
 122     Decrements the \ref api-fund-shared-object "reference count" of
 123     the connection \bt_p{connection}.
 124
 125 @param[in] connection
 126     @parblock
 127     Connection of which to decrement the reference count.
 128
 129     Can be \c NULL.
 130     @endparblock
 131
 132 @sa bt_connection_get_ref() &mdash;
 133     Increments the reference count of a connection.
 134 */
 135 extern void bt_connection_put_ref(const bt_connection *connection)
 136                 __BT_NOEXCEPT;
 137
 138 /*!
 139 @brief
 140     Decrements the reference count of the connection
 141     \bt_p{_connection}, and then sets \bt_p{_connection} to \c NULL.
 142
 143 @param _connection
 144     @parblock
 145     Connection of which to decrement the reference count.
 146
 147     Can contain \c NULL.
 148     @endparblock
 149
 150 @bt_pre_assign_expr{_connection}
 151 */
 152 #define BT_CONNECTION_PUT_REF_AND_RESET(_connection)    \
 153         do {                                            \
 154                 bt_connection_put_ref(_connection);     \
 155                 (_connection) = NULL;                   \
 156         } while (0)
 157
 158 /*!
 159 @brief
 160     Decrements the reference count of the connection \bt_p{_dst}, sets
 161     \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
 162
 163 This macro effectively moves a connection reference from the expression
 164 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
 165 \bt_p{_dst} reference.
 166
 167 @param _dst
 168     @parblock
 169     Destination expression.
 170
 171     Can contain \c NULL.
 172     @endparblock
 173 @param _src
 174     @parblock
 175     Source expression.
 176
 177     Can contain \c NULL.
 178     @endparblock
 179
 180 @bt_pre_assign_expr{_dst}
 181 @bt_pre_assign_expr{_src}
 182 */
 183 #define BT_CONNECTION_MOVE_REF(_dst, _src)      \
 184         do {                                    \
 185                 bt_connection_put_ref(_dst);    \
 186                 (_dst) = (_src);                \
 187                 (_src) = NULL;                  \
 188         } while (0)
 189
 190 /*! @} */
 191
 192 /*! @} */
 193
 194 #ifdef __cplusplus
 195 }
 196 #endif
 197
 198 #endif /* BABELTRACE2_GRAPH_CONNECTION_H */