1 #ifndef BABELTRACE_REF_H
2 #define BABELTRACE_REF_H
5 * BabelTrace: common reference counting
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>
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:
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
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
35 @defgroup refs Reference counting management
37 @brief Common reference counting management for all Babeltrace objects.
40 #include <babeltrace/ref.h>
43 The macros and functions of this module are everything that is needed
44 to handle the <strong><em>reference counting</em></strong> of
47 Any Babeltrace object can be shared by multiple owners thanks to
48 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
51 The Babeltrace C API complies with the following key principles:
53 1. When you call an API function which accepts a Babeltrace object
54 pointer as a parameter, the API function <strong>borrows the
55 reference</strong> for the <strong>duration of the function</strong>.
57 @image html ref-count-user-calls.png
59 The API function can also get a new reference if the system needs a
60 more persistent reference, but the ownership is <strong>never
61 transferred</strong> from the caller to the API function.
63 In other words, the caller still owns the object after calling any
64 API function: no function "steals" the user's reference (except
67 2. An API function which \em returns a Babeltrace object pointer to the
68 user returns a <strong>new reference</strong>. The caller becomes an
71 @image html ref-count-api-returns.png
73 It is your responsibility to discard the object when you don't
74 need it anymore with bt_put().
76 For example, see bt_value_array_get().
78 3. A Babeltrace object pointer received as a parameter in a user
79 function called back from an API function is a
80 <strong>borrowed</strong>, or <strong>weak reference</strong>: if you
81 need a reference which is more persistent than the duration of the
82 user function, call bt_get() on the pointer.
84 @image html ref-count-callback.png
86 For example, see bt_value_map_foreach().
88 The two macros BT_PUT() and BT_MOVE() operate on \em variables rather
89 than pointer values. You should use BT_PUT() instead of bt_put() when
90 possible to avoid "double puts". For the same reason, you should use use
91 BT_MOVE() instead of performing manual reference moves between
95 @brief Reference counting management macros and functions.
103 @brief Calls bt_put() on a variable named \p _var, then
104 sets \p _var to \c NULL.
106 Using this macro is considered safer than calling bt_put() because it
107 makes sure that the variable which used to contain a reference to a
108 Babeltrace object is set to \c NULL so that a future BT_PUT() or
109 bt_put() call will not cause another, unwanted reference decrementation.
111 @param[in,out] _var Name of a variable containing a
112 Babeltrace object's address (this address
115 @post <strong>If \p _var does not contain \p NULL</strong>,
116 its reference count is decremented.
117 @post \p _var contains \c NULL.
119 @sa BT_MOVE(): Transfers the ownership of a Babeltrace object from a
122 #define BT_PUT(_var) \
129 @brief Transfers the ownership of a Babeltrace object from a variable
130 named \p _var_src to a variable named \p _var_dst.
132 This macro implements the following common pattern:
134 1. Call bt_put() on \p _var_dst to make sure the previous reference
135 held by \p _var_dst is discarded.
136 2. Assign \p _var_src to \p _var_dst.
137 3. Set \p _var_src to \c NULL to avoid future, unwanted reference
138 decrementation of \p _var_src.
141 You must \em not use this macro when both \p _var_dst and
142 \p _var_src contain the same Babeltrace object address and the reference
143 count of this object is 1. The initial call to bt_put() on \p _var_dst
144 would destroy the object and leave a dangling pointer in \p _var_dst.
146 @param[in,out] _var_dst Name of the destination variable, containing
147 either the address of a Babeltrace object to
148 put first, or \c NULL.
149 @param[in,out] _var_src Name of the source variable, containing
150 either the address of a Babeltrace object to
153 @pre <strong>If \p _var_dst and \p _var_src contain the same
154 value which is not \c NULL</strong>, this object's reference
155 count is greater than 1.
156 @post <strong>If \c _var_dst is not \c NULL</strong>, its reference
157 count is decremented.
158 @post \p _var_dst is equal to the value of \p _var_src \em before
159 you called this macro.
160 @post \p _var_src is \c NULL.
162 @sa BT_PUT(): Calls bt_put() on a variable, then sets it to \c NULL.
164 #define BT_MOVE(_var_dst, _var_src) \
167 (_var_dst) = (_var_src); \
172 @brief Increments the reference count of the Babeltrace object \p obj.
174 @param[in] obj Babeltrace object of which to get a new reference
178 @post <strong>If \c obj is not \c NULL</strong>, its reference
179 count is incremented.
181 @sa bt_put(): Decrements the reference count of a Babeltrace object.
183 void *bt_get(void *obj
);
186 @brief Decrements the reference count of the Babeltrace object
189 When the object's reference count reaches 0, the object can no longer
190 be accessed and is considered \em destroyed.
193 You should use the BT_PUT() macro instead of calling bt_put() since the
194 former is generally safer.
196 @param[in] obj Babeltrace object of which to drop a reference
199 @post <strong>If \c obj is not \c NULL</strong>, its reference
200 count is decremented.
202 @sa BT_PUT(): Calls bt_put() on a variable, then sets it to \c NULL.
203 @sa BT_MOVE(): Transfers the ownership of a Babeltrace object from a
205 @sa bt_get(): Increments the reference count of a Babeltrace object.
207 void bt_put(void *obj
);
217 #endif /* BABELTRACE_REF_H */
This page took 0.048226 seconds and 4 git commands to generate.