src/ctf-writer/object.h

   1 #ifndef BABELTRACE_CTF_WRITER_OBJECT_INTERNAL_H
   2 #define BABELTRACE_CTF_WRITER_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 "common/babeltrace.h"
  29 #include "common/assert.h"
  30 #include <stdbool.h>
  31
  32 struct bt_ctf_object;
  33
  34 typedef void (*bt_ctf_object_release_func)(struct bt_ctf_object *);
  35 typedef void (*bt_ctf_object_parent_is_owner_listener_func)(
  36                 struct bt_ctf_object *);
  37
  38 static inline
  39 void *bt_ctf_object_get_no_null_check(struct bt_ctf_object *obj);
  40
  41 static inline
  42 void bt_ctf_object_put_no_null_check(struct bt_ctf_object *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_ctf_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_ctf_object_with_parent_release_func(), which calls
  66          * `spec_release_func` below if there's no current parent.
  67          */
  68         bt_ctf_object_release_func release_func;
  69
  70         /*
  71          * Specific release function called by
  72          * bt_ctf_object_with_parent_release_func() or directly by a
  73          * parent object.
  74          */
  75         bt_ctf_object_release_func spec_release_func;
  76
  77         /*
  78          * Optional callback for an object with a parent, called by
  79          * bt_ctf_object_with_parent_release_func() to indicate to the
  80          * object that its parent is its owner.
  81          */
  82         bt_ctf_object_parent_is_owner_listener_func
  83                 parent_is_owner_listener_func;
  84
  85         /*
  86          * Optional parent object.
  87          */
  88         struct bt_ctf_object *parent;
  89 };
  90
  91 static inline
  92 unsigned long long bt_ctf_object_get_ref_count(struct bt_ctf_object *obj)
  93 {
  94         BT_ASSERT(obj);
  95         BT_ASSERT(obj->is_shared);
  96         return obj->ref_count;
  97 }
  98
  99 static inline
 100 struct bt_ctf_object *bt_ctf_object_borrow_parent(struct bt_ctf_object *obj)
 101 {
 102         BT_ASSERT(obj);
 103         BT_ASSERT(obj->is_shared);
 104         return obj->parent;
 105 }
 106
 107 static inline
 108 struct bt_ctf_object *bt_ctf_object_get_parent(struct bt_ctf_object *obj)
 109 {
 110         struct bt_ctf_object *parent = bt_ctf_object_borrow_parent(obj);
 111
 112         if (parent) {
 113                 bt_ctf_object_get_no_null_check(parent);
 114         }
 115
 116         return parent;
 117 }
 118
 119 static inline
 120 void bt_ctf_object_set_parent(struct bt_ctf_object *child, struct bt_ctf_object *parent)
 121 {
 122         BT_ASSERT(child);
 123         BT_ASSERT(child->is_shared);
 124
 125 #ifdef BT_LOGV
 126         BT_LOGV("Setting object's parent: addr=%p, parent-addr=%p",
 127                 child, parent);
 128 #endif
 129
 130         /*
 131          * It is assumed that a "child" having a parent is publicly
 132          * reachable. Therefore, a reference to its parent must be
 133          * taken. The reference to the parent will be released once the
 134          * object's reference count falls to zero.
 135          */
 136         if (parent) {
 137                 BT_ASSERT(!child->parent);
 138                 child->parent = parent;
 139                 bt_ctf_object_get_no_null_check(parent);
 140         } else {
 141                 if (child->parent) {
 142                         bt_ctf_object_put_no_null_check(child->parent);
 143                 }
 144
 145                 child->parent = NULL;
 146         }
 147 }
 148
 149 static inline
 150 void bt_ctf_object_try_spec_release(struct bt_ctf_object *obj)
 151 {
 152         BT_ASSERT(obj);
 153         BT_ASSERT(obj->is_shared);
 154         BT_ASSERT(obj->spec_release_func);
 155
 156         if (bt_ctf_object_get_ref_count(obj) == 0) {
 157                 obj->spec_release_func(obj);
 158         }
 159 }
 160
 161 static inline
 162 void bt_ctf_object_with_parent_release_func(struct bt_ctf_object *obj)
 163 {
 164         if (obj->parent) {
 165                 /*
 166                  * Keep our own copy of the parent address because `obj`
 167                  * could be destroyed in
 168                  * obj->parent_is_owner_listener_func().
 169                  */
 170                 struct bt_ctf_object *parent = obj->parent;
 171
 172 #ifdef BT_LOGV
 173                 BT_LOGV("Releasing parented object: addr=%p, ref-count=%llu, "
 174                         "parent-addr=%p, parent-ref-count=%llu",
 175                         obj, obj->ref_count,
 176                         parent, parent->ref_count);
 177 #endif
 178
 179                 if (obj->parent_is_owner_listener_func) {
 180                         /*
 181                          * Object has a chance to destroy itself here
 182                          * under certain conditions and notify its
 183                          * parent. At this point the parent is
 184                          * guaranteed to exist because it's not put yet.
 185                          */
 186                         obj->parent_is_owner_listener_func(obj);
 187                 }
 188
 189                 /* The release function will be invoked by the parent. */
 190                 bt_ctf_object_put_no_null_check(parent);
 191         } else {
 192                 bt_ctf_object_try_spec_release(obj);
 193         }
 194 }
 195
 196 static inline
 197 void bt_ctf_object_init(struct bt_ctf_object *obj, bool is_shared,
 198                 bt_ctf_object_release_func release_func)
 199 {
 200         BT_ASSERT(obj);
 201         BT_ASSERT(!is_shared || release_func);
 202         obj->is_shared = is_shared;
 203         obj->release_func = release_func;
 204         obj->parent_is_owner_listener_func = NULL;
 205         obj->spec_release_func = NULL;
 206         obj->parent = NULL;
 207         obj->ref_count = 1;
 208 }
 209
 210 static inline
 211 void bt_ctf_object_init_shared(struct bt_ctf_object *obj,
 212                 bt_ctf_object_release_func release_func)
 213 {
 214         bt_ctf_object_init(obj, true, release_func);
 215 }
 216
 217 static inline
 218 void bt_ctf_object_init_unique(struct bt_ctf_object *obj)
 219 {
 220         bt_ctf_object_init(obj, false, NULL);
 221 }
 222
 223 static inline
 224 void bt_ctf_object_init_shared_with_parent(struct bt_ctf_object *obj,
 225                 bt_ctf_object_release_func spec_release_func)
 226 {
 227         BT_ASSERT(obj);
 228         BT_ASSERT(spec_release_func);
 229         bt_ctf_object_init_shared(obj, bt_ctf_object_with_parent_release_func);
 230         obj->spec_release_func = spec_release_func;
 231 }
 232
 233 static inline
 234 void bt_ctf_object_set_parent_is_owner_listener_func(struct bt_ctf_object *obj,
 235                 bt_ctf_object_parent_is_owner_listener_func func)
 236 {
 237         BT_ASSERT(obj);
 238         BT_ASSERT(obj->is_shared);
 239         BT_ASSERT(obj->spec_release_func);
 240         ((struct bt_ctf_object *) obj)->parent_is_owner_listener_func = func;
 241 }
 242
 243 static inline
 244 void bt_ctf_object_inc_ref_count(struct bt_ctf_object *obj)
 245 {
 246         BT_ASSERT(obj);
 247         BT_ASSERT(obj->is_shared);
 248         obj->ref_count++;
 249         BT_ASSERT(obj->ref_count != 0);
 250 }
 251
 252 static inline
 253 void *bt_ctf_object_get_no_null_check_no_parent_check(struct bt_ctf_object *obj)
 254 {
 255         BT_ASSERT(obj);
 256         BT_ASSERT(obj->is_shared);
 257
 258 #ifdef BT_LOGV
 259         BT_LOGV("Incrementing object's reference count: %llu -> %llu: "
 260                 "addr=%p, cur-count=%llu, new-count=%llu",
 261                 obj->ref_count, obj->ref_count + 1,
 262                 obj, obj->ref_count, obj->ref_count + 1);
 263 #endif
 264
 265         bt_ctf_object_inc_ref_count(obj);
 266         return obj;
 267 }
 268
 269 static inline
 270 void *bt_ctf_object_get_no_null_check(struct bt_ctf_object *obj)
 271 {
 272         BT_ASSERT(obj);
 273         BT_ASSERT(obj->is_shared);
 274
 275         if (unlikely(obj->parent && bt_ctf_object_get_ref_count(obj) == 0)) {
 276 #ifdef BT_LOGV
 277                 BT_LOGV("Incrementing object's parent's reference count: "
 278                         "addr=%p, parent-addr=%p", obj, obj->parent);
 279 #endif
 280
 281                 bt_ctf_object_get_no_null_check(obj->parent);
 282         }
 283
 284 #ifdef BT_LOGV
 285         BT_LOGV("Incrementing object's reference count: %llu -> %llu: "
 286                 "addr=%p, cur-count=%llu, new-count=%llu",
 287                 obj->ref_count, obj->ref_count + 1,
 288                 obj, obj->ref_count, obj->ref_count + 1);
 289 #endif
 290
 291         bt_ctf_object_inc_ref_count(obj);
 292         return obj;
 293 }
 294
 295 static inline
 296 void bt_ctf_object_put_no_null_check(struct bt_ctf_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_CTF_WRITER_OBJECT_INTERNAL_H */