include/babeltrace2-ctf-writer/object.h

   1 #ifndef BABELTRACE2_CTF_WRITER_OBJECT_H
   2 #define BABELTRACE2_CTF_WRITER_OBJECT_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 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 /**
  31 @defgroup refs Reference counting management
  32 @ingroup apiref
  33 @brief Common reference counting management for all Babeltrace objects.
  34
  35 @code
  36 #include <babeltrace2-ctf-writer/object.h>
  37 @endcode
  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 Any Babeltrace object can be shared by multiple owners thanks to
  44 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
  45 counting</a>.
  46
  47 The Babeltrace C API complies with the following key principles:
  48
  49 1. When you call an API function which accepts a Babeltrace object
  50    pointer as a parameter, the API function <strong>borrows the
  51    reference</strong> for the <strong>duration of the function</strong>.
  52
  53    @image html ref-count-user-calls.png
  54
  55    The API function can also get a new reference if the system needs a
  56    more persistent reference, but the ownership is <strong>never
  57    transferred</strong> from the caller to the API function.
  58
  59    In other words, the caller still owns the object after calling any
  60    API function: no function "steals" the user's reference (except
  61    bt_ctf_object_put_ref()).
  62
  63 2. An API function which \em returns a Babeltrace object pointer to the
  64    user returns a <strong>new reference</strong>. The caller becomes an
  65    owner of the object.
  66
  67    @image html ref-count-api-returns.png
  68
  69    It is your responsibility to discard the object when you don't
  70    need it anymore with bt_ctf_object_put_ref().
  71
  72    For example, see bt_ctf_value_array_get().
  73
  74 3. A Babeltrace object pointer received as a parameter in a user
  75    function called back from an API function is a
  76    <strong>borrowed</strong>, or <strong>weak reference</strong>: if you
  77    need a reference which is more persistent than the duration of the
  78    user function, call bt_ctf_object_get_ref() on the pointer.
  79
  80    @image html ref-count-callback.png
  81
  82    For example, see bt_ctf_value_map_foreach_entry().
  83
  84 The two macros BT_CTF_OBJECT_PUT_REF_AND_RESET() and BT_CTF_OBJECT_MOVE_REF() operate on \em variables rather
  85 than pointer values. You should use BT_CTF_OBJECT_PUT_REF_AND_RESET() instead of bt_ctf_object_put_ref() when
  86 possible to avoid "double puts". For the same reason, you should use use
  87 BT_CTF_OBJECT_MOVE_REF() instead of performing manual reference moves between
  88 variables.
  89
  90 @file
  91 @brief Reference counting management macros and functions.
  92 @sa refs
  93
  94 @addtogroup refs
  95 @{
  96 */
  97
  98 /**
  99 @brief  Calls bt_ctf_object_put_ref() on a variable named \p _var, then
 100         sets \p _var to \c NULL.
 101
 102 Using this macro is considered safer than calling bt_ctf_object_put_ref() because it
 103 makes sure that the variable which used to contain a reference to a
 104 Babeltrace object is set to \c NULL so that a future BT_CTF_OBJECT_PUT_REF_AND_RESET() or
 105 bt_ctf_object_put_ref() call will not cause another, unwanted reference decrementation.
 106
 107 @param[in,out] _var     Name of a variable containing a
 108                         Babeltrace object's address (this address
 109                         can be \c NULL).
 110
 111 @post <strong>If \p _var does not contain \p NULL</strong>,
 112         its reference count is decremented.
 113 @post \p _var contains \c NULL.
 114
 115 @sa BT_CTF_OBJECT_MOVE_REF(): Transfers the ownership of a Babeltrace object from a
 116         variable to another.
 117 */
 118 #define BT_CTF_OBJECT_PUT_REF_AND_RESET(_var)   \
 119         do {                                    \
 120                 bt_ctf_object_put_ref(_var);    \
 121                 (_var) = NULL;                  \
 122         } while (0)
 123
 124 /**
 125 @brief  Transfers the ownership of a Babeltrace object from a variable
 126         named \p _var_src to a variable named \p _var_dst.
 127
 128 This macro implements the following common pattern:
 129
 130   1. Call bt_ctf_object_put_ref() on \p _var_dst to make sure the previous reference
 131      held by \p _var_dst is discarded.
 132   2. Assign \p _var_src to \p _var_dst.
 133   3. Set \p _var_src to \c NULL to avoid future, unwanted reference
 134      decrementation of \p _var_src.
 135
 136 @warning
 137 You must \em not use this macro when both \p _var_dst and
 138 \p _var_src contain the same Babeltrace object address and the reference
 139 count of this object is 1. The initial call to bt_ctf_object_put_ref() on \p _var_dst
 140 would destroy the object and leave a dangling pointer in \p _var_dst.
 141
 142 @param[in,out] _var_dst Name of the destination variable, containing
 143                         either the address of a Babeltrace object to
 144                         put first, or \c NULL.
 145 @param[in,out] _var_src Name of the source variable, containing
 146                         either the address of a Babeltrace object to
 147                         move, or \c NULL.
 148
 149 @pre <strong>If \p _var_dst and \p _var_src contain the same
 150         value which is not \c NULL</strong>, this object's reference
 151         count is greater than 1.
 152 @post <strong>If \c _var_dst is not \c NULL</strong>, its reference
 153         count is decremented.
 154 @post \p _var_dst is equal to the value of \p _var_src \em before
 155         you called this macro.
 156 @post \p _var_src is \c NULL.
 157
 158 @sa BT_CTF_OBJECT_PUT_REF_AND_RESET(): Calls bt_ctf_object_put_ref() on a variable, then sets it to \c NULL.
 159 */
 160 #define BT_CTF_OBJECT_MOVE_REF(_var_dst, _var_src)      \
 161         do {                                    \
 162                 bt_ctf_object_put_ref(_var_dst);        \
 163                 (_var_dst) = (_var_src);        \
 164                 (_var_src) = NULL;              \
 165         } while (0)
 166
 167 /**
 168 @brief  Increments the reference count of the Babeltrace object \p obj.
 169
 170 @param[in] obj  Babeltrace object of which to get a new reference
 171                 (can be \c NULL).
 172 @returns        \p obj
 173
 174 @post <strong>If \c obj is not \c NULL</strong>, its reference
 175         count is incremented.
 176
 177 @sa bt_ctf_object_put_ref(): Decrements the reference count of a Babeltrace object.
 178 */
 179 void *bt_ctf_object_get_ref(void *obj);
 180
 181 /**
 182 @brief  Decrements the reference count of the Babeltrace object
 183         \p obj.
 184
 185 When the object's reference count reaches 0, the object can no longer
 186 be accessed and is considered \em destroyed.
 187
 188 @remarks
 189 You should use the BT_CTF_OBJECT_PUT_REF_AND_RESET() macro instead of calling bt_ctf_object_put_ref() since the
 190 former is generally safer.
 191
 192 @param[in] obj  Babeltrace object of which to drop a reference
 193                 (can be \c NULL).
 194
 195 @post <strong>If \c obj is not \c NULL</strong>, its reference
 196         count is decremented.
 197
 198 @sa BT_CTF_OBJECT_PUT_REF_AND_RESET(): Calls bt_ctf_object_put_ref() on a variable, then sets it to \c NULL.
 199 @sa BT_CTF_OBJECT_MOVE_REF(): Transfers the ownership of a Babeltrace object from a
 200         variable to another.
 201 @sa bt_ctf_object_get_ref(): Increments the reference count of a Babeltrace object.
 202 */
 203 void bt_ctf_object_put_ref(void *obj);
 204
 205 /**
 206 @}
 207 */
 208
 209 #ifdef __cplusplus
 210 }
 211 #endif
 212
 213 #endif /* BABELTRACE2_CTF_WRITER_OBJECT_H */