lib: rename `bt_object_{get,put}_no` -> `bt_object_{get,put}_ref_no`
[babeltrace.git] / src / lib / object.h
CommitLineData
83509119
JG
1#ifndef BABELTRACE_OBJECT_INTERNAL_H
2#define BABELTRACE_OBJECT_INTERNAL_H
273b65be
JG
3
4/*
e2f7325d 5 * Copyright 2017-2018 Philippe Proulx <pproulx@efficios.com>
83509119 6 * Copyright 2015 Jérémie Galarneau <jeremie.galarneau@efficios.com>
273b65be
JG
7 *
8 * Permission is hereby granted, free of charge, to any person obtaining a copy
9 * of this software and associated documentation files (the "Software"), to deal
10 * in the Software without restriction, including without limitation the rights
11 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
12 * copies of the Software, and to permit persons to whom the Software is
13 * furnished to do so, subject to the following conditions:
14 *
15 * The above copyright notice and this permission notice shall be included in
16 * all copies or substantial portions of the Software.
17 *
18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
24 * SOFTWARE.
25 */
26
91d81473 27#include "common/macros.h"
578e048b 28#include "common/assert.h"
312c056a 29#include <stdbool.h>
273b65be 30
9358ceb3
PP
31/*
32 * Some parts of the Babeltrace project use this internal library header
33 * for internal reference counting. Until we make this header generic
34 * for the whole project, make it possible to disable logging in this
35 * file by defining `BT_OBJECT_DONT_LOG` because it's possible that the
ef267d12 36 * BT_LOGT() statements here won't find the log level
9358ceb3
PP
37 * (`BT_LOG_OUTPUT_LEVEL`).
38 */
ef267d12 39#if defined(BT_LOGT) && !defined(BT_OBJECT_DONT_LOG)
9358ceb3
PP
40# define _BT_OBJECT_LOGGING_ENABLED
41#endif
42
3fea54f6
PP
43struct bt_object;
44
45typedef void (*bt_object_release_func)(struct bt_object *);
46typedef void (*bt_object_parent_is_owner_listener_func)(
47 struct bt_object *);
48
49static inline
6871026b 50void bt_object_get_ref_no_null_check(const void *obj);
3fea54f6
PP
51
52static inline
6871026b 53void bt_object_put_ref_no_null_check(const void *obj);
3fea54f6
PP
54
55/*
56 * Babeltrace object base.
57 *
58 * All objects publicly exposed by Babeltrace APIs must contain this
59 * object as their first member.
de3dd40e 60 */
83509119 61struct bt_object {
312c056a 62 /*
3fea54f6
PP
63 * True if this object is shared, that is, it has a reference
64 * count.
312c056a
PP
65 */
66 bool is_shared;
3fea54f6
PP
67
68 /*
69 * Current reference count.
70 */
71 unsigned long long ref_count;
72
73 /*
74 * Release function called when the object's reference count
75 * falls to zero. For an object with a parent, this function is
76 * bt_object_with_parent_release_func(), which calls
77 * `spec_release_func` below if there's no current parent.
78 */
79 bt_object_release_func release_func;
80
81 /*
82 * Specific release function called by
83 * bt_object_with_parent_release_func() or directly by a
84 * parent object.
85 */
86 bt_object_release_func spec_release_func;
87
88 /*
89 * Optional callback for an object with a parent, called by
90 * bt_object_with_parent_release_func() to indicate to the
91 * object that its parent is its owner.
92 */
93 bt_object_parent_is_owner_listener_func
94 parent_is_owner_listener_func;
95
96 /*
97 * Optional parent object.
98 */
99 struct bt_object *parent;
273b65be
JG
100};
101
102static inline
398454ed 103unsigned long long bt_object_get_ref_count(const struct bt_object *c_obj)
7c56f3cc 104{
398454ed
PP
105 struct bt_object *obj = (void *) c_obj;
106
3fea54f6
PP
107 BT_ASSERT(obj);
108 BT_ASSERT(obj->is_shared);
109 return obj->ref_count;
110}
5d2d9981 111
3fea54f6 112static inline
398454ed 113struct bt_object *bt_object_borrow_parent(const struct bt_object *c_obj)
3fea54f6 114{
398454ed
PP
115 struct bt_object *obj = (void *) c_obj;
116
3fea54f6
PP
117 BT_ASSERT(obj);
118 BT_ASSERT(obj->is_shared);
119 return obj->parent;
7c56f3cc
MD
120}
121
122static inline
398454ed 123struct bt_object *bt_object_get_parent(const struct bt_object *c_obj)
5d2d9981 124{
398454ed 125 struct bt_object *obj = (void *) c_obj;
3fea54f6
PP
126 struct bt_object *parent = bt_object_borrow_parent(obj);
127
128 if (parent) {
6871026b 129 bt_object_get_ref_no_null_check(parent);
3fea54f6
PP
130 }
131
132 return parent;
133}
134
135static inline
136void bt_object_set_parent(struct bt_object *child, struct bt_object *parent)
137{
138 BT_ASSERT(child);
139 BT_ASSERT(child->is_shared);
5d2d9981 140
9358ceb3 141#ifdef _BT_OBJECT_LOGGING_ENABLED
ef267d12 142 BT_LOGT("Setting object's parent: addr=%p, parent-addr=%p",
3fea54f6 143 child, parent);
0f5e83e5
PP
144#endif
145
3fea54f6
PP
146 /*
147 * It is assumed that a "child" having a parent is publicly
148 * reachable. Therefore, a reference to its parent must be
149 * taken. The reference to the parent will be released once the
150 * object's reference count falls to zero.
151 */
152 if (parent) {
153 BT_ASSERT(!child->parent);
154 child->parent = parent;
6871026b 155 bt_object_get_ref_no_null_check(parent);
3fea54f6
PP
156 } else {
157 if (child->parent) {
6871026b 158 bt_object_put_ref_no_null_check(child->parent);
3fea54f6
PP
159 }
160
161 child->parent = NULL;
5d2d9981
JG
162 }
163}
164
7c56f3cc 165static inline
3fea54f6
PP
166void bt_object_try_spec_release(struct bt_object *obj)
167{
168 BT_ASSERT(obj);
169 BT_ASSERT(obj->is_shared);
170 BT_ASSERT(obj->spec_release_func);
171
172 if (bt_object_get_ref_count(obj) == 0) {
173 obj->spec_release_func(obj);
174 }
175}
176
177static inline
178void bt_object_with_parent_release_func(struct bt_object *obj)
5d2d9981
JG
179{
180 if (obj->parent) {
3fea54f6
PP
181 /*
182 * Keep our own copy of the parent address because `obj`
183 * could be destroyed in
184 * obj->parent_is_owner_listener_func().
185 */
0f5e83e5
PP
186 struct bt_object *parent = obj->parent;
187
9358ceb3 188#ifdef _BT_OBJECT_LOGGING_ENABLED
ef267d12 189 BT_LOGT("Releasing parented object: addr=%p, ref-count=%llu, "
3fea54f6
PP
190 "parent-addr=%p, parent-ref-count=%llu",
191 obj, obj->ref_count,
192 parent, parent->ref_count);
0f5e83e5 193#endif
f167d3c0 194
3fea54f6 195 if (obj->parent_is_owner_listener_func) {
f167d3c0
PP
196 /*
197 * Object has a chance to destroy itself here
198 * under certain conditions and notify its
199 * parent. At this point the parent is
200 * guaranteed to exist because it's not put yet.
201 */
3fea54f6 202 obj->parent_is_owner_listener_func(obj);
f167d3c0
PP
203 }
204
5d2d9981 205 /* The release function will be invoked by the parent. */
6871026b 206 bt_object_put_ref_no_null_check(parent);
5d2d9981 207 } else {
3fea54f6 208 bt_object_try_spec_release(obj);
5d2d9981
JG
209 }
210}
211
212static inline
3fea54f6
PP
213void bt_object_init(struct bt_object *obj, bool is_shared,
214 bt_object_release_func release_func)
5d2d9981 215{
3fea54f6
PP
216 BT_ASSERT(obj);
217 BT_ASSERT(!is_shared || release_func);
218 obj->is_shared = is_shared;
219 obj->release_func = release_func;
220 obj->parent_is_owner_listener_func = NULL;
221 obj->spec_release_func = NULL;
222 obj->parent = NULL;
223 obj->ref_count = 1;
dc3fffef
PP
224}
225
226static inline
3fea54f6
PP
227void bt_object_init_shared(struct bt_object *obj,
228 bt_object_release_func release_func)
dc3fffef 229{
3fea54f6 230 bt_object_init(obj, true, release_func);
5d2d9981
JG
231}
232
233static inline
3fea54f6 234void bt_object_init_unique(struct bt_object *obj)
273b65be 235{
3fea54f6
PP
236 bt_object_init(obj, false, NULL);
237}
5d2d9981 238
3fea54f6
PP
239static inline
240void bt_object_init_shared_with_parent(struct bt_object *obj,
241 bt_object_release_func spec_release_func)
242{
243 BT_ASSERT(obj);
244 BT_ASSERT(spec_release_func);
245 bt_object_init_shared(obj, bt_object_with_parent_release_func);
246 obj->spec_release_func = spec_release_func;
247}
0f5e83e5 248
3fea54f6
PP
249static inline
250void bt_object_set_parent_is_owner_listener_func(struct bt_object *obj,
251 bt_object_parent_is_owner_listener_func func)
252{
253 BT_ASSERT(obj);
254 BT_ASSERT(obj->is_shared);
255 BT_ASSERT(obj->spec_release_func);
256 ((struct bt_object *) obj)->parent_is_owner_listener_func = func;
5d2d9981
JG
257}
258
312c056a 259static inline
398454ed 260void bt_object_inc_ref_count(const struct bt_object *c_obj)
312c056a 261{
398454ed
PP
262 struct bt_object *obj = (void *) c_obj;
263
3fea54f6
PP
264 BT_ASSERT(obj);
265 BT_ASSERT(obj->is_shared);
266 obj->ref_count++;
267 BT_ASSERT(obj->ref_count != 0);
312c056a
PP
268}
269
6c677fb5 270static inline
6871026b 271void bt_object_get_ref_no_null_check_no_parent_check(const struct bt_object *c_obj)
6c677fb5 272{
398454ed
PP
273 struct bt_object *obj = (void *) c_obj;
274
6c677fb5
PP
275 BT_ASSERT(obj);
276 BT_ASSERT(obj->is_shared);
277
9358ceb3 278#ifdef _BT_OBJECT_LOGGING_ENABLED
ef267d12 279 BT_LOGT("Incrementing object's reference count: %llu -> %llu: "
6c677fb5
PP
280 "addr=%p, cur-count=%llu, new-count=%llu",
281 obj->ref_count, obj->ref_count + 1,
282 obj, obj->ref_count, obj->ref_count + 1);
283#endif
284
285 bt_object_inc_ref_count(obj);
286}
287
5d2d9981 288static inline
6871026b 289void bt_object_get_ref_no_null_check(const void *c_obj)
5d2d9981 290{
398454ed
PP
291 struct bt_object *obj = (void *) c_obj;
292
3fea54f6
PP
293 BT_ASSERT(obj);
294 BT_ASSERT(obj->is_shared);
5d2d9981 295
91d81473 296 if (G_UNLIKELY(obj->parent && bt_object_get_ref_count(obj) == 0)) {
9358ceb3 297#ifdef _BT_OBJECT_LOGGING_ENABLED
ef267d12 298 BT_LOGT("Incrementing object's parent's reference count: "
3fea54f6
PP
299 "addr=%p, parent-addr=%p", obj, obj->parent);
300#endif
301
6871026b 302 bt_object_get_ref_no_null_check(obj->parent);
3fea54f6
PP
303 }
304
9358ceb3 305#ifdef _BT_OBJECT_LOGGING_ENABLED
ef267d12 306 BT_LOGT("Incrementing object's reference count: %llu -> %llu: "
3fea54f6
PP
307 "addr=%p, cur-count=%llu, new-count=%llu",
308 obj->ref_count, obj->ref_count + 1,
309 obj, obj->ref_count, obj->ref_count + 1);
310#endif
311
312 bt_object_inc_ref_count(obj);
273b65be
JG
313}
314
f167d3c0 315static inline
6871026b 316void bt_object_put_ref_no_null_check(const void *c_obj)
f167d3c0 317{
398454ed
PP
318 struct bt_object *obj = (void *) c_obj;
319
f6ccaed9 320 BT_ASSERT(obj);
3fea54f6
PP
321 BT_ASSERT(obj->is_shared);
322 BT_ASSERT(obj->ref_count > 0);
323
9358ceb3 324#ifdef _BT_OBJECT_LOGGING_ENABLED
ef267d12 325 BT_LOGT("Decrementing object's reference count: %llu -> %llu: "
3fea54f6
PP
326 "addr=%p, cur-count=%llu, new-count=%llu",
327 obj->ref_count, obj->ref_count - 1,
328 obj, obj->ref_count, obj->ref_count - 1);
329#endif
330
331 obj->ref_count--;
332
333 if (obj->ref_count == 0) {
334 BT_ASSERT(obj->release_func);
335 obj->release_func(obj);
336 }
f167d3c0
PP
337}
338
c5b9b441
PP
339static inline
340void bt_object_get_ref(const void *ptr)
341{
342 struct bt_object *obj = (void *) ptr;
343
91d81473 344 if (G_UNLIKELY(!obj)) {
c5b9b441
PP
345 return;
346 }
347
bdb288b3
PP
348#ifdef BT_ASSERT_PRE_DEV
349 BT_ASSERT_PRE_DEV(obj->is_shared, "Object is not shared: %!+O", obj);
c5b9b441
PP
350#endif
351
6871026b 352 bt_object_get_ref_no_null_check(obj);
c5b9b441
PP
353}
354
355static inline
356void bt_object_put_ref(const void *ptr)
357{
358 struct bt_object *obj = (void *) ptr;
359
91d81473 360 if (G_UNLIKELY(!obj)) {
c5b9b441
PP
361 return;
362 }
363
bdb288b3
PP
364#ifdef BT_ASSERT_PRE_DEV
365 BT_ASSERT_PRE_DEV(obj->is_shared, "Object is not shared: %!+O", obj);
366 BT_ASSERT_PRE_DEV(bt_object_get_ref_count(obj) > 0,
c5b9b441
PP
367 "Decrementing a reference count set to 0: %!+O", ptr);
368#endif
369
6871026b 370 bt_object_put_ref_no_null_check(obj);
c5b9b441
PP
371}
372
373#define BT_OBJECT_PUT_REF_AND_RESET(_var) \
374 do { \
375 bt_object_put_ref(_var); \
376 (_var) = NULL; \
377 } while (0)
378
379#define BT_OBJECT_MOVE_REF(_var_dst, _var_src) \
380 do { \
381 bt_object_put_ref(_var_dst); \
382 (_var_dst) = (_var_src); \
383 (_var_src) = NULL; \
384 } while (0)
385
83509119 386#endif /* BABELTRACE_OBJECT_INTERNAL_H */
This page took 0.096432 seconds and 4 git commands to generate.