src/cpp-common/bt2/shared-obj.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_OBJ_HPP
   8 #define BABELTRACE_CPP_COMMON_BT2_SHARED_OBJ_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 SharedObj final
  35 {
  36     /*
  37      * This makes it possible for a
  38      * `SharedObj<Something, bt_something, ...>` instance to get
  39      * assigned an instance of
  40      * `SharedObj<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 SharedObj;
  46
  47 private:
  48     /*
  49      * Builds a shared object from `obj` without getting a reference.
  50      */
  51     explicit SharedObj(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     SharedObj(const SharedObj<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     SharedObj(SharedObj<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 SharedObj createWithoutRef(const ObjT& obj) noexcept
  90     {
  91         return SharedObj {obj};
  92     }
  93
  94     /*
  95      * Builds a shared object from `libObjPtr` without getting a
  96      * reference.
  97      */
  98     static SharedObj createWithoutRef(LibObjT * const libObjPtr) noexcept
  99     {
 100         return SharedObj::createWithoutRef(ObjT {libObjPtr});
 101     }
 102
 103     /*
 104      * Builds a shared object from `obj`, immediately getting a new
 105      * reference.
 106      */
 107     static SharedObj createWithRef(const ObjT& obj) noexcept
 108     {
 109         SharedObj sharedObj {obj};
 110
 111         sharedObj._getRef();
 112         return sharedObj;
 113     }
 114
 115     /*
 116      * Builds a shared object from `libObjPtr`, immediately getting a new
 117      * reference.
 118      */
 119     static SharedObj createWithRef(LibObjT * const libObjPtr) noexcept
 120     {
 121         return SharedObj::createWithRef(ObjT {libObjPtr});
 122     }
 123
 124     /*
 125      * Copy constructor.
 126      */
 127     SharedObj(const SharedObj& other) noexcept : SharedObj {other, 0}
 128     {
 129     }
 130
 131     /*
 132      * Move constructor.
 133      */
 134     SharedObj(SharedObj&& other) noexcept : SharedObj {std::move(other), 0}
 135     {
 136     }
 137
 138     /*
 139      * Copy assignment operator.
 140      */
 141     SharedObj& operator=(const SharedObj& 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     SharedObj& operator=(SharedObj&& 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 SharedObj` comment above.
 160      */
 161     template <typename OtherObjT, typename OtherLibObjT>
 162     SharedObj(const SharedObj<OtherObjT, OtherLibObjT, RefFuncsT>& other) noexcept :
 163         SharedObj {other, 0}
 164     {
 165     }
 166
 167     /*
 168      * Generic "move" constructor.
 169      *
 170      * See the `friend class SharedObj` comment above.
 171      */
 172     template <typename OtherObjT, typename OtherLibObjT>
 173     SharedObj(SharedObj<OtherObjT, OtherLibObjT, RefFuncsT>&& other) noexcept :
 174         SharedObj {std::move(other), 0}
 175     {
 176     }
 177
 178     /*
 179      * Generic "copy" assignment operator.
 180      *
 181      * See the `friend class SharedObj` comment above.
 182      */
 183     template <typename OtherObjT, typename OtherLibObjT>
 184     SharedObj& operator=(const SharedObj<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 SharedObj` comment above.
 200      */
 201     template <typename OtherObjT, typename OtherLibObjT>
 202     SharedObj& operator=(SharedObj<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     ~SharedObj()
 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 active
 248      * owner.
 249      *
 250      * This method makes this object invalid.
 251      */
 252     ObjT release() noexcept
 253     {
 254         BT_ASSERT_DBG(_mObj);
 255         const auto obj = *_mObj;
 256         this->_reset();
 257         return obj;
 258     }
 259
 260 private:
 261     /*
 262      * Resets this shared object.
 263      *
 264      * To be used when moving it.
 265      */
 266     void _reset() noexcept
 267     {
 268         _mObj.reset();
 269     }
 270
 271     /*
 272      * Gets a new reference using the configured libbabeltrace2
 273      * reference incrementation function.
 274      */
 275     void _getRef() const noexcept
 276     {
 277         if (_mObj) {
 278             RefFuncsT::get(_mObj->libObjPtr());
 279         }
 280     }
 281
 282     /*
 283      * Puts a reference using the configured libbabeltrace2 reference
 284      * decrementation function.
 285      */
 286     void _putRef() const noexcept
 287     {
 288         if (_mObj) {
 289             RefFuncsT::put(_mObj->libObjPtr());
 290         }
 291     }
 292
 293     nonstd::optional<ObjT> _mObj;
 294 };
 295
 296 } /* namespace bt2 */
 297
 298 #endif /* BABELTRACE_CPP_COMMON_BT2_SHARED_OBJ_HPP */