2 * SPDX-License-Identifier: MIT
4 * Copyright 2017-2018 Philippe Proulx <pproulx@efficios.com>
5 * Copyright 2015 Jérémie Galarneau <jeremie.galarneau@efficios.com>
8 #ifndef BABELTRACE_OBJECT_INTERNAL_H
9 #define BABELTRACE_OBJECT_INTERNAL_H
11 #include "common/macros.h"
12 #include "common/assert.h"
17 typedef void (*bt_object_release_func
)(struct bt_object
*);
18 typedef void (*bt_object_parent_is_owner_listener_func
)(
22 void bt_object_get_ref_no_null_check(const void *obj
);
25 void bt_object_put_ref_no_null_check(const void *obj
);
28 * Babeltrace object base.
30 * All objects publicly exposed by Babeltrace APIs must contain this
31 * object as their first member.
35 * True if this object is shared, that is, it has a reference
41 * Current reference count.
43 unsigned long long ref_count
;
46 * Release function called when the object's reference count
47 * falls to zero. For an object with a parent, this function is
48 * bt_object_with_parent_release_func(), which calls
49 * `spec_release_func` below if there's no current parent.
51 bt_object_release_func release_func
;
54 * Specific release function called by
55 * bt_object_with_parent_release_func() or directly by a
58 bt_object_release_func spec_release_func
;
61 * Optional callback for an object with a parent, called by
62 * bt_object_with_parent_release_func() to indicate to the
63 * object that its parent is its owner.
65 bt_object_parent_is_owner_listener_func
66 parent_is_owner_listener_func
;
69 * Optional parent object.
71 struct bt_object
*parent
;
75 unsigned long long bt_object_get_ref_count(const struct bt_object
*c_obj
)
77 struct bt_object
*obj
= (void *) c_obj
;
80 BT_ASSERT_DBG(obj
->is_shared
);
81 return obj
->ref_count
;
85 struct bt_object
*bt_object_borrow_parent(const struct bt_object
*c_obj
)
87 struct bt_object
*obj
= (void *) c_obj
;
90 BT_ASSERT_DBG(obj
->is_shared
);
95 struct bt_object
*bt_object_get_parent(const struct bt_object
*c_obj
)
97 struct bt_object
*obj
= (void *) c_obj
;
98 struct bt_object
*parent
= bt_object_borrow_parent(obj
);
101 bt_object_get_ref_no_null_check(parent
);
108 void bt_object_set_parent(struct bt_object
*child
, struct bt_object
*parent
)
110 BT_ASSERT_DBG(child
);
111 BT_ASSERT_DBG(child
->is_shared
);
114 BT_LOGT("Setting object's parent: addr=%p, parent-addr=%p",
119 * It is assumed that a "child" having a parent is publicly
120 * reachable. Therefore, a reference to its parent must be
121 * taken. The reference to the parent will be released once the
122 * object's reference count falls to zero.
125 BT_ASSERT_DBG(!child
->parent
);
126 child
->parent
= parent
;
127 bt_object_get_ref_no_null_check(parent
);
130 bt_object_put_ref_no_null_check(child
->parent
);
133 child
->parent
= NULL
;
138 void bt_object_try_spec_release(struct bt_object
*obj
)
141 BT_ASSERT_DBG(obj
->is_shared
);
142 BT_ASSERT_DBG(obj
->spec_release_func
);
144 if (bt_object_get_ref_count(obj
) == 0) {
145 obj
->spec_release_func(obj
);
150 void bt_object_with_parent_release_func(struct bt_object
*obj
)
154 * Keep our own copy of the parent address because `obj`
155 * could be destroyed in
156 * obj->parent_is_owner_listener_func().
158 struct bt_object
*parent
= obj
->parent
;
161 BT_LOGT("Releasing parented object: addr=%p, ref-count=%llu, "
162 "parent-addr=%p, parent-ref-count=%llu",
164 parent
, parent
->ref_count
);
167 if (obj
->parent_is_owner_listener_func
) {
169 * Object has a chance to destroy itself here
170 * under certain conditions and notify its
171 * parent. At this point the parent is
172 * guaranteed to exist because it's not put yet.
174 obj
->parent_is_owner_listener_func(obj
);
177 /* The release function will be invoked by the parent. */
178 bt_object_put_ref_no_null_check(parent
);
180 bt_object_try_spec_release(obj
);
185 void bt_object_init(struct bt_object
*obj
, bool is_shared
,
186 bt_object_release_func release_func
)
189 BT_ASSERT_DBG(!is_shared
|| release_func
);
190 obj
->is_shared
= is_shared
;
191 obj
->release_func
= release_func
;
192 obj
->parent_is_owner_listener_func
= NULL
;
193 obj
->spec_release_func
= NULL
;
199 void bt_object_init_shared(struct bt_object
*obj
,
200 bt_object_release_func release_func
)
202 bt_object_init(obj
, true, release_func
);
206 void bt_object_init_unique(struct bt_object
*obj
)
208 bt_object_init(obj
, false, NULL
);
212 void bt_object_init_shared_with_parent(struct bt_object
*obj
,
213 bt_object_release_func spec_release_func
)
216 BT_ASSERT_DBG(spec_release_func
);
217 bt_object_init_shared(obj
, bt_object_with_parent_release_func
);
218 obj
->spec_release_func
= spec_release_func
;
222 void bt_object_set_parent_is_owner_listener_func(struct bt_object
*obj
,
223 bt_object_parent_is_owner_listener_func func
)
226 BT_ASSERT_DBG(obj
->is_shared
);
227 BT_ASSERT_DBG(obj
->spec_release_func
);
228 ((struct bt_object
*) obj
)->parent_is_owner_listener_func
= func
;
232 void bt_object_inc_ref_count(const struct bt_object
*c_obj
)
234 struct bt_object
*obj
= (void *) c_obj
;
237 BT_ASSERT_DBG(obj
->is_shared
);
239 BT_ASSERT_DBG(obj
->ref_count
!= 0);
243 void bt_object_get_ref_no_null_check_no_parent_check(const struct bt_object
*c_obj
)
245 struct bt_object
*obj
= (void *) c_obj
;
248 BT_ASSERT_DBG(obj
->is_shared
);
251 BT_LOGT("Incrementing object's reference count: %llu -> %llu: "
252 "addr=%p, cur-count=%llu, new-count=%llu",
253 obj
->ref_count
, obj
->ref_count
+ 1,
254 obj
, obj
->ref_count
, obj
->ref_count
+ 1);
257 bt_object_inc_ref_count(obj
);
261 void bt_object_get_ref_no_null_check(const void *c_obj
)
263 struct bt_object
*obj
= (void *) c_obj
;
266 BT_ASSERT_DBG(obj
->is_shared
);
268 if (G_UNLIKELY(obj
->parent
&& bt_object_get_ref_count(obj
) == 0)) {
270 BT_LOGT("Incrementing object's parent's reference count: "
271 "addr=%p, parent-addr=%p", obj
, obj
->parent
);
274 bt_object_get_ref_no_null_check(obj
->parent
);
278 BT_LOGT("Incrementing object's reference count: %llu -> %llu: "
279 "addr=%p, cur-count=%llu, new-count=%llu",
280 obj
->ref_count
, obj
->ref_count
+ 1,
281 obj
, obj
->ref_count
, obj
->ref_count
+ 1);
284 bt_object_inc_ref_count(obj
);
288 void bt_object_put_ref_no_null_check(const void *c_obj
)
290 struct bt_object
*obj
= (void *) c_obj
;
293 BT_ASSERT_DBG(obj
->is_shared
);
294 BT_ASSERT_DBG(obj
->ref_count
> 0);
297 BT_LOGT("Decrementing object's reference count: %llu -> %llu: "
298 "addr=%p, cur-count=%llu, new-count=%llu",
299 obj
->ref_count
, obj
->ref_count
- 1,
300 obj
, obj
->ref_count
, obj
->ref_count
- 1);
305 if (obj
->ref_count
== 0) {
306 BT_ASSERT_DBG(obj
->release_func
);
307 obj
->release_func(obj
);
312 void bt_object_get_ref(const void *ptr
)
314 struct bt_object
*obj
= (void *) ptr
;
316 if (G_UNLIKELY(!obj
)) {
320 BT_ASSERT_DBG(obj
->is_shared
);
321 bt_object_get_ref_no_null_check(obj
);
325 void bt_object_put_ref(const void *ptr
)
327 struct bt_object
*obj
= (void *) ptr
;
329 if (G_UNLIKELY(!obj
)) {
333 BT_ASSERT_DBG(obj
->is_shared
);
334 BT_ASSERT_DBG(bt_object_get_ref_count(obj
) > 0);
335 bt_object_put_ref_no_null_check(obj
);
338 #define BT_OBJECT_PUT_REF_AND_RESET(_var) \
340 bt_object_put_ref(_var); \
344 #define BT_OBJECT_MOVE_REF(_var_dst, _var_src) \
346 bt_object_put_ref(_var_dst); \
347 (_var_dst) = (_var_src); \
351 #endif /* BABELTRACE_OBJECT_INTERNAL_H */