include/babeltrace/object-internal.h

   1 #ifndef BABELTRACE_OBJECT_INTERNAL_H
   2 #define BABELTRACE_OBJECT_INTERNAL_H
   3
   4 /*
   5  * Copyright 2015 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   6  *
   7  * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
   8  *
   9  * Permission is hereby granted, free of charge, to any person obtaining a copy
  10  * of this software and associated documentation files (the "Software"), to deal
  11  * in the Software without restriction, including without limitation the rights
  12  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  13  * copies of the Software, and to permit persons to whom the Software is
  14  * furnished to do so, subject to the following conditions:
  15  *
  16  * The above copyright notice and this permission notice shall be included in
  17  * all copies or substantial portions of the Software.
  18  *
  19  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  20  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  21  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  22  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  23  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  24  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  25  * SOFTWARE.
  26  */
  27
  28 #include <babeltrace/babeltrace-internal.h>
  29 #include <babeltrace/assert-internal.h>
  30 #include <stdbool.h>
  31
  32 struct bt_object;
  33
  34 typedef void (*bt_object_release_func)(struct bt_object *);
  35 typedef void (*bt_object_parent_is_owner_listener_func)(
  36                 struct bt_object *);
  37
  38 static inline
  39 void bt_object_get_no_null_check(const void *obj);
  40
  41 static inline
  42 void bt_object_put_no_null_check(const void *obj);
  43
  44 /*
  45  * Babeltrace object base.
  46  *
  47  * All objects publicly exposed by Babeltrace APIs must contain this
  48  * object as their first member.
  49  */
  50 struct bt_object {
  51         /*
  52          * True if this object is shared, that is, it has a reference
  53          * count.
  54          */
  55         bool is_shared;
  56
  57         /*
  58          * Current reference count.
  59          */
  60         unsigned long long ref_count;
  61
  62         /*
  63          * Release function called when the object's reference count
  64          * falls to zero. For an object with a parent, this function is
  65          * bt_object_with_parent_release_func(), which calls
  66          * `spec_release_func` below if there's no current parent.
  67          */
  68         bt_object_release_func release_func;
  69
  70         /*
  71          * Specific release function called by
  72          * bt_object_with_parent_release_func() or directly by a
  73          * parent object.
  74          */
  75         bt_object_release_func spec_release_func;
  76
  77         /*
  78          * Optional callback for an object with a parent, called by
  79          * bt_object_with_parent_release_func() to indicate to the
  80          * object that its parent is its owner.
  81          */
  82         bt_object_parent_is_owner_listener_func
  83                 parent_is_owner_listener_func;
  84
  85         /*
  86          * Optional parent object.
  87          */
  88         struct bt_object *parent;
  89 };
  90
  91 static inline
  92 unsigned long long bt_object_get_ref_count(const struct bt_object *c_obj)
  93 {
  94         struct bt_object *obj = (void *) c_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(const struct bt_object *c_obj)
 103 {
 104         struct bt_object *obj = (void *) c_obj;
 105
 106         BT_ASSERT(obj);
 107         BT_ASSERT(obj->is_shared);
 108         return obj->parent;
 109 }
 110
 111 static inline
 112 struct bt_object *bt_object_get_parent(const struct bt_object *c_obj)
 113 {
 114         struct bt_object *obj = (void *) c_obj;
 115         struct bt_object *parent = bt_object_borrow_parent(obj);
 116
 117         if (parent) {
 118                 bt_object_get_no_null_check(parent);
 119         }
 120
 121         return parent;
 122 }
 123
 124 static inline
 125 void bt_object_set_parent(struct bt_object *child, struct bt_object *parent)
 126 {
 127         BT_ASSERT(child);
 128         BT_ASSERT(child->is_shared);
 129
 130 #ifdef BT_LOGV
 131         BT_LOGV("Setting object's parent: addr=%p, parent-addr=%p",
 132                 child, parent);
 133 #endif
 134
 135         /*
 136          * It is assumed that a "child" having a parent is publicly
 137          * reachable. Therefore, a reference to its parent must be
 138          * taken. The reference to the parent will be released once the
 139          * object's reference count falls to zero.
 140          */
 141         if (parent) {
 142                 BT_ASSERT(!child->parent);
 143                 child->parent = parent;
 144                 bt_object_get_no_null_check(parent);
 145         } else {
 146                 if (child->parent) {
 147                         bt_object_put_no_null_check(child->parent);
 148                 }
 149
 150                 child->parent = NULL;
 151         }
 152 }
 153
 154 static inline
 155 void bt_object_try_spec_release(struct bt_object *obj)
 156 {
 157         BT_ASSERT(obj);
 158         BT_ASSERT(obj->is_shared);
 159         BT_ASSERT(obj->spec_release_func);
 160
 161         if (bt_object_get_ref_count(obj) == 0) {
 162                 obj->spec_release_func(obj);
 163         }
 164 }
 165
 166 static inline
 167 void bt_object_with_parent_release_func(struct bt_object *obj)
 168 {
 169         if (obj->parent) {
 170                 /*
 171                  * Keep our own copy of the parent address because `obj`
 172                  * could be destroyed in
 173                  * obj->parent_is_owner_listener_func().
 174                  */
 175                 struct bt_object *parent = obj->parent;
 176
 177 #ifdef BT_LOGV
 178                 BT_LOGV("Releasing parented object: addr=%p, ref-count=%llu, "
 179                         "parent-addr=%p, parent-ref-count=%llu",
 180                         obj, obj->ref_count,
 181                         parent, parent->ref_count);
 182 #endif
 183
 184                 if (obj->parent_is_owner_listener_func) {
 185                         /*
 186                          * Object has a chance to destroy itself here
 187                          * under certain conditions and notify its
 188                          * parent. At this point the parent is
 189                          * guaranteed to exist because it's not put yet.
 190                          */
 191                         obj->parent_is_owner_listener_func(obj);
 192                 }
 193
 194                 /* The release function will be invoked by the parent. */
 195                 bt_object_put_no_null_check(parent);
 196         } else {
 197                 bt_object_try_spec_release(obj);
 198         }
 199 }
 200
 201 static inline
 202 void bt_object_init(struct bt_object *obj, bool is_shared,
 203                 bt_object_release_func release_func)
 204 {
 205         BT_ASSERT(obj);
 206         BT_ASSERT(!is_shared || release_func);
 207         obj->is_shared = is_shared;
 208         obj->release_func = release_func;
 209         obj->parent_is_owner_listener_func = NULL;
 210         obj->spec_release_func = NULL;
 211         obj->parent = NULL;
 212         obj->ref_count = 1;
 213 }
 214
 215 static inline
 216 void bt_object_init_shared(struct bt_object *obj,
 217                 bt_object_release_func release_func)
 218 {
 219         bt_object_init(obj, true, release_func);
 220 }
 221
 222 static inline
 223 void bt_object_init_unique(struct bt_object *obj)
 224 {
 225         bt_object_init(obj, false, NULL);
 226 }
 227
 228 static inline
 229 void bt_object_init_shared_with_parent(struct bt_object *obj,
 230                 bt_object_release_func spec_release_func)
 231 {
 232         BT_ASSERT(obj);
 233         BT_ASSERT(spec_release_func);
 234         bt_object_init_shared(obj, bt_object_with_parent_release_func);
 235         obj->spec_release_func = spec_release_func;
 236 }
 237
 238 static inline
 239 void bt_object_set_parent_is_owner_listener_func(struct bt_object *obj,
 240                 bt_object_parent_is_owner_listener_func func)
 241 {
 242         BT_ASSERT(obj);
 243         BT_ASSERT(obj->is_shared);
 244         BT_ASSERT(obj->spec_release_func);
 245         ((struct bt_object *) obj)->parent_is_owner_listener_func = func;
 246 }
 247
 248 static inline
 249 void bt_object_inc_ref_count(const struct bt_object *c_obj)
 250 {
 251         struct bt_object *obj = (void *) c_obj;
 252
 253         BT_ASSERT(obj);
 254         BT_ASSERT(obj->is_shared);
 255         obj->ref_count++;
 256         BT_ASSERT(obj->ref_count != 0);
 257 }
 258
 259 static inline
 260 void bt_object_get_no_null_check_no_parent_check(const struct bt_object *c_obj)
 261 {
 262         struct bt_object *obj = (void *) c_obj;
 263
 264         BT_ASSERT(obj);
 265         BT_ASSERT(obj->is_shared);
 266
 267 #ifdef BT_LOGV
 268         BT_LOGV("Incrementing object's reference count: %llu -> %llu: "
 269                 "addr=%p, cur-count=%llu, new-count=%llu",
 270                 obj->ref_count, obj->ref_count + 1,
 271                 obj, obj->ref_count, obj->ref_count + 1);
 272 #endif
 273
 274         bt_object_inc_ref_count(obj);
 275 }
 276
 277 static inline
 278 void bt_object_get_no_null_check(const void *c_obj)
 279 {
 280         struct bt_object *obj = (void *) c_obj;
 281
 282         BT_ASSERT(obj);
 283         BT_ASSERT(obj->is_shared);
 284
 285         if (unlikely(obj->parent && bt_object_get_ref_count(obj) == 0)) {
 286 #ifdef BT_LOGV
 287                 BT_LOGV("Incrementing object's parent's reference count: "
 288                         "addr=%p, parent-addr=%p", obj, obj->parent);
 289 #endif
 290
 291                 bt_object_get_no_null_check(obj->parent);
 292         }
 293
 294 #ifdef BT_LOGV
 295         BT_LOGV("Incrementing object's reference count: %llu -> %llu: "
 296                 "addr=%p, cur-count=%llu, new-count=%llu",
 297                 obj->ref_count, obj->ref_count + 1,
 298                 obj, obj->ref_count, obj->ref_count + 1);
 299 #endif
 300
 301         bt_object_inc_ref_count(obj);
 302 }
 303
 304 static inline
 305 void bt_object_put_no_null_check(const void *c_obj)
 306 {
 307         struct bt_object *obj = (void *) c_obj;
 308
 309         BT_ASSERT(obj);
 310         BT_ASSERT(obj->is_shared);
 311         BT_ASSERT(obj->ref_count > 0);
 312
 313 #ifdef BT_LOGV
 314         BT_LOGV("Decrementing object's reference count: %llu -> %llu: "
 315                 "addr=%p, cur-count=%llu, new-count=%llu",
 316                 obj->ref_count, obj->ref_count - 1,
 317                 obj, obj->ref_count, obj->ref_count - 1);
 318 #endif
 319
 320         obj->ref_count--;
 321
 322         if (obj->ref_count == 0) {
 323                 BT_ASSERT(obj->release_func);
 324                 obj->release_func(obj);
 325         }
 326 }
 327
 328 #endif /* BABELTRACE_OBJECT_INTERNAL_H */