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