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