src/cpp-common/bt2/shared-object.hpp

   1 /*
   2  * Copyright (c) 2019-2020 Philippe Proulx <pproulx@efficios.com>
   3  *
   4  * SPDX-License-Identifier: MIT
   5  */
   6
   7 #ifndef BABELTRACE_CPP_COMMON_BT2_SHARED_OBJECT_HPP
   8 #define BABELTRACE_CPP_COMMON_BT2_SHARED_OBJECT_HPP
   9
  10 #include "common/assert.h"
  11 #include "cpp-common/optional.hpp"
  12
  13 namespace bt2 {
  14
  15 /*
  16  * An instance of this class wraps an optional instance of `ObjT` and
  17  * manages the reference counting of the underlying libbabeltrace2
  18  * object.
  19  *
  20  * When you move a shared object, it becomes invalid, in that
  21  * operator*() and operator->() will either fail to assert in debug mode
  22  * or trigger a segmentation fault.
  23  *
  24  * `LibObjT` is the direct libbabeltrace2 object type, for example
  25  * `bt_stream_class` or `const bt_value`.
  26  *
  27  * RefFuncsT::get() must accept a `const LibObjT *` value and increment
  28  * its reference count.
  29  *
  30  * RefFuncsT::put() must accept a `const LibObjT *` value and decrement
  31  * its reference count.
  32  */
  33 template <typename ObjT, typename LibObjT, typename RefFuncsT>
  34 class SharedObject final
  35 {
  36     /*
  37      * This makes it possible for a
  38      * `SharedObject<Something, bt_something, ...>` instance to get
  39      * assigned an instance of
  40      * `SharedObject<SpecificSomething, bt_something, ...>` (copy/move
  41      * constructors and assignment operators), given that
  42      * `SpecificSomething` inherits `Something`.
  43      */
  44     template <typename, typename, typename>
  45     friend class SharedObject;
  46
  47 private:
  48     /*
  49      * Builds a shared object from `obj` without getting a reference.
  50      */
  51     explicit SharedObject(const ObjT& obj) noexcept : _mObj {obj}
  52     {
  53     }
  54
  55     /*
  56      * Common generic "copy" constructor.
  57      *
  58      * This constructor is meant to be delegated to by the copy
  59      * constructor and the generic "copy" constructor.
  60      *
  61      * The second parameter, of type `int`, makes it possible to
  62      * delegate by deduction as you can't explicit the template
  63      * parameters when delegating to a constructor template.
  64      */
  65     template <typename OtherObjT, typename OtherLibObjT>
  66     SharedObject(const SharedObject<OtherObjT, OtherLibObjT, RefFuncsT>& other, int) noexcept :
  67         _mObj {other._mObj}
  68     {
  69         this->_getRef();
  70     }
  71
  72     /*
  73      * Common generic "move" constructor.
  74      *
  75      * See the comment of the common generic "copy" constructor above.
  76      */
  77     template <typename OtherObjT, typename OtherLibObjT>
  78     SharedObject(SharedObject<OtherObjT, OtherLibObjT, RefFuncsT>&& other, int) noexcept :
  79         _mObj {other._mObj}
  80     {
  81         /* Reset moved-from object */
  82         other._reset();
  83     }
  84
  85 public:
  86     /*
  87      * Builds a shared object from `obj` without getting a reference.
  88      */
  89     static SharedObject createWithoutRef(const ObjT& obj) noexcept
  90     {
  91         return SharedObject {obj};
  92     }
  93
  94     /*
  95      * Builds a shared object from `libObjPtr` without getting a
  96      * reference.
  97      */
  98     static SharedObject createWithoutRef(LibObjT * const libObjPtr) noexcept
  99     {
 100         return SharedObject::createWithoutRef(ObjT {libObjPtr});
 101     }
 102
 103     /*
 104      * Builds a shared object from `obj`, immediately getting a new
 105      * reference.
 106      */
 107     static SharedObject createWithRef(const ObjT& obj) noexcept
 108     {
 109         SharedObject sharedObj {obj};
 110
 111         sharedObj._getRef();
 112         return sharedObj;
 113     }
 114
 115     /*
 116      * Builds a shared object from `libObjPtr`, immediately getting a
 117      * new reference.
 118      */
 119     static SharedObject createWithRef(LibObjT * const libObjPtr) noexcept
 120     {
 121         return SharedObject::createWithRef(ObjT {libObjPtr});
 122     }
 123
 124     /*
 125      * Copy constructor.
 126      */
 127     SharedObject(const SharedObject& other) noexcept : SharedObject {other, 0}
 128     {
 129     }
 130
 131     /*
 132      * Move constructor.
 133      */
 134     SharedObject(SharedObject&& other) noexcept : SharedObject {std::move(other), 0}
 135     {
 136     }
 137
 138     /*
 139      * Copy assignment operator.
 140      */
 141     SharedObject& operator=(const SharedObject& other) noexcept
 142     {
 143         /* Use generic "copy" assignment operator */
 144         return this->operator=<ObjT, LibObjT>(other);
 145     }
 146
 147     /*
 148      * Move assignment operator.
 149      */
 150     SharedObject& operator=(SharedObject&& other) noexcept
 151     {
 152         /* Use generic "move" assignment operator */
 153         return this->operator=<ObjT, LibObjT>(std::move(other));
 154     }
 155
 156     /*
 157      * Generic "copy" constructor.
 158      *
 159      * See the `friend class SharedObject` comment above.
 160      */
 161     template <typename OtherObjT, typename OtherLibObjT>
 162     SharedObject(const SharedObject<OtherObjT, OtherLibObjT, RefFuncsT>& other) noexcept :
 163         SharedObject {other, 0}
 164     {
 165     }
 166
 167     /*
 168      * Generic "move" constructor.
 169      *
 170      * See the `friend class SharedObject` comment above.
 171      */
 172     template <typename OtherObjT, typename OtherLibObjT>
 173     SharedObject(SharedObject<OtherObjT, OtherLibObjT, RefFuncsT>&& other) noexcept :
 174         SharedObject {std::move(other), 0}
 175     {
 176     }
 177
 178     /*
 179      * Generic "copy" assignment operator.
 180      *
 181      * See the `friend class SharedObject` comment above.
 182      */
 183     template <typename OtherObjT, typename OtherLibObjT>
 184     SharedObject& operator=(const SharedObject<OtherObjT, OtherLibObjT, RefFuncsT>& other) noexcept
 185     {
 186         /* Put current object's reference */
 187         this->_putRef();
 188
 189         /* Set new current object and get a reference */
 190         _mObj = other._mObj;
 191         this->_getRef();
 192
 193         return *this;
 194     }
 195
 196     /*
 197      * Generic "move" assignment operator.
 198      *
 199      * See the `friend class SharedObject` comment above.
 200      */
 201     template <typename OtherObjT, typename OtherLibObjT>
 202     SharedObject& operator=(SharedObject<OtherObjT, OtherLibObjT, RefFuncsT>&& other) noexcept
 203     {
 204         /* Put current object's reference */
 205         this->_putRef();
 206
 207         /* Set new current object */
 208         _mObj = other._mObj;
 209
 210         /* Reset moved-from object */
 211         other._reset();
 212
 213         return *this;
 214     }
 215
 216     ~SharedObject()
 217     {
 218         this->_putRef();
 219     }
 220
 221     ObjT& operator*() noexcept
 222     {
 223         BT_ASSERT_DBG(_mObj);
 224         return *_mObj;
 225     }
 226
 227     const ObjT& operator*() const noexcept
 228     {
 229         BT_ASSERT_DBG(_mObj);
 230         return *_mObj;
 231     }
 232
 233     ObjT *operator->() noexcept
 234     {
 235         BT_ASSERT_DBG(_mObj);
 236         return &*_mObj;
 237     }
 238
 239     const ObjT *operator->() const noexcept
 240     {
 241         BT_ASSERT_DBG(_mObj);
 242         return &*_mObj;
 243     }
 244
 245     /*
 246      * Transfers the reference of the object which this shared object
 247      * wrapper manages and returns it, making the caller become an
 248      * active owner.
 249      *
 250      * This method makes this object invalid.
 251      */
 252     ObjT release() noexcept
 253     {
 254         BT_ASSERT_DBG(_mObj);
 255
 256         const auto obj = *_mObj;
 257
 258         this->_reset();
 259         return obj;
 260     }
 261
 262 private:
 263     /*
 264      * Resets this shared object.
 265      *
 266      * To be used when moving it.
 267      */
 268     void _reset() noexcept
 269     {
 270         _mObj.reset();
 271     }
 272
 273     /*
 274      * Gets a new reference using the configured libbabeltrace2
 275      * reference incrementation function.
 276      */
 277     void _getRef() const noexcept
 278     {
 279         if (_mObj) {
 280             RefFuncsT::get(_mObj->libObjPtr());
 281         }
 282     }
 283
 284     /*
 285      * Puts a reference using the configured libbabeltrace2 reference
 286      * decrementation function.
 287      */
 288     void _putRef() const noexcept
 289     {
 290         if (_mObj) {
 291             RefFuncsT::put(_mObj->libObjPtr());
 292         }
 293     }
 294
 295     nonstd::optional<ObjT> _mObj;
 296 };
 297
 298 } /* namespace bt2 */
 299
 300 #endif /* BABELTRACE_CPP_COMMON_BT2_SHARED_OBJECT_HPP */