include/babeltrace2/graph/connection.h

   1 #ifndef BABELTRACE2_GRAPH_CONNECTION_H
   2 #define BABELTRACE2_GRAPH_CONNECTION_H
   3
   4 /*
   5  * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
   6  *
   7  * Permission is hereby granted, free of charge, to any person obtaining a copy
   8  * of this software and associated documentation files (the "Software"), to deal
   9  * in the Software without restriction, including without limitation the rights
  10  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  11  * copies of the Software, and to permit persons to whom the Software is
  12  * furnished to do so, subject to the following conditions:
  13  *
  14  * The above copyright notice and this permission notice shall be included in
  15  * all copies or substantial portions of the Software.
  16  *
  17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  18  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  20  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  21  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  22  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  23  * SOFTWARE.
  24  */
  25
  26 #ifndef __BT_IN_BABELTRACE_H
  27 # error "Please include <babeltrace2/babeltrace.h> instead."
  28 #endif
  29
  30 #include <babeltrace2/types.h>
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /*!
  37 @defgroup api-conn Connection
  38 @ingroup api-graph
  39
  40 @brief
  41     \bt_c_comp \bt_port connection.
  42
  43 A <strong><em>connection</em></strong> is a link between an \bt_oport
  44 and an \bt_iport.
  45
  46 @image html component-zoom.png
  47
  48 A connection is a \ref api-fund-shared-object "shared object": get a new
  49 reference with bt_connection_get_ref() and put an existing reference with
  50 bt_connection_put_ref().
  51
  52 The type of a connection is #bt_connection.
  53
  54 Borrow the upstream (output) port and downstream (input) port of a
  55 connection with bt_connection_borrow_upstream_port_const() and
  56 bt_connection_borrow_downstream_port_const().
  57 */
  58
  59 /*! @{ */
  60
  61 /*!
  62 @name Type
  63 @{
  64
  65 @typedef struct bt_connection bt_connection;
  66
  67 @brief
  68     Connection.
  69
  70 @}
  71 */
  72
  73 /*!
  74 @name Port access
  75 @{
  76 */
  77
  78 /*!
  79 @brief
  80     Borrows the upstream \bt_iport of the connection \bt_p{connection}.
  81
  82 @param[in] connection
  83     Connection of which to borrow the upstream port.
  84
  85 @returns
  86     \em Borrowed reference of the upstream port of \bt_p{connection}.
  87
  88 @bt_pre_not_null{connection}
  89 */
  90 extern const bt_port_input *bt_connection_borrow_downstream_port_const(
  91                 const bt_connection *connection);
  92
  93 /*!
  94 @brief
  95     Borrows the downstream \bt_oport of the connection
  96     \bt_p{connection}.
  97
  98 @param[in] connection
  99     Connection of which to borrow the downstream port.
 100
 101 @returns
 102     \em Borrowed reference of the downstream port of \bt_p{connection}.
 103
 104 @bt_pre_not_null{connection}
 105 */
 106 extern const bt_port_output *bt_connection_borrow_upstream_port_const(
 107                 const bt_connection *connection);
 108
 109 /*! @} */
 110
 111 /*!
 112 @name Reference count
 113 @{
 114 */
 115
 116 /*!
 117 @brief
 118     Increments the \ref api-fund-shared-object "reference count" of
 119     the connection \bt_p{connection}.
 120
 121 @param[in] connection
 122     @parblock
 123     Connection of which to increment the reference count.
 124
 125     Can be \c NULL.
 126     @endparblock
 127
 128 @sa bt_connection_put_ref() &mdash;
 129     Decrements the reference count of a connection.
 130 */
 131 extern void bt_connection_get_ref(const bt_connection *connection);
 132
 133 /*!
 134 @brief
 135     Decrements the \ref api-fund-shared-object "reference count" of
 136     the connection \bt_p{connection}.
 137
 138 @param[in] connection
 139     @parblock
 140     Connection of which to decrement the reference count.
 141
 142     Can be \c NULL.
 143     @endparblock
 144
 145 @sa bt_connection_get_ref() &mdash;
 146     Increments the reference count of a connection.
 147 */
 148 extern void bt_connection_put_ref(const bt_connection *connection);
 149
 150 /*!
 151 @brief
 152     Decrements the reference count of the connection
 153     \bt_p{_connection}, and then sets \bt_p{_connection} to \c NULL.
 154
 155 @param _connection
 156     @parblock
 157     Connection of which to decrement the reference count.
 158
 159     Can contain \c NULL.
 160     @endparblock
 161
 162 @bt_pre_assign_expr{_connection}
 163 */
 164 #define BT_CONNECTION_PUT_REF_AND_RESET(_connection)    \
 165         do {                                            \
 166                 bt_connection_put_ref(_connection);     \
 167                 (_connection) = NULL;                   \
 168         } while (0)
 169
 170 /*!
 171 @brief
 172     Decrements the reference count of the connection \bt_p{_dst}, sets
 173     \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
 174
 175 This macro effectively moves a connection reference from the expression
 176 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
 177 \bt_p{_dst} reference.
 178
 179 @param _dst
 180     @parblock
 181     Destination expression.
 182
 183     Can contain \c NULL.
 184     @endparblock
 185 @param _src
 186     @parblock
 187     Source expression.
 188
 189     Can contain \c NULL.
 190     @endparblock
 191
 192 @bt_pre_assign_expr{_dst}
 193 @bt_pre_assign_expr{_src}
 194 */
 195 #define BT_CONNECTION_MOVE_REF(_dst, _src)      \
 196         do {                                    \
 197                 bt_connection_put_ref(_dst);    \
 198                 (_dst) = (_src);                \
 199                 (_src) = NULL;                  \
 200         } while (0)
 201
 202 /*! @} */
 203
 204 /*! @} */
 205
 206 #ifdef __cplusplus
 207 }
 208 #endif
 209
 210 #endif /* BABELTRACE2_GRAPH_CONNECTION_H */