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);
  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);
  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
 119 /*!
 120 @brief
 121     Decrements the \ref api-fund-shared-object "reference count" of
 122     the connection \bt_p{connection}.
 123
 124 @param[in] connection
 125     @parblock
 126     Connection of which to decrement the reference count.
 127
 128     Can be \c NULL.
 129     @endparblock
 130
 131 @sa bt_connection_get_ref() &mdash;
 132     Increments the reference count of a connection.
 133 */
 134 extern void bt_connection_put_ref(const bt_connection *connection);
 135
 136 /*!
 137 @brief
 138     Decrements the reference count of the connection
 139     \bt_p{_connection}, and then sets \bt_p{_connection} to \c NULL.
 140
 141 @param _connection
 142     @parblock
 143     Connection of which to decrement the reference count.
 144
 145     Can contain \c NULL.
 146     @endparblock
 147
 148 @bt_pre_assign_expr{_connection}
 149 */
 150 #define BT_CONNECTION_PUT_REF_AND_RESET(_connection)    \
 151         do {                                            \
 152                 bt_connection_put_ref(_connection);     \
 153                 (_connection) = NULL;                   \
 154         } while (0)
 155
 156 /*!
 157 @brief
 158     Decrements the reference count of the connection \bt_p{_dst}, sets
 159     \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
 160
 161 This macro effectively moves a connection reference from the expression
 162 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
 163 \bt_p{_dst} reference.
 164
 165 @param _dst
 166     @parblock
 167     Destination expression.
 168
 169     Can contain \c NULL.
 170     @endparblock
 171 @param _src
 172     @parblock
 173     Source expression.
 174
 175     Can contain \c NULL.
 176     @endparblock
 177
 178 @bt_pre_assign_expr{_dst}
 179 @bt_pre_assign_expr{_src}
 180 */
 181 #define BT_CONNECTION_MOVE_REF(_dst, _src)      \
 182         do {                                    \
 183                 bt_connection_put_ref(_dst);    \
 184                 (_dst) = (_src);                \
 185                 (_src) = NULL;                  \
 186         } while (0)
 187
 188 /*! @} */
 189
 190 /*! @} */
 191
 192 #ifdef __cplusplus
 193 }
 194 #endif
 195
 196 #endif /* BABELTRACE2_GRAPH_CONNECTION_H */