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     /* This complete borrowed object */
  74     using _ThisBorrowedObject = BorrowedObject<LibObjT>;
  75
  76 public:
  77     /* libbabeltrace2 object */
  78     using LibObj = LibObjT;
  79
  80     /* libbabeltrace2 object pointer */
  81     using LibObjPtr = LibObjT *;
  82
  83 protected:
  84     /*
  85      * Builds a borrowed object to wrap the libbabeltrace2 object
  86      * pointer `libObjPtr`.
  87      *
  88      * `libObjPtr` must not be `nullptr`.
  89      */
  90     explicit BorrowedObject(const LibObjPtr libObjPtr) noexcept : _mLibObjPtr {libObjPtr}
  91     {
  92         BT_ASSERT_DBG(libObjPtr);
  93     }
  94
  95     /*
  96      * Generic "copy" constructor.
  97      *
  98      * This converting constructor accepts both an instance of
  99      * `_ThisBorrowedObject` and an instance (`other`) of
 100      * `BorrowedObject<ConstLibObjT>`, where `ConstLibObjT` is the
 101      * `const` version of `LibObjT`, if applicable.
 102      *
 103      * This makes it possible for a `BorrowedObject<const bt_something>`
 104      * instance to be built from an instance of
 105      * `BorrowedObject<bt_something>`. C++ forbids the other way around.
 106      */
 107     template <typename OtherLibObjT>
 108     BorrowedObject(const BorrowedObject<OtherLibObjT>& other) noexcept :
 109         BorrowedObject {other._mLibObjPtr}
 110     {
 111         static_assert(_AssignableFromConst<OtherLibObjT>::val,
 112                       "Don't assign a non-const wrapper from a const wrapper.");
 113     }
 114
 115     /*
 116      * Generic "assignment" operator.
 117      *
 118      * This operator accepts both an instance of
 119      * `_ThisBorrowedObject` and an instance (`other`) of
 120      * `BorrowedObject<ConstLibObjT>`, where `ConstLibObjT` is the
 121      * `const` version of `LibObjT`, if applicable.
 122      *
 123      * This makes it possible for a `BorrowedObject<const bt_something>`
 124      * instance to get assigned an instance of
 125      * `BorrowedObject<bt_something>`. C++ forbids the other way around,
 126      * therefore we use `_EnableIfAssignableT` to show a more relevant
 127      * context in the compiler error message.
 128      */
 129     template <typename OtherLibObjT>
 130     _ThisBorrowedObject operator=(const BorrowedObject<OtherLibObjT>& other) noexcept
 131     {
 132         static_assert(_AssignableFromConst<OtherLibObjT>::val,
 133                       "Don't assign a non-const wrapper from a const wrapper.");
 134
 135         _mLibObjPtr = other._mLibObjPtr;
 136         return *this;
 137     }
 138
 139 public:
 140     /*
 141      * Returns a hash of this object, solely based on its raw
 142      * libbabeltrace2 pointer.
 143      */
 144     std::size_t hash() const noexcept
 145     {
 146         return std::hash<LibObjPtr> {}(_mLibObjPtr);
 147     }
 148
 149     /*
 150      * Returns whether or not this object is the exact same as `other`,
 151      * solely based on the raw libbabeltrace2 pointers.
 152      */
 153     bool isSame(const _ThisBorrowedObject& other) const noexcept
 154     {
 155         return _mLibObjPtr == other._mLibObjPtr;
 156     }
 157
 158     /* Wrapped libbabeltrace2 object pointer */
 159     LibObjPtr libObjPtr() const noexcept
 160     {
 161         return _mLibObjPtr;
 162     }
 163
 164 private:
 165     LibObjPtr _mLibObjPtr;
 166 };
 167
 168 } /* namespace bt2 */
 169
 170 #endif /* BABELTRACE_CPP_COMMON_BT2_BORROWED_OBJECT_HPP */