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

   1 /*
   2  * Copyright 2019-2020 (c) Philippe Proulx <pproulx@efficios.com>
   3  *
   4  * SPDX-License-Identifier: MIT
   5  */
   6
   7 #ifndef BABELTRACE_CPP_COMMON_BT2_BORROWED_OBJECT_HPP
   8 #define BABELTRACE_CPP_COMMON_BT2_BORROWED_OBJECT_HPP
   9
  10 #include <functional>
  11 #include <type_traits>
  12
  13 #include "common/assert.h"
  14
  15 namespace bt2 {
  16
  17 /*
  18  * An instance of this class wraps a pointer to a libbabeltrace2 object
  19  * of type `LibObjT` without managing any reference counting.
  20  *
  21  * This is an abstract base class for any libbabeltrace2 object wrapper.
  22  *
  23  * `LibObjT` is the direct libbabeltrace2 object type, for example
  24  * `bt_stream_class` or `const bt_value`.
  25  *
  26  * The user of a borrowed object, including methods of a derived class,
  27  * can call libObjPtr() to access the libbabeltrace2 object pointer.
  28  */
  29 template <typename LibObjT>
  30 class BorrowedObject
  31 {
  32     static_assert(!std::is_pointer<LibObjT>::value, "`LibObjT` must not be a pointer");
  33
  34     /*
  35      * This makes it possible for a `BorrowedObject<const bt_something>`
  36      * instance to get assigned an instance of
  37      * `BorrowedObject<bt_something>` ("copy" constructor and
  38      * "assignment" operator).
  39      *
  40      * C++ forbids the other way around.
  41      */
  42     template <typename>
  43     friend class BorrowedObject;
  44
  45 private:
  46     /*
  47      * Provides `val` which indicates whether or not you can assign this
  48      * object from a borrowed object of type `OtherLibObjT`.
  49      */
  50     template <typename OtherLibObjT>
  51     struct _AssignableFromConst final
  52     {
  53         /*
  54          * If `LibObjT` is const (for example, `const bt_value`), then
  55          * you may always assign from its non-const equivalent (for
  56          * example, `bt_value`). In C (correct):
  57          *
  58          *     bt_value * const meow = bt_value_bool_create_init(BT_TRUE);
  59          *     const bt_value * const mix = meow;
  60          *
  61          * If `LibObjT` is non-const, then you may not assign from its
  62          * const equivalent. In C (not correct):
  63          *
  64          *     const bt_value * const meow =
  65          *         bt_value_array_borrow_element_by_index_const(some_val, 17);
  66          *     bt_value * const mix = meow;
  67          */
  68         static constexpr bool val =
  69             std::is_const<LibObjT>::value || !std::is_const<OtherLibObjT>::value;
  70     };
  71
  72 protected:
  73     /* libbabeltrace2 object pointer */
  74     using _LibObjPtr = LibObjT *;
  75
  76     /* This complete borrowed object */
  77     using _ThisBorrowedObject = BorrowedObject<LibObjT>;
  78
  79     /*
  80      * Builds a borrowed object to wrap the libbabeltrace2 object
  81      * pointer `libObjPtr`.
  82      *
  83      * `libObjPtr` must not be `nullptr`.
  84      */
  85     explicit BorrowedObject(const _LibObjPtr libObjPtr) noexcept : _mLibObjPtr {libObjPtr}
  86     {
  87         BT_ASSERT_DBG(libObjPtr);
  88     }
  89
  90     /* Default copy operations */
  91     BorrowedObject(const BorrowedObject&) noexcept = default;
  92     BorrowedObject& operator=(const BorrowedObject&) noexcept = default;
  93
  94     /*
  95      * Generic "copy" constructor.
  96      *
  97      * This converting constructor accepts both an instance of
  98      * `_ThisBorrowedObject` and an instance (`other`) of
  99      * `BorrowedObject<ConstLibObjT>`, where `ConstLibObjT` is the
 100      * `const` version of `LibObjT`, if applicable.
 101      *
 102      * This makes it possible for a `BorrowedObject<const bt_something>`
 103      * instance to be built from an instance of
 104      * `BorrowedObject<bt_something>`. C++ forbids the other way around.
 105      */
 106     template <typename OtherLibObjT>
 107     BorrowedObject(const BorrowedObject<OtherLibObjT>& other) noexcept :
 108         BorrowedObject {other._mLibObjPtr}
 109     {
 110         static_assert(_AssignableFromConst<OtherLibObjT>::val,
 111                       "Don't assign a non-const wrapper from a const wrapper.");
 112     }
 113
 114     /*
 115      * Generic "assignment" operator.
 116      *
 117      * This operator accepts both an instance of
 118      * `_ThisBorrowedObject` and an instance (`other`) of
 119      * `BorrowedObject<ConstLibObjT>`, where `ConstLibObjT` is the
 120      * `const` version of `LibObjT`, if applicable.
 121      *
 122      * This makes it possible for a `BorrowedObject<const bt_something>`
 123      * instance to get assigned an instance of
 124      * `BorrowedObject<bt_something>`. C++ forbids the other way around,
 125      * therefore we use `_EnableIfAssignableT` to show a more relevant
 126      * context in the compiler error message.
 127      */
 128     template <typename OtherLibObjT>
 129     _ThisBorrowedObject& operator=(const BorrowedObject<OtherLibObjT>& other) noexcept
 130     {
 131         static_assert(_AssignableFromConst<OtherLibObjT>::val,
 132                       "Don't assign a non-const wrapper from a const wrapper.");
 133
 134         _mLibObjPtr = other._mLibObjPtr;
 135         return *this;
 136     }
 137
 138 public:
 139     /*
 140      * Returns a hash of this object, solely based on its raw
 141      * libbabeltrace2 pointer.
 142      */
 143     std::size_t hash() const noexcept
 144     {
 145         return std::hash<_LibObjPtr> {}(_mLibObjPtr);
 146     }
 147
 148     /*
 149      * Returns whether or not this object is the exact same as `other`,
 150      * solely based on the raw libbabeltrace2 pointers.
 151      */
 152     bool isSame(const _ThisBorrowedObject& other) const noexcept
 153     {
 154         return _mLibObjPtr == other._mLibObjPtr;
 155     }
 156
 157     /* Wrapped libbabeltrace2 object pointer */
 158     _LibObjPtr libObjPtr() const noexcept
 159     {
 160         return _mLibObjPtr;
 161     }
 162
 163 private:
 164     _LibObjPtr _mLibObjPtr;
 165 };
 166
 167 } /* namespace bt2 */
 168
 169 #endif /* BABELTRACE_CPP_COMMON_BT2_BORROWED_OBJECT_HPP */