mfbt/Util.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 /*
   7  * Miscellaneous uncategorized functionality.  Please add new functionality to
   8  * new headers, or to other appropriate existing headers, not here.
   9  */
  10
  11 #ifndef mozilla_Util_h_
  12 #define mozilla_Util_h_
  13
  14 #include "mozilla/Assertions.h"
  15 #include "mozilla/Attributes.h"
  16 #include "mozilla/Types.h"
  17
  18 #ifdef __cplusplus
  19
  20 namespace mozilla {
  21
  22 /**
  23  * DebugOnly contains a value of type T, but only in debug builds.  In release
  24  * builds, it does not contain a value.  This helper is intended to be used with
  25  * MOZ_ASSERT()-style macros, allowing one to write:
  26  *
  27  *   DebugOnly<bool> check = func();
  28  *   MOZ_ASSERT(check);
  29  *
  30  * more concisely than declaring |check| conditional on #ifdef DEBUG, but also
  31  * without allocating storage space for |check| in release builds.
  32  *
  33  * DebugOnly instances can only be coerced to T in debug builds.  In release
  34  * builds they don't have a value, so type coercion is not well defined.
  35  */
  36 template<typename T>
  37 struct DebugOnly
  38 {
  39 #ifdef DEBUG
  40     T value;
  41
  42     DebugOnly() { }
  43     DebugOnly(const T& other) : value(other) { }
  44     DebugOnly(const DebugOnly& other) : value(other.value) { }
  45     DebugOnly& operator=(const T& rhs) {
  46       value = rhs;
  47       return *this;
  48     }
  49     void operator++(int) {
  50       value++;
  51     }
  52     void operator--(int) {
  53       value--;
  54     }
  55
  56     T *operator&() { return &value; }
  57
  58     operator T&() { return value; }
  59     operator const T&() const { return value; }
  60
  61     T& operator->() { return value; }
  62
  63 #else
  64     DebugOnly() { }
  65     DebugOnly(const T&) { }
  66     DebugOnly(const DebugOnly&) { }
  67     DebugOnly& operator=(const T&) { return *this; }
  68     void operator++(int) { }
  69     void operator--(int) { }
  70 #endif
  71
  72     /*
  73      * DebugOnly must always have a destructor or else it will
  74      * generate "unused variable" warnings, exactly what it's intended
  75      * to avoid!
  76      */
  77     ~DebugOnly() {}
  78 };
  79
  80 /*
  81  * This class, and the corresponding macro MOZ_ALIGNOF, figure out how many
  82  * bytes of alignment a given type needs.
  83  */
  84 template<class T>
  85 class AlignmentFinder
  86 {
  87     struct Aligner
  88     {
  89         char c;
  90         T t;
  91     };
  92
  93   public:
  94     static const size_t alignment = sizeof(Aligner) - sizeof(T);
  95 };
  96
  97 #define MOZ_ALIGNOF(T) mozilla::AlignmentFinder<T>::alignment
  98
  99 /*
 100  * Declare the MOZ_ALIGNED_DECL macro for declaring aligned types.
 101  *
 102  * For instance,
 103  *
 104  *   MOZ_ALIGNED_DECL(char arr[2], 8);
 105  *
 106  * will declare a two-character array |arr| aligned to 8 bytes.
 107  */
 108
 109 #if defined(__GNUC__)
 110 #  define MOZ_ALIGNED_DECL(_type, _align) \
 111      _type __attribute__((aligned(_align)))
 112 #elif defined(_MSC_VER)
 113 #  define MOZ_ALIGNED_DECL(_type, _align) \
 114      __declspec(align(_align)) _type
 115 #else
 116 #  warning "We don't know how to align variables on this compiler."
 117 #  define MOZ_ALIGNED_DECL(_type, _align) _type
 118 #endif
 119
 120 /*
 121  * AlignedElem<N> is a structure whose alignment is guaranteed to be at least N
 122  * bytes.
 123  *
 124  * We support 1, 2, 4, 8, and 16-bit alignment.
 125  */
 126 template<size_t align>
 127 struct AlignedElem;
 128
 129 /*
 130  * We have to specialize this template because GCC doesn't like __attribute__((aligned(foo))) where
 131  * foo is a template parameter.
 132  */
 133
 134 template<>
 135 struct AlignedElem<1>
 136 {
 137     MOZ_ALIGNED_DECL(uint8_t elem, 1);
 138 };
 139
 140 template<>
 141 struct AlignedElem<2>
 142 {
 143     MOZ_ALIGNED_DECL(uint8_t elem, 2);
 144 };
 145
 146 template<>
 147 struct AlignedElem<4>
 148 {
 149     MOZ_ALIGNED_DECL(uint8_t elem, 4);
 150 };
 151
 152 template<>
 153 struct AlignedElem<8>
 154 {
 155     MOZ_ALIGNED_DECL(uint8_t elem, 8);
 156 };
 157
 158 template<>
 159 struct AlignedElem<16>
 160 {
 161     MOZ_ALIGNED_DECL(uint8_t elem, 16);
 162 };
 163
 164 /*
 165  * This utility pales in comparison to Boost's aligned_storage. The utility
 166  * simply assumes that uint64_t is enough alignment for anyone. This may need
 167  * to be extended one day...
 168  *
 169  * As an important side effect, pulling the storage into this template is
 170  * enough obfuscation to confuse gcc's strict-aliasing analysis into not giving
 171  * false negatives when we cast from the char buffer to whatever type we've
 172  * constructed using the bytes.
 173  */
 174 template<size_t nbytes>
 175 struct AlignedStorage
 176 {
 177     union U {
 178       char bytes[nbytes];
 179       uint64_t _;
 180     } u;
 181
 182     const void* addr() const { return u.bytes; }
 183     void* addr() { return u.bytes; }
 184 };
 185
 186 template<class T>
 187 struct AlignedStorage2
 188 {
 189     union U {
 190       char bytes[sizeof(T)];
 191       uint64_t _;
 192     } u;
 193
 194     const T* addr() const { return reinterpret_cast<const T*>(u.bytes); }
 195     T* addr() { return static_cast<T*>(static_cast<void*>(u.bytes)); }
 196 };
 197
 198 /*
 199  * Small utility for lazily constructing objects without using dynamic storage.
 200  * When a Maybe<T> is constructed, it is |empty()|, i.e., no value of T has
 201  * been constructed and no T destructor will be called when the Maybe<T> is
 202  * destroyed. Upon calling |construct|, a T object will be constructed with the
 203  * given arguments and that object will be destroyed when the owning Maybe<T>
 204  * is destroyed.
 205  *
 206  * N.B. GCC seems to miss some optimizations with Maybe and may generate extra
 207  * branches/loads/stores. Use with caution on hot paths.
 208  */
 209 template<class T>
 210 class Maybe
 211 {
 212     AlignedStorage2<T> storage;
 213     bool constructed;
 214
 215     T& asT() { return *storage.addr(); }
 216
 217   public:
 218     Maybe() { constructed = false; }
 219     ~Maybe() { if (constructed) asT().~T(); }
 220
 221     bool empty() const { return !constructed; }
 222
 223     void construct() {
 224       MOZ_ASSERT(!constructed);
 225       new (storage.addr()) T();
 226       constructed = true;
 227     }
 228
 229     template<class T1>
 230     void construct(const T1& t1) {
 231       MOZ_ASSERT(!constructed);
 232       new (storage.addr()) T(t1);
 233       constructed = true;
 234     }
 235
 236     template<class T1, class T2>
 237     void construct(const T1& t1, const T2& t2) {
 238       MOZ_ASSERT(!constructed);
 239       new (storage.addr()) T(t1, t2);
 240       constructed = true;
 241     }
 242
 243     template<class T1, class T2, class T3>
 244     void construct(const T1& t1, const T2& t2, const T3& t3) {
 245       MOZ_ASSERT(!constructed);
 246       new (storage.addr()) T(t1, t2, t3);
 247       constructed = true;
 248     }
 249
 250     template<class T1, class T2, class T3, class T4>
 251     void construct(const T1& t1, const T2& t2, const T3& t3, const T4& t4) {
 252       MOZ_ASSERT(!constructed);
 253       new (storage.addr()) T(t1, t2, t3, t4);
 254       constructed = true;
 255     }
 256
 257     T* addr() {
 258       MOZ_ASSERT(constructed);
 259       return &asT();
 260     }
 261
 262     T& ref() {
 263       MOZ_ASSERT(constructed);
 264       return asT();
 265     }
 266
 267     const T& ref() const {
 268       MOZ_ASSERT(constructed);
 269       return const_cast<Maybe*>(this)->asT();
 270     }
 271
 272     void destroy() {
 273       ref().~T();
 274       constructed = false;
 275     }
 276
 277     void destroyIfConstructed() {
 278       if (!empty())
 279         destroy();
 280     }
 281
 282   private:
 283     Maybe(const Maybe& other) MOZ_DELETE;
 284     const Maybe& operator=(const Maybe& other) MOZ_DELETE;
 285 };
 286
 287 /*
 288  * Safely subtract two pointers when it is known that end >= begin.  This avoids
 289  * the common compiler bug that if (size_t(end) - size_t(begin)) has the MSB
 290  * set, the unsigned subtraction followed by right shift will produce -1, or
 291  * size_t(-1), instead of the real difference.
 292  */
 293 template<class T>
 294 MOZ_ALWAYS_INLINE size_t
 295 PointerRangeSize(T* begin, T* end)
 296 {
 297   MOZ_ASSERT(end >= begin);
 298   return (size_t(end) - size_t(begin)) / sizeof(T);
 299 }
 300
 301 /*
 302  * Compute the length of an array with constant length.  (Use of this method
 303  * with a non-array pointer will not compile.)
 304  *
 305  * Beware of the implicit trailing '\0' when using this with string constants.
 306  */
 307 template<typename T, size_t N>
 308 size_t
 309 ArrayLength(T (&arr)[N])
 310 {
 311   return N;
 312 }
 313
 314 /*
 315  * Compute the address one past the last element of a constant-length array.
 316  *
 317  * Beware of the implicit trailing '\0' when using this with string constants.
 318  */
 319 template<typename T, size_t N>
 320 T*
 321 ArrayEnd(T (&arr)[N])
 322 {
 323   return arr + ArrayLength(arr);
 324 }
 325
 326 } /* namespace mozilla */
 327
 328 #endif /* __cplusplus */
 329
 330 #endif  /* mozilla_Util_h_ */