include/babeltrace/ref.h

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