src/base/refcnt.hh

   1 /*
   2  * Copyright (c) 2017-2018 ARM Limited
   3  * All rights reserved.
   4  *
   5  * The license below extends only to copyright in the software and shall
   6  * not be construed as granting a license to any other intellectual
   7  * property including but not limited to intellectual property relating
   8  * to a hardware implementation of the functionality of the software
   9  * licensed hereunder.  You may use the software subject to the license
  10  * terms below provided that you ensure that this notice is replicated
  11  * unmodified and in its entirety in all distributions of the software,
  12  * modified or unmodified, in source code or in binary form.
  13  *
  14  * Copyright (c) 2002-2005 The Regents of The University of Michigan
  15  * All rights reserved.
  16  *
  17  * Redistribution and use in source and binary forms, with or without
  18  * modification, are permitted provided that the following conditions are
  19  * met: redistributions of source code must retain the above copyright
  20  * notice, this list of conditions and the following disclaimer;
  21  * redistributions in binary form must reproduce the above copyright
  22  * notice, this list of conditions and the following disclaimer in the
  23  * documentation and/or other materials provided with the distribution;
  24  * neither the name of the copyright holders nor the names of its
  25  * contributors may be used to endorse or promote products derived from
  26  * this software without specific prior written permission.
  27  *
  28  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  29  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  30  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  31  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  32  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  33  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  34  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  35  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  36  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  37  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  38  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  39  */
  40
  41 #ifndef __BASE_REFCNT_HH__
  42 #define __BASE_REFCNT_HH__
  43
  44 #include <type_traits>
  45
  46 /**
  47  * @file base/refcnt.hh
  48  *
  49  * Classes for managing reference counted objects.
  50  */
  51
  52 /**
  53  * Derive from RefCounted if you want to enable reference counting of
  54  * this class.  If you want to use automatic reference counting, you
  55  * should use RefCountingPtr<T> instead of regular pointers.
  56  */
  57 class RefCounted
  58 {
  59   private:
  60     // The reference count is mutable because one may want to
  61     // reference count a const pointer.  This really is OK because
  62     // const is about logical constness of the object not really about
  63     // strictly disallowing an object to change.
  64     mutable int count;
  65
  66   private:
  67     // Don't allow a default copy constructor or copy operator on
  68     // these objects because the default operation will copy the
  69     // reference count as well and we certainly don't want that.
  70     RefCounted(const RefCounted &);
  71     RefCounted &operator=(const RefCounted &);
  72
  73   public:
  74     /**
  75      * We initialize the reference count to zero and the first object
  76      * to take ownership of it must increment it to one.
  77      *
  78      * @attention A memory leak will occur if you never assign a newly
  79      * constructed object to a reference counting pointer.
  80      */
  81     RefCounted() : count(0) {}
  82
  83     /**
  84      * We make the destructor virtual because we're likely to have
  85      * virtual functions on reference counted objects.
  86      *
  87      * @todo Even if this were true, does it matter?  Shouldn't the
  88      * derived class indicate this?  This only matters if we would
  89      * ever choose to delete a "RefCounted *" which I doubt we'd ever
  90      * do.  We don't ever delete a "void *".
  91      */
  92     virtual ~RefCounted() {}
  93
  94     /// Increment the reference count
  95     void incref() const { ++count; }
  96
  97     /// Decrement the reference count and destroy the object if all
  98     /// references are gone.
  99     void decref() const { if (--count <= 0) delete this; }
 100 };
 101
 102 /**
 103  * If you want a reference counting pointer to a mutable object,
 104  * create it like this:
 105  * @code
 106  * typedef RefCountingPtr<Foo> FooPtr;
 107  * @endcode
 108  *
 109  * @attention Do not use "const FooPtr"
 110  * To create a reference counting pointer to a const object, use this:
 111  * @code
 112  * typedef RefCountingPtr<const Foo> ConstFooPtr;
 113  * @endcode
 114  *
 115  * These two usages are analogous to iterator and const_iterator in the stl.
 116  */
 117 template <class T>
 118 class RefCountingPtr
 119 {
 120   public:
 121     using PtrType = T*;
 122
 123   protected:
 124     /** Convenience aliases for const/non-const versions of T w/ friendship. */
 125     /** @{ */
 126     static constexpr auto TisConst = std::is_const<T>::value;
 127     using ConstT = typename std::conditional<TisConst,
 128             RefCountingPtr<T>,
 129             RefCountingPtr<typename std::add_const<T>::type>>::type;
 130     friend ConstT;
 131     using NonConstT = typename std::conditional<TisConst,
 132             RefCountingPtr<typename std::remove_const<T>::type>,
 133             RefCountingPtr<T>>::type;
 134     friend NonConstT;
 135     /** @} */
 136     /// The stored pointer.
 137     /// Arguably this should be private.
 138     T *data;
 139
 140     /**
 141      * Copy a new pointer value and increment the reference count if
 142      * it is a valid pointer.  Note, this does not delete the
 143      * reference any existing object.
 144      * @param d Pointer to store.
 145      */
 146     void
 147     copy(T *d)
 148     {
 149         data = d;
 150         if (data)
 151             data->incref();
 152     }
 153
 154     /**
 155      * Delete the reference to any existing object if it is non NULL.
 156      * @attention this doesn't clear the pointer value, so a double
 157      * decref could happen if not careful.
 158      */
 159     void
 160     del()
 161     {
 162         if (data)
 163             data->decref();
 164     }
 165
 166     /**
 167      * Drop the old reference and change it to something new.
 168      */
 169     void
 170     set(T *d)
 171     {
 172         // Need to check if we're actually changing because otherwise
 173         // we could delete the last reference before adding the new
 174         // reference.
 175         if (data != d) {
 176             del();
 177             copy(d);
 178         }
 179     }
 180
 181   public:
 182     /// Create an empty reference counting pointer.
 183     RefCountingPtr() : data(0) {}
 184
 185     /// Create a new reference counting pointer to some object
 186     /// (probably something newly created).  Adds a reference.
 187     RefCountingPtr(T *data) { copy(data); }
 188
 189     /// Create a new reference counting pointer by copying another
 190     /// one.  Adds a reference.
 191     RefCountingPtr(const RefCountingPtr &r) { copy(r.data); }
 192
 193     /** Move-constructor.
 194      * Does not add a reference.
 195      */
 196     RefCountingPtr(RefCountingPtr&& r)
 197     {
 198         data = r.data;
 199         r.data = nullptr;
 200     }
 201
 202     template <bool B = TisConst>
 203     RefCountingPtr(const NonConstT &r) { copy(r.data); }
 204
 205     /// Destroy the pointer and any reference it may hold.
 206     ~RefCountingPtr() { del(); }
 207
 208     // The following pointer access functions are const because they
 209     // don't actually change the pointer, though the user could change
 210     // what is pointed to.  This is analagous to a "Foo * const".
 211
 212     /// Access a member variable.
 213     T *operator->() const { return data; }
 214
 215     /// Dereference the pointer.
 216     T &operator*() const { return *data; }
 217
 218     /// Directly access the pointer itself without taking a reference.
 219     T *get() const { return data; }
 220
 221     template <bool B = TisConst>
 222     operator RefCountingPtr<typename std::enable_if_t<!B, ConstT>>()
 223     {
 224         return RefCountingPtr<const T>(*this);
 225     }
 226
 227     /// Assign a new value to the pointer
 228     const RefCountingPtr &operator=(T *p) { set(p); return *this; }
 229
 230     /// Copy the pointer from another RefCountingPtr
 231     const RefCountingPtr &operator=(const RefCountingPtr &r)
 232     { return operator=(r.data); }
 233
 234     /// Move-assign the pointer from another RefCountingPtr
 235     const RefCountingPtr &operator=(RefCountingPtr&& r)
 236     {
 237         /* This happens regardless of whether the pointer is the same or not,
 238          * because of the move semantics, the rvalue needs to be 'destroyed'.
 239          */
 240         del();
 241         data = r.data;
 242         r.data = nullptr;
 243         return *this;
 244     }
 245
 246     /// Check if the pointer is empty
 247     bool operator!() const { return data == 0; }
 248
 249     /// Check if the pointer is non-empty
 250     operator bool() const { return data != 0; }
 251 };
 252
 253 /// Check for equality of two reference counting pointers.
 254 template<class T>
 255 inline bool operator==(const RefCountingPtr<T> &l, const RefCountingPtr<T> &r)
 256 { return l.get() == r.get(); }
 257
 258 /// Check for equality of of a reference counting pointers and a
 259 /// regular pointer
 260 template<class T>
 261 inline bool operator==(const RefCountingPtr<T> &l, const T *r)
 262 { return l.get() == r; }
 263
 264 /// Check for equality of of a reference counting pointers and a
 265 /// regular pointer
 266 template<class T>
 267 inline bool operator==(const T *l, const RefCountingPtr<T> &r)
 268 { return l == r.get(); }
 269
 270 /// Check for inequality of two reference counting pointers.
 271 template<class T>
 272 inline bool operator!=(const RefCountingPtr<T> &l, const RefCountingPtr<T> &r)
 273 { return l.get() != r.get(); }
 274
 275 /// Check for inequality of of a reference counting pointers and a
 276 /// regular pointer
 277 template<class T>
 278 inline bool operator!=(const RefCountingPtr<T> &l, const T *r)
 279 { return l.get() != r; }
 280
 281 /// Check for inequality of of a reference counting pointers and a
 282 /// regular pointer
 283 template<class T>
 284 inline bool operator!=(const T *l, const RefCountingPtr<T> &r)
 285 { return l != r.get(); }
 286
 287 #endif // __BASE_REFCNT_HH__