include/babeltrace/object-internal.h

   1 #ifndef BABELTRACE_OBJECT_INTERNAL_H
   2 #define BABELTRACE_OBJECT_INTERNAL_H
   3
   4 /*
   5  * Babeltrace - Base object
   6  *
   7  * Copyright 2015 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   8  *
   9  * Author: 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 #include <babeltrace/babeltrace-internal.h>
  31 #include <babeltrace/assert-internal.h>
  32 #include <stdbool.h>
  33
  34 struct bt_object;
  35
  36 typedef void (*bt_object_release_func)(struct bt_object *);
  37 typedef void (*bt_object_parent_is_owner_listener_func)(
  38                 struct bt_object *);
  39
  40 static inline
  41 void bt_object_get_no_null_check(struct bt_object *obj);
  42
  43 static inline
  44 void bt_object_put_no_null_check(struct bt_object *obj);
  45
  46 /*
  47  * Babeltrace object base.
  48  *
  49  * All objects publicly exposed by Babeltrace APIs must contain this
  50  * object as their first member.
  51  */
  52 struct bt_object {
  53         /*
  54          * True if this object is shared, that is, it has a reference
  55          * count.
  56          */
  57         bool is_shared;
  58
  59         /*
  60          * Current reference count.
  61          */
  62         unsigned long long ref_count;
  63
  64         /*
  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.
  69          */
  70         bt_object_release_func release_func;
  71
  72         /*
  73          * Specific release function called by
  74          * bt_object_with_parent_release_func() or directly by a
  75          * parent object.
  76          */
  77         bt_object_release_func spec_release_func;
  78
  79         /*
  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.
  83          */
  84         bt_object_parent_is_owner_listener_func
  85                 parent_is_owner_listener_func;
  86
  87         /*
  88          * Optional parent object.
  89          */
  90         struct bt_object *parent;
  91 };
  92
  93 static inline
  94 unsigned long long bt_object_get_ref_count(struct bt_object *obj)
  95 {
  96         BT_ASSERT(obj);
  97         BT_ASSERT(obj->is_shared);
  98         return obj->ref_count;
  99 }
 100
 101 static inline
 102 struct bt_object *bt_object_borrow_parent(struct bt_object *obj)
 103 {
 104         BT_ASSERT(obj);
 105         BT_ASSERT(obj->is_shared);
 106         return obj->parent;
 107 }
 108
 109 static inline
 110 struct bt_object *bt_object_get_parent(struct bt_object *obj)
 111 {
 112         struct bt_object *parent = bt_object_borrow_parent(obj);
 113
 114         if (parent) {
 115                 bt_object_get_no_null_check(parent);
 116         }
 117
 118         return parent;
 119 }
 120
 121 static inline
 122 void bt_object_set_parent(struct bt_object *child, struct bt_object *parent)
 123 {
 124         BT_ASSERT(child);
 125         BT_ASSERT(child->is_shared);
 126
 127 #ifdef BT_LOGV
 128         BT_LOGV("Setting object's parent: addr=%p, parent-addr=%p",
 129                 child, parent);
 130 #endif
 131
 132         /*
 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.
 137          */
 138         if (parent) {
 139                 BT_ASSERT(!child->parent);
 140                 child->parent = parent;
 141                 bt_object_get_no_null_check(parent);
 142         } else {
 143                 if (child->parent) {
 144                         bt_object_put_no_null_check(child->parent);
 145                 }
 146
 147                 child->parent = NULL;
 148         }
 149 }
 150
 151 static inline
 152 void bt_object_try_spec_release(struct bt_object *obj)
 153 {
 154         BT_ASSERT(obj);
 155         BT_ASSERT(obj->is_shared);
 156         BT_ASSERT(obj->spec_release_func);
 157
 158         if (bt_object_get_ref_count(obj) == 0) {
 159                 obj->spec_release_func(obj);
 160         }
 161 }
 162
 163 static inline
 164 void bt_object_with_parent_release_func(struct bt_object *obj)
 165 {
 166         if (obj->parent) {
 167                 /*
 168                  * Keep our own copy of the parent address because `obj`
 169                  * could be destroyed in
 170                  * obj->parent_is_owner_listener_func().
 171                  */
 172                 struct bt_object *parent = obj->parent;
 173
 174 #ifdef BT_LOGV
 175                 BT_LOGV("Releasing parented object: addr=%p, ref-count=%llu, "
 176                         "parent-addr=%p, parent-ref-count=%llu",
 177                         obj, obj->ref_count,
 178                         parent, parent->ref_count);
 179 #endif
 180
 181                 if (obj->parent_is_owner_listener_func) {
 182                         /*
 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.
 187                          */
 188                         obj->parent_is_owner_listener_func(obj);
 189                 }
 190
 191                 /* The release function will be invoked by the parent. */
 192                 bt_object_put_no_null_check(parent);
 193         } else {
 194                 bt_object_try_spec_release(obj);
 195         }
 196 }
 197
 198 static inline
 199 void bt_object_init(struct bt_object *obj, bool is_shared,
 200                 bt_object_release_func release_func)
 201 {
 202         BT_ASSERT(obj);
 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;
 208         obj->parent = NULL;
 209         obj->ref_count = 1;
 210 }
 211
 212 static inline
 213 void bt_object_init_shared(struct bt_object *obj,
 214                 bt_object_release_func release_func)
 215 {
 216         bt_object_init(obj, true, release_func);
 217 }
 218
 219 static inline
 220 void bt_object_init_unique(struct bt_object *obj)
 221 {
 222         bt_object_init(obj, false, NULL);
 223 }
 224
 225 static inline
 226 void bt_object_init_shared_with_parent(struct bt_object *obj,
 227                 bt_object_release_func spec_release_func)
 228 {
 229         BT_ASSERT(obj);
 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;
 233 }
 234
 235 static inline
 236 void bt_object_set_parent_is_owner_listener_func(struct bt_object *obj,
 237                 bt_object_parent_is_owner_listener_func func)
 238 {
 239         BT_ASSERT(obj);
 240         BT_ASSERT(obj->is_shared);
 241         BT_ASSERT(obj->spec_release_func);
 242         ((struct bt_object *) obj)->parent_is_owner_listener_func = func;
 243 }
 244
 245 static inline
 246 void bt_object_inc_ref_count(struct bt_object *obj)
 247 {
 248         BT_ASSERT(obj);
 249         BT_ASSERT(obj->is_shared);
 250         obj->ref_count++;
 251         BT_ASSERT(obj->ref_count != 0);
 252 }
 253
 254 static inline
 255 void bt_object_get_no_null_check_no_parent_check(struct bt_object *obj)
 256 {
 257         BT_ASSERT(obj);
 258         BT_ASSERT(obj->is_shared);
 259
 260 #ifdef BT_LOGV
 261         BT_LOGV("Incrementing object's reference count: %llu -> %llu: "
 262                 "addr=%p, cur-count=%llu, new-count=%llu",
 263                 obj->ref_count, obj->ref_count + 1,
 264                 obj, obj->ref_count, obj->ref_count + 1);
 265 #endif
 266
 267         bt_object_inc_ref_count(obj);
 268 }
 269
 270 static inline
 271 void bt_object_get_no_null_check(struct bt_object *obj)
 272 {
 273         BT_ASSERT(obj);
 274         BT_ASSERT(obj->is_shared);
 275
 276         if (unlikely(obj->parent && bt_object_get_ref_count(obj) == 0)) {
 277 #ifdef BT_LOGV
 278                 BT_LOGV("Incrementing object's parent's reference count: "
 279                         "addr=%p, parent-addr=%p", obj, obj->parent);
 280 #endif
 281
 282                 bt_object_get_no_null_check(obj->parent);
 283         }
 284
 285 #ifdef BT_LOGV
 286         BT_LOGV("Incrementing object's reference count: %llu -> %llu: "
 287                 "addr=%p, cur-count=%llu, new-count=%llu",
 288                 obj->ref_count, obj->ref_count + 1,
 289                 obj, obj->ref_count, obj->ref_count + 1);
 290 #endif
 291
 292         bt_object_inc_ref_count(obj);
 293 }
 294
 295 static inline
 296 void bt_object_put_no_null_check(struct bt_object *obj)
 297 {
 298         BT_ASSERT(obj);
 299         BT_ASSERT(obj->is_shared);
 300         BT_ASSERT(obj->ref_count > 0);
 301
 302 #ifdef BT_LOGV
 303         BT_LOGV("Decrementing object's reference count: %llu -> %llu: "
 304                 "addr=%p, cur-count=%llu, new-count=%llu",
 305                 obj->ref_count, obj->ref_count - 1,
 306                 obj, obj->ref_count, obj->ref_count - 1);
 307 #endif
 308
 309         obj->ref_count--;
 310
 311         if (obj->ref_count == 0) {
 312                 BT_ASSERT(obj->release_func);
 313                 obj->release_func(obj);
 314         }
 315 }
 316
 317 #endif /* BABELTRACE_OBJECT_INTERNAL_H */