mfbt/RangedPtr.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 /*
   8  * Implements a smart pointer asserted to remain within a range specified at
   9  * construction.
  10  */
  11
  12 #ifndef mozilla_RangedPtr_h
  13 #define mozilla_RangedPtr_h
  14
  15 #include "mozilla/ArrayUtils.h"
  16 #include "mozilla/Assertions.h"
  17 #include "mozilla/Attributes.h"
  18
  19 #include <stdint.h>
  20
  21 namespace mozilla {
  22
  23 /*
  24  * RangedPtr is a smart pointer restricted to an address range specified at
  25  * creation.  The pointer (and any smart pointers derived from it) must remain
  26  * within the range [start, end] (inclusive of end to facilitate use as
  27  * sentinels).  Dereferencing or indexing into the pointer (or pointers derived
  28  * from it) must remain within the range [start, end).  All the standard pointer
  29  * operators are defined on it; in debug builds these operations assert that the
  30  * range specified at construction is respected.
  31  *
  32  * In theory passing a smart pointer instance as an argument can be slightly
  33  * slower than passing a T* (due to ABI requirements for passing structs versus
  34  * passing pointers), if the method being called isn't inlined.  If you are in
  35  * extremely performance-critical code, you may want to be careful using this
  36  * smart pointer as an argument type.
  37  *
  38  * RangedPtr<T> intentionally does not implicitly convert to T*.  Use get() to
  39  * explicitly convert to T*.  Keep in mind that the raw pointer of course won't
  40  * implement bounds checking in debug builds.
  41  */
  42 template<typename T>
  43 class RangedPtr
  44 {
  45   T* mPtr;
  46
  47 #ifdef DEBUG
  48   T* const mRangeStart;
  49   T* const mRangeEnd;
  50 #endif
  51
  52   typedef void (RangedPtr::* ConvertibleToBool)();
  53   void nonNull() {}
  54
  55   void checkSanity()
  56   {
  57     MOZ_ASSERT(mRangeStart <= mPtr);
  58     MOZ_ASSERT(mPtr <= mRangeEnd);
  59   }
  60
  61   /* Creates a new pointer for |aPtr|, restricted to this pointer's range. */
  62   RangedPtr<T> create(T* aPtr) const
  63   {
  64 #ifdef DEBUG
  65     return RangedPtr<T>(aPtr, mRangeStart, mRangeEnd);
  66 #else
  67     return RangedPtr<T>(aPtr, nullptr, size_t(0));
  68 #endif
  69   }
  70
  71   uintptr_t asUintptr() const { return reinterpret_cast<uintptr_t>(mPtr); }
  72
  73 public:
  74   RangedPtr(T* aPtr, T* aStart, T* aEnd)
  75     : mPtr(aPtr)
  76 #ifdef DEBUG
  77     , mRangeStart(aStart), mRangeEnd(aEnd)
  78 #endif
  79   {
  80     MOZ_ASSERT(mRangeStart <= mRangeEnd);
  81     checkSanity();
  82   }
  83   RangedPtr(T* aPtr, T* aStart, size_t aLength)
  84     : mPtr(aPtr)
  85 #ifdef DEBUG
  86     , mRangeStart(aStart), mRangeEnd(aStart + aLength)
  87 #endif
  88   {
  89     MOZ_ASSERT(aLength <= size_t(-1) / sizeof(T));
  90     MOZ_ASSERT(reinterpret_cast<uintptr_t>(mRangeStart) + aLength * sizeof(T) >=
  91                reinterpret_cast<uintptr_t>(mRangeStart));
  92     checkSanity();
  93   }
  94
  95   /* Equivalent to RangedPtr(aPtr, aPtr, aLength). */
  96   RangedPtr(T* aPtr, size_t aLength)
  97     : mPtr(aPtr)
  98 #ifdef DEBUG
  99     , mRangeStart(aPtr), mRangeEnd(aPtr + aLength)
 100 #endif
 101   {
 102     MOZ_ASSERT(aLength <= size_t(-1) / sizeof(T));
 103     MOZ_ASSERT(reinterpret_cast<uintptr_t>(mRangeStart) + aLength * sizeof(T) >=
 104                reinterpret_cast<uintptr_t>(mRangeStart));
 105     checkSanity();
 106   }
 107
 108   /* Equivalent to RangedPtr(aArr, aArr, N). */
 109   template<size_t N>
 110   RangedPtr(T (&aArr)[N])
 111     : mPtr(aArr)
 112 #ifdef DEBUG
 113     , mRangeStart(aArr), mRangeEnd(aArr + N)
 114 #endif
 115   {
 116     checkSanity();
 117   }
 118
 119   T* get() const { return mPtr; }
 120
 121   operator ConvertibleToBool() const { return mPtr ? &RangedPtr::nonNull : 0; }
 122
 123   /*
 124    * You can only assign one RangedPtr into another if the two pointers have
 125    * the same valid range:
 126    *
 127    *   char arr1[] = "hi";
 128    *   char arr2[] = "bye";
 129    *   RangedPtr<char> p1(arr1, 2);
 130    *   p1 = RangedPtr<char>(arr1 + 1, arr1, arr1 + 2); // works
 131    *   p1 = RangedPtr<char>(arr2, 3);                  // asserts
 132    */
 133   RangedPtr<T>& operator=(const RangedPtr<T>& aOther)
 134   {
 135     MOZ_ASSERT(mRangeStart == aOther.mRangeStart);
 136     MOZ_ASSERT(mRangeEnd == aOther.mRangeEnd);
 137     mPtr = aOther.mPtr;
 138     checkSanity();
 139     return *this;
 140   }
 141
 142   RangedPtr<T> operator+(size_t aInc)
 143   {
 144     MOZ_ASSERT(aInc <= size_t(-1) / sizeof(T));
 145     MOZ_ASSERT(asUintptr() + aInc * sizeof(T) >= asUintptr());
 146     return create(mPtr + aInc);
 147   }
 148
 149   RangedPtr<T> operator-(size_t aDec)
 150   {
 151     MOZ_ASSERT(aDec <= size_t(-1) / sizeof(T));
 152     MOZ_ASSERT(asUintptr() - aDec * sizeof(T) <= asUintptr());
 153     return create(mPtr - aDec);
 154   }
 155
 156   /*
 157    * You can assign a raw pointer into a RangedPtr if the raw pointer is
 158    * within the range specified at creation.
 159    */
 160   template <typename U>
 161   RangedPtr<T>& operator=(U* aPtr)
 162   {
 163     *this = create(aPtr);
 164     return *this;
 165   }
 166
 167   template <typename U>
 168   RangedPtr<T>& operator=(const RangedPtr<U>& aPtr)
 169   {
 170     MOZ_ASSERT(mRangeStart <= aPtr.mPtr);
 171     MOZ_ASSERT(aPtr.mPtr <= mRangeEnd);
 172     mPtr = aPtr.mPtr;
 173     checkSanity();
 174     return *this;
 175   }
 176
 177   RangedPtr<T>& operator++()
 178   {
 179     return (*this += 1);
 180   }
 181
 182   RangedPtr<T> operator++(int)
 183   {
 184     RangedPtr<T> rcp = *this;
 185     ++*this;
 186     return rcp;
 187   }
 188
 189   RangedPtr<T>& operator--()
 190   {
 191     return (*this -= 1);
 192   }
 193
 194   RangedPtr<T> operator--(int)
 195   {
 196     RangedPtr<T> rcp = *this;
 197     --*this;
 198     return rcp;
 199   }
 200
 201   RangedPtr<T>& operator+=(size_t aInc)
 202   {
 203     *this = *this + aInc;
 204     return *this;
 205   }
 206
 207   RangedPtr<T>& operator-=(size_t aDec)
 208   {
 209     *this = *this - aDec;
 210     return *this;
 211   }
 212
 213   T& operator[](int aIndex) const
 214   {
 215     MOZ_ASSERT(size_t(aIndex > 0 ? aIndex : -aIndex) <= size_t(-1) / sizeof(T));
 216     return *create(mPtr + aIndex);
 217   }
 218
 219   T& operator*() const
 220   {
 221     MOZ_ASSERT(mPtr >= mRangeStart);
 222     MOZ_ASSERT(mPtr < mRangeEnd);
 223     return *mPtr;
 224   }
 225
 226   template <typename U>
 227   bool operator==(const RangedPtr<U>& aOther) const
 228   {
 229     return mPtr == aOther.mPtr;
 230   }
 231   template <typename U>
 232   bool operator!=(const RangedPtr<U>& aOther) const
 233   {
 234     return !(*this == aOther);
 235   }
 236
 237   template<typename U>
 238   bool operator==(const U* u) const
 239   {
 240     return mPtr == u;
 241   }
 242   template<typename U>
 243   bool operator!=(const U* u) const
 244   {
 245     return !(*this == u);
 246   }
 247
 248   template <typename U>
 249   bool operator<(const RangedPtr<U>& aOther) const
 250   {
 251     return mPtr < aOther.mPtr;
 252   }
 253   template <typename U>
 254   bool operator<=(const RangedPtr<U>& aOther) const
 255   {
 256     return mPtr <= aOther.mPtr;
 257   }
 258
 259   template <typename U>
 260   bool operator>(const RangedPtr<U>& aOther) const
 261   {
 262     return mPtr > aOther.mPtr;
 263   }
 264   template <typename U>
 265   bool operator>=(const RangedPtr<U>& aOther) const
 266   {
 267     return mPtr >= aOther.mPtr;
 268   }
 269
 270   size_t operator-(const RangedPtr<T>& aOther) const
 271   {
 272     MOZ_ASSERT(mPtr >= aOther.mPtr);
 273     return PointerRangeSize(aOther.mPtr, mPtr);
 274   }
 275
 276 private:
 277   RangedPtr() = delete;
 278   T* operator&() = delete;
 279 };
 280
 281 } /* namespace mozilla */
 282
 283 #endif /* mozilla_RangedPtr_h */