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 #include <babeltrace/babeltrace-internal.h>
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /*
  37  * BT_PUT: calls bt_put() with a variable, then sets this variable to NULL.
  38  *
  39  * A common action with Babeltrace objects is to create or get one, perform
  40  * an action with it, and then put it. To avoid putting it a second time
  41  * later (if an error occurs, for example), the variable is often reset
  42  * to NULL after putting the object it points to. Since this is so
  43  * common, the BT_PUT() macro can be used to do just that.
  44  *
  45  * It is safe to call this function with a variable containing NULL.
  46  *
  47  * @param obj Variable pointing to a Babeltrace object.
  48  */
  49 #define BT_PUT(_obj)            \
  50         do {                    \
  51                 bt_put(_obj);   \
  52                 (_obj) = NULL;  \
  53         } while (0)
  54
  55 /*
  56  * BT_MOVE: transfers the ownership of an object, setting the old owner to NULL.
  57  *
  58  * This macro sets the variable _dst to the value of the variable _src,
  59  * then sets _src to NULL, effectively moving the ownership of an
  60  * object from one variable to the other.
  61  *
  62  * Before assigning _src to _dst, it puts _dst. Therefore it is not safe to
  63  * call this function with an uninitialized value of _dst.
  64  *
  65  * @param _dst Destination variable pointing to a Babeltrace object.
  66  * @param _src Source variable pointing to a Babeltrace object.
  67  */
  68 #define BT_MOVE(_dst, _src)     \
  69         do {                    \
  70                 bt_put(_dst);   \
  71                 (_dst) = (_src);\
  72                 (_src) = NULL;  \
  73         } while (0)
  74
  75 /*
  76  * bt_get: increments the reference count of a Babeltrace object.
  77  *
  78  * The same number of bt_get() and bt_put() (plus one extra bt_put() to release
  79  * the initial reference acquired at creation) have to be performed to destroy a
  80  * Babeltrace object.
  81  *
  82  * It is safe to call this function with a NULL object.
  83  *
  84  * @param obj Babeltrace object.
  85  *
  86  * Returns obj.
  87  */
  88 BT_HIDDEN
  89 void *bt_get(void *obj);
  90
  91 /*
  92  * bt_put: decrements the reference count of a Babeltrace object.
  93  *
  94  * The same number of bt_get() and bt_put() (plus one extra bt_put() to release
  95  * bt_put() to release the initial reference done at creation) have to be
  96  * performed to destroy a Babeltrace object.
  97  *
  98  * The object is freed when its reference count is decremented to 0 by a call to
  99  * bt_put().
 100  *
 101  * It is safe to call this function with a NULL object.
 102  *
 103  * @param obj Babeltrace object.
 104  */
 105 BT_HIDDEN
 106 void bt_put(void *obj);
 107
 108 #ifdef __cplusplus
 109 }
 110 #endif
 111
 112 #endif /* BABELTRACE_REF_H */