src/lib/object.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright 2017-2018 Philippe Proulx <pproulx@efficios.com>
   5  * Copyright 2015 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   6  */
   7
   8 #ifndef BABELTRACE_OBJECT_INTERNAL_H
   9 #define BABELTRACE_OBJECT_INTERNAL_H
  10
  11 #include "common/macros.h"
  12 #include "common/assert.h"
  13 #include <stdbool.h>
  14
  15 struct bt_object;
  16
  17 typedef void (*bt_object_release_func)(struct bt_object *);
  18 typedef void (*bt_object_parent_is_owner_listener_func)(
  19                 struct bt_object *);
  20
  21 static inline
  22 void bt_object_get_ref_no_null_check(const void *obj);
  23
  24 static inline
  25 void bt_object_put_ref_no_null_check(const void *obj);
  26
  27 /*
  28  * Babeltrace object base.
  29  *
  30  * All objects publicly exposed by Babeltrace APIs must contain this
  31  * object as their first member.
  32  */
  33 struct bt_object {
  34         /*
  35          * True if this object is shared, that is, it has a reference
  36          * count.
  37          */
  38         bool is_shared;
  39
  40         /*
  41          * Current reference count.
  42          */
  43         unsigned long long ref_count;
  44
  45         /*
  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.
  50          */
  51         bt_object_release_func release_func;
  52
  53         /*
  54          * Specific release function called by
  55          * bt_object_with_parent_release_func() or directly by a
  56          * parent object.
  57          */
  58         bt_object_release_func spec_release_func;
  59
  60         /*
  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.
  64          */
  65         bt_object_parent_is_owner_listener_func
  66                 parent_is_owner_listener_func;
  67
  68         /*
  69          * Optional parent object.
  70          */
  71         struct bt_object *parent;
  72 };
  73
  74 static inline
  75 unsigned long long bt_object_get_ref_count(const struct bt_object *c_obj)
  76 {
  77         struct bt_object *obj = (void *) c_obj;
  78
  79         BT_ASSERT_DBG(obj);
  80         BT_ASSERT_DBG(obj->is_shared);
  81         return obj->ref_count;
  82 }
  83
  84 static inline
  85 struct bt_object *bt_object_borrow_parent(const struct bt_object *c_obj)
  86 {
  87         struct bt_object *obj = (void *) c_obj;
  88
  89         BT_ASSERT_DBG(obj);
  90         BT_ASSERT_DBG(obj->is_shared);
  91         return obj->parent;
  92 }
  93
  94 static inline
  95 struct bt_object *bt_object_get_parent(const struct bt_object *c_obj)
  96 {
  97         struct bt_object *obj = (void *) c_obj;
  98         struct bt_object *parent = bt_object_borrow_parent(obj);
  99
 100         if (parent) {
 101                 bt_object_get_ref_no_null_check(parent);
 102         }
 103
 104         return parent;
 105 }
 106
 107 static inline
 108 void bt_object_set_parent(struct bt_object *child, struct bt_object *parent)
 109 {
 110         BT_ASSERT_DBG(child);
 111         BT_ASSERT_DBG(child->is_shared);
 112
 113 #ifdef BT_LOGT
 114         BT_LOGT("Setting object's parent: addr=%p, parent-addr=%p",
 115                 child, parent);
 116 #endif
 117
 118         /*
 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.
 123          */
 124         if (parent) {
 125                 BT_ASSERT_DBG(!child->parent);
 126                 child->parent = parent;
 127                 bt_object_get_ref_no_null_check(parent);
 128         } else {
 129                 if (child->parent) {
 130                         bt_object_put_ref_no_null_check(child->parent);
 131                 }
 132
 133                 child->parent = NULL;
 134         }
 135 }
 136
 137 static inline
 138 void bt_object_try_spec_release(struct bt_object *obj)
 139 {
 140         BT_ASSERT_DBG(obj);
 141         BT_ASSERT_DBG(obj->is_shared);
 142         BT_ASSERT_DBG(obj->spec_release_func);
 143
 144         if (bt_object_get_ref_count(obj) == 0) {
 145                 obj->spec_release_func(obj);
 146         }
 147 }
 148
 149 static inline
 150 void bt_object_with_parent_release_func(struct bt_object *obj)
 151 {
 152         if (obj->parent) {
 153                 /*
 154                  * Keep our own copy of the parent address because `obj`
 155                  * could be destroyed in
 156                  * obj->parent_is_owner_listener_func().
 157                  */
 158                 struct bt_object *parent = obj->parent;
 159
 160 #ifdef BT_LOGT
 161                 BT_LOGT("Releasing parented object: addr=%p, ref-count=%llu, "
 162                         "parent-addr=%p, parent-ref-count=%llu",
 163                         obj, obj->ref_count,
 164                         parent, parent->ref_count);
 165 #endif
 166
 167                 if (obj->parent_is_owner_listener_func) {
 168                         /*
 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.
 173                          */
 174                         obj->parent_is_owner_listener_func(obj);
 175                 }
 176
 177                 /* The release function will be invoked by the parent. */
 178                 bt_object_put_ref_no_null_check(parent);
 179         } else {
 180                 bt_object_try_spec_release(obj);
 181         }
 182 }
 183
 184 static inline
 185 void bt_object_init(struct bt_object *obj, bool is_shared,
 186                 bt_object_release_func release_func)
 187 {
 188         BT_ASSERT_DBG(obj);
 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;
 194         obj->parent = NULL;
 195         obj->ref_count = 1;
 196 }
 197
 198 static inline
 199 void bt_object_init_shared(struct bt_object *obj,
 200                 bt_object_release_func release_func)
 201 {
 202         bt_object_init(obj, true, release_func);
 203 }
 204
 205 static inline
 206 void bt_object_init_unique(struct bt_object *obj)
 207 {
 208         bt_object_init(obj, false, NULL);
 209 }
 210
 211 static inline
 212 void bt_object_init_shared_with_parent(struct bt_object *obj,
 213                 bt_object_release_func spec_release_func)
 214 {
 215         BT_ASSERT_DBG(obj);
 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;
 219 }
 220
 221 static inline
 222 void bt_object_set_parent_is_owner_listener_func(struct bt_object *obj,
 223                 bt_object_parent_is_owner_listener_func func)
 224 {
 225         BT_ASSERT_DBG(obj);
 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;
 229 }
 230
 231 static inline
 232 void bt_object_inc_ref_count(const struct bt_object *c_obj)
 233 {
 234         struct bt_object *obj = (void *) c_obj;
 235
 236         BT_ASSERT_DBG(obj);
 237         BT_ASSERT_DBG(obj->is_shared);
 238         obj->ref_count++;
 239         BT_ASSERT_DBG(obj->ref_count != 0);
 240 }
 241
 242 static inline
 243 void bt_object_get_ref_no_null_check_no_parent_check(const struct bt_object *c_obj)
 244 {
 245         struct bt_object *obj = (void *) c_obj;
 246
 247         BT_ASSERT_DBG(obj);
 248         BT_ASSERT_DBG(obj->is_shared);
 249
 250 #ifdef BT_LOGT
 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);
 255 #endif
 256
 257         bt_object_inc_ref_count(obj);
 258 }
 259
 260 static inline
 261 void bt_object_get_ref_no_null_check(const void *c_obj)
 262 {
 263         struct bt_object *obj = (void *) c_obj;
 264
 265         BT_ASSERT_DBG(obj);
 266         BT_ASSERT_DBG(obj->is_shared);
 267
 268         if (G_UNLIKELY(obj->parent && bt_object_get_ref_count(obj) == 0)) {
 269 #ifdef BT_LOGT
 270                 BT_LOGT("Incrementing object's parent's reference count: "
 271                         "addr=%p, parent-addr=%p", obj, obj->parent);
 272 #endif
 273
 274                 bt_object_get_ref_no_null_check(obj->parent);
 275         }
 276
 277 #ifdef BT_LOGT
 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);
 282 #endif
 283
 284         bt_object_inc_ref_count(obj);
 285 }
 286
 287 static inline
 288 void bt_object_put_ref_no_null_check(const void *c_obj)
 289 {
 290         struct bt_object *obj = (void *) c_obj;
 291
 292         BT_ASSERT_DBG(obj);
 293         BT_ASSERT_DBG(obj->is_shared);
 294         BT_ASSERT_DBG(obj->ref_count > 0);
 295
 296 #ifdef BT_LOGT
 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);
 301 #endif
 302
 303         obj->ref_count--;
 304
 305         if (obj->ref_count == 0) {
 306                 BT_ASSERT_DBG(obj->release_func);
 307                 obj->release_func(obj);
 308         }
 309 }
 310
 311 static inline
 312 void bt_object_get_ref(const void *ptr)
 313 {
 314         struct bt_object *obj = (void *) ptr;
 315
 316         if (G_UNLIKELY(!obj)) {
 317                 return;
 318         }
 319
 320 #ifdef BT_ASSERT_PRE_DEV
 321         BT_ASSERT_PRE_DEV(obj->is_shared, "Object is not shared: %!+O", obj);
 322 #endif
 323
 324         bt_object_get_ref_no_null_check(obj);
 325 }
 326
 327 static inline
 328 void bt_object_put_ref(const void *ptr)
 329 {
 330         struct bt_object *obj = (void *) ptr;
 331
 332         if (G_UNLIKELY(!obj)) {
 333                 return;
 334         }
 335
 336 #ifdef BT_ASSERT_PRE_DEV
 337         BT_ASSERT_PRE_DEV(obj->is_shared, "Object is not shared: %!+O", obj);
 338         BT_ASSERT_PRE_DEV(bt_object_get_ref_count(obj) > 0,
 339                 "Decrementing a reference count set to 0: %!+O", ptr);
 340 #endif
 341
 342         bt_object_put_ref_no_null_check(obj);
 343 }
 344
 345 #define BT_OBJECT_PUT_REF_AND_RESET(_var)       \
 346         do {                                    \
 347                 bt_object_put_ref(_var);        \
 348                 (_var) = NULL;                  \
 349         } while (0)
 350
 351 #define BT_OBJECT_MOVE_REF(_var_dst, _var_src)  \
 352         do {                                    \
 353                 bt_object_put_ref(_var_dst);    \
 354                 (_var_dst) = (_var_src);        \
 355                 (_var_src) = NULL;              \
 356         } while (0)
 357
 358 #endif /* BABELTRACE_OBJECT_INTERNAL_H */