mfbt/Util.h

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