1 #ifndef BABELTRACE_OBJECT_INTERNAL_H
2 #define BABELTRACE_OBJECT_INTERNAL_H
5 * Babeltrace - Base object
7 * Copyright 2015 Jérémie Galarneau <jeremie.galarneau@efficios.com>
9 * Author: 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
30 #include <babeltrace/babeltrace-internal.h>
31 #include <babeltrace/assert-internal.h>
36 typedef void (*bt_object_release_func
)(struct bt_object
*);
37 typedef void (*bt_object_parent_is_owner_listener_func
)(
41 void bt_object_get_no_null_check(struct bt_object
*obj
);
44 void bt_object_put_no_null_check(struct bt_object
*obj
);
47 * Babeltrace object base.
49 * All objects publicly exposed by Babeltrace APIs must contain this
50 * object as their first member.
54 * True if this object is shared, that is, it has a reference
60 * Current reference count.
62 unsigned long long ref_count
;
65 * Release function called when the object's reference count
66 * falls to zero. For an object with a parent, this function is
67 * bt_object_with_parent_release_func(), which calls
68 * `spec_release_func` below if there's no current parent.
70 bt_object_release_func release_func
;
73 * Specific release function called by
74 * bt_object_with_parent_release_func() or directly by a
77 bt_object_release_func spec_release_func
;
80 * Optional callback for an object with a parent, called by
81 * bt_object_with_parent_release_func() to indicate to the
82 * object that its parent is its owner.
84 bt_object_parent_is_owner_listener_func
85 parent_is_owner_listener_func
;
88 * Optional parent object.
90 struct bt_object
*parent
;
94 unsigned long long bt_object_get_ref_count(struct bt_object
*obj
)
97 BT_ASSERT(obj
->is_shared
);
98 return obj
->ref_count
;
102 struct bt_object
*bt_object_borrow_parent(struct bt_object
*obj
)
105 BT_ASSERT(obj
->is_shared
);
110 struct bt_object
*bt_object_get_parent(struct bt_object
*obj
)
112 struct bt_object
*parent
= bt_object_borrow_parent(obj
);
115 bt_object_get_no_null_check(parent
);
122 void bt_object_set_parent(struct bt_object
*child
, struct bt_object
*parent
)
125 BT_ASSERT(child
->is_shared
);
128 BT_LOGV("Setting object's parent: addr=%p, parent-addr=%p",
133 * It is assumed that a "child" having a parent is publicly
134 * reachable. Therefore, a reference to its parent must be
135 * taken. The reference to the parent will be released once the
136 * object's reference count falls to zero.
139 BT_ASSERT(!child
->parent
);
140 child
->parent
= parent
;
141 bt_object_get_no_null_check(parent
);
144 bt_object_put_no_null_check(child
->parent
);
147 child
->parent
= NULL
;
152 void bt_object_try_spec_release(struct bt_object
*obj
)
155 BT_ASSERT(obj
->is_shared
);
156 BT_ASSERT(obj
->spec_release_func
);
158 if (bt_object_get_ref_count(obj
) == 0) {
159 obj
->spec_release_func(obj
);
164 void bt_object_with_parent_release_func(struct bt_object
*obj
)
168 * Keep our own copy of the parent address because `obj`
169 * could be destroyed in
170 * obj->parent_is_owner_listener_func().
172 struct bt_object
*parent
= obj
->parent
;
175 BT_LOGV("Releasing parented object: addr=%p, ref-count=%llu, "
176 "parent-addr=%p, parent-ref-count=%llu",
178 parent
, parent
->ref_count
);
181 if (obj
->parent_is_owner_listener_func
) {
183 * Object has a chance to destroy itself here
184 * under certain conditions and notify its
185 * parent. At this point the parent is
186 * guaranteed to exist because it's not put yet.
188 obj
->parent_is_owner_listener_func(obj
);
191 /* The release function will be invoked by the parent. */
192 bt_object_put_no_null_check(parent
);
194 bt_object_try_spec_release(obj
);
199 void bt_object_init(struct bt_object
*obj
, bool is_shared
,
200 bt_object_release_func release_func
)
203 BT_ASSERT(!is_shared
|| release_func
);
204 obj
->is_shared
= is_shared
;
205 obj
->release_func
= release_func
;
206 obj
->parent_is_owner_listener_func
= NULL
;
207 obj
->spec_release_func
= NULL
;
213 void bt_object_init_shared(struct bt_object
*obj
,
214 bt_object_release_func release_func
)
216 bt_object_init(obj
, true, release_func
);
220 void bt_object_init_unique(struct bt_object
*obj
)
222 bt_object_init(obj
, false, NULL
);
226 void bt_object_init_shared_with_parent(struct bt_object
*obj
,
227 bt_object_release_func spec_release_func
)
230 BT_ASSERT(spec_release_func
);
231 bt_object_init_shared(obj
, bt_object_with_parent_release_func
);
232 obj
->spec_release_func
= spec_release_func
;
236 void bt_object_set_parent_is_owner_listener_func(struct bt_object
*obj
,
237 bt_object_parent_is_owner_listener_func func
)
240 BT_ASSERT(obj
->is_shared
);
241 BT_ASSERT(obj
->spec_release_func
);
242 ((struct bt_object
*) obj
)->parent_is_owner_listener_func
= func
;
246 void bt_object_inc_ref_count(struct bt_object
*obj
)
249 BT_ASSERT(obj
->is_shared
);
251 BT_ASSERT(obj
->ref_count
!= 0);
255 void bt_object_get_no_null_check(struct bt_object
*obj
)
258 BT_ASSERT(obj
->is_shared
);
260 if (unlikely(obj
->parent
&& bt_object_get_ref_count(obj
) == 0)) {
262 BT_LOGV("Incrementing object's parent's reference count: "
263 "addr=%p, parent-addr=%p", obj
, obj
->parent
);
266 bt_object_get_no_null_check(obj
->parent
);
270 BT_LOGV("Incrementing object's reference count: %llu -> %llu: "
271 "addr=%p, cur-count=%llu, new-count=%llu",
272 obj
->ref_count
, obj
->ref_count
+ 1,
273 obj
, obj
->ref_count
, obj
->ref_count
+ 1);
276 bt_object_inc_ref_count(obj
);
280 void bt_object_put_no_null_check(struct bt_object
*obj
)
283 BT_ASSERT(obj
->is_shared
);
284 BT_ASSERT(obj
->ref_count
> 0);
287 BT_LOGV("Decrementing object's reference count: %llu -> %llu: "
288 "addr=%p, cur-count=%llu, new-count=%llu",
289 obj
->ref_count
, obj
->ref_count
- 1,
290 obj
, obj
->ref_count
, obj
->ref_count
- 1);
295 if (obj
->ref_count
== 0) {
296 BT_ASSERT(obj
->release_func
);
297 obj
->release_func(obj
);
301 #endif /* BABELTRACE_OBJECT_INTERNAL_H */