include/babeltrace/object.h

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