include/babeltrace/object.h

   1 #ifndef BABELTRACE_OBJECT_H
   2 #define BABELTRACE_OBJECT_H
   3
   4 /*
   5  * Copyright (c) 2015-2018 Philippe Proulx <pproulx@efficios.com>
   6  * Copyright (c) 2015 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   7  *
   8  * Permission is hereby granted, free of charge, to any person obtaining a copy
   9  * of this software and associated documentation files (the "Software"), to deal
  10  * in the Software without restriction, including without limitation the rights
  11  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  12  * copies of the Software, and to permit persons to whom the Software is
  13  * furnished to do so, subject to the following conditions:
  14  *
  15  * The above copyright notice and this permission notice shall be included in
  16  * all copies or substantial portions of the Software.
  17  *
  18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  19  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  20  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  21  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  22  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  23  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  24  * SOFTWARE.
  25  */
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31 /**
  32 @defgroup refs Reference counting management
  33 @ingroup apiref
  34 @brief Common reference counting management for all Babeltrace objects.
  35
  36 @code
  37 #include <babeltrace/object.h>
  38 @endcode
  39
  40 The macros and functions of this module are everything that is needed
  41 to handle the <strong><em>reference counting</em></strong> of
  42 Babeltrace objects.
  43
  44 Any Babeltrace object can be shared by multiple owners thanks to
  45 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
  46 counting</a>.
  47
  48 The Babeltrace C API complies with the following key principles:
  49
  50 1. When you call an API function which accepts a Babeltrace object
  51    pointer as a parameter, the API function <strong>borrows the
  52    reference</strong> for the <strong>duration of the function</strong>.
  53
  54    @image html ref-count-user-calls.png
  55
  56    The API function can also get a new reference if the system needs a
  57    more persistent reference, but the ownership is <strong>never
  58    transferred</strong> from the caller to the API function.
  59
  60    In other words, the caller still owns the object after calling any
  61    API function: no function "steals" the user's reference (except
  62    bt_object_put_ref()).
  63
  64 2. An API function which \em returns a Babeltrace object pointer to the
  65    user returns a <strong>new reference</strong>. The caller becomes an
  66    owner of the object.
  67
  68    @image html ref-count-api-returns.png
  69
  70    It is your responsibility to discard the object when you don't
  71    need it anymore with bt_object_put_ref().
  72
  73    For example, see bt_value_array_get().
  74
  75 3. A Babeltrace object pointer received as a parameter in a user
  76    function called back from an API function is a
  77    <strong>borrowed</strong>, or <strong>weak reference</strong>: if you
  78    need a reference which is more persistent than the duration of the
  79    user function, call bt_object_get_ref() on the pointer.
  80
  81    @image html ref-count-callback.png
  82
  83    For example, see bt_value_map_foreach_entry().
  84
  85 The two macros BT_OBJECT_PUT_REF_AND_RESET() and BT_OBJECT_MOVE_REF() operate on \em variables rather
  86 than pointer values. You should use BT_OBJECT_PUT_REF_AND_RESET() instead of bt_object_put_ref() when
  87 possible to avoid "double puts". For the same reason, you should use use
  88 BT_OBJECT_MOVE_REF() instead of performing manual reference moves between
  89 variables.
  90
  91 @file
  92 @brief Reference counting management macros and functions.
  93 @sa refs
  94
  95 @addtogroup refs
  96 @{
  97 */
  98
  99 /**
 100 @brief  Calls bt_object_put_ref() on a variable named \p _var, then
 101         sets \p _var to \c NULL.
 102
 103 Using this macro is considered safer than calling bt_object_put_ref() because it
 104 makes sure that the variable which used to contain a reference to a
 105 Babeltrace object is set to \c NULL so that a future BT_OBJECT_PUT_REF_AND_RESET() or
 106 bt_object_put_ref() call will not cause another, unwanted reference decrementation.
 107
 108 @param[in,out] _var     Name of a variable containing a
 109                         Babeltrace object's address (this address
 110                         can be \c NULL).
 111
 112 @post <strong>If \p _var does not contain \p NULL</strong>,
 113         its reference count is decremented.
 114 @post \p _var contains \c NULL.
 115
 116 @sa BT_OBJECT_MOVE_REF(): Transfers the ownership of a Babeltrace object from a
 117         variable to another.
 118 */
 119 #define BT_OBJECT_PUT_REF_AND_RESET(_var)       \
 120         do {                                    \
 121                 bt_object_put_ref(_var);        \
 122                 (_var) = NULL;                  \
 123         } while (0)
 124
 125 /**
 126 @brief  Transfers the ownership of a Babeltrace object from a variable
 127         named \p _var_src to a variable named \p _var_dst.
 128
 129 This macro implements the following common pattern:
 130
 131   1. Call bt_object_put_ref() on \p _var_dst to make sure the previous reference
 132      held by \p _var_dst is discarded.
 133   2. Assign \p _var_src to \p _var_dst.
 134   3. Set \p _var_src to \c NULL to avoid future, unwanted reference
 135      decrementation of \p _var_src.
 136
 137 @warning
 138 You must \em not use this macro when both \p _var_dst and
 139 \p _var_src contain the same Babeltrace object address and the reference
 140 count of this object is 1. The initial call to bt_object_put_ref() on \p _var_dst
 141 would destroy the object and leave a dangling pointer in \p _var_dst.
 142
 143 @param[in,out] _var_dst Name of the destination variable, containing
 144                         either the address of a Babeltrace object to
 145                         put first, or \c NULL.
 146 @param[in,out] _var_src Name of the source variable, containing
 147                         either the address of a Babeltrace object to
 148                         move, or \c NULL.
 149
 150 @pre <strong>If \p _var_dst and \p _var_src contain the same
 151         value which is not \c NULL</strong>, this object's reference
 152         count is greater than 1.
 153 @post <strong>If \c _var_dst is not \c NULL</strong>, its reference
 154         count is decremented.
 155 @post \p _var_dst is equal to the value of \p _var_src \em before
 156         you called this macro.
 157 @post \p _var_src is \c NULL.
 158
 159 @sa BT_OBJECT_PUT_REF_AND_RESET(): Calls bt_object_put_ref() on a variable, then sets it to \c NULL.
 160 */
 161 #define BT_OBJECT_MOVE_REF(_var_dst, _var_src)  \
 162         do {                                    \
 163                 bt_object_put_ref(_var_dst);    \
 164                 (_var_dst) = (_var_src);        \
 165                 (_var_src) = NULL;              \
 166         } while (0)
 167
 168 /**
 169 @brief  Increments the reference count of the Babeltrace object \p obj.
 170
 171 @param[in] obj  Babeltrace object of which to get a new reference
 172                 (can be \c NULL).
 173 @returns        \p obj
 174
 175 @post <strong>If \c obj is not \c NULL</strong>, its reference
 176         count is incremented.
 177
 178 @sa bt_object_put_ref(): Decrements the reference count of a Babeltrace object.
 179 */
 180 void bt_object_get_ref(const void *obj);
 181
 182 /**
 183 @brief  Decrements the reference count of the Babeltrace object
 184         \p obj.
 185
 186 When the object's reference count reaches 0, the object can no longer
 187 be accessed and is considered \em destroyed.
 188
 189 @remarks
 190 You should use the BT_OBJECT_PUT_REF_AND_RESET() macro instead of calling bt_object_put_ref() since the
 191 former is generally safer.
 192
 193 @param[in] obj  Babeltrace object of which to drop a reference
 194                 (can be \c NULL).
 195
 196 @post <strong>If \c obj is not \c NULL</strong>, its reference
 197         count is decremented.
 198
 199 @sa BT_OBJECT_PUT_REF_AND_RESET(): Calls bt_object_put_ref() on a variable, then sets it to \c NULL.
 200 @sa BT_OBJECT_MOVE_REF(): Transfers the ownership of a Babeltrace object from a
 201         variable to another.
 202 @sa bt_object_get_ref(): Increments the reference count of a Babeltrace object.
 203 */
 204 void bt_object_put_ref(const void *obj);
 205
 206 /**
 207 @}
 208 */
 209
 210 #ifdef __cplusplus
 211 }
 212 #endif
 213
 214 #endif /* BABELTRACE_OBJECT_H */