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