src/3rdparty/v8/src/lazy-instance.h

   1 // Copyright 2012 the V8 project authors. All rights reserved.
   2 // Redistribution and use in source and binary forms, with or without
   3 // modification, are permitted provided that the following conditions are
   4 // met:
   5 //
   6 //     * Redistributions of source code must retain the above copyright
   7 //       notice, this list of conditions and the following disclaimer.
   8 //     * Redistributions in binary form must reproduce the above
   9 //       copyright notice, this list of conditions and the following
  10 //       disclaimer in the documentation and/or other materials provided
  11 //       with the distribution.
  12 //     * Neither the name of Google Inc. nor the names of its
  13 //       contributors may be used to endorse or promote products derived
  14 //       from this software without specific prior written permission.
  15 //
  16 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  17 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  18 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  19 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  20 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  21 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  22 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  23 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  24 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  25 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  26 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27
  28 // The LazyInstance<Type, Traits> class manages a single instance of Type,
  29 // which will be lazily created on the first time it's accessed.  This class is
  30 // useful for places you would normally use a function-level static, but you
  31 // need to have guaranteed thread-safety.  The Type constructor will only ever
  32 // be called once, even if two threads are racing to create the object.  Get()
  33 // and Pointer() will always return the same, completely initialized instance.
  34 //
  35 // LazyInstance is completely thread safe, assuming that you create it safely.
  36 // The class was designed to be POD initialized, so it shouldn't require a
  37 // static constructor.  It really only makes sense to declare a LazyInstance as
  38 // a global variable using the LAZY_INSTANCE_INITIALIZER initializer.
  39 //
  40 // LazyInstance is similar to Singleton, except it does not have the singleton
  41 // property.  You can have multiple LazyInstance's of the same type, and each
  42 // will manage a unique instance.  It also preallocates the space for Type, as
  43 // to avoid allocating the Type instance on the heap.  This may help with the
  44 // performance of creating the instance, and reducing heap fragmentation.  This
  45 // requires that Type be a complete type so we can determine the size. See
  46 // notes for advanced users below for more explanations.
  47 //
  48 // Example usage:
  49 //   static LazyInstance<MyClass>::type my_instance = LAZY_INSTANCE_INITIALIZER;
  50 //   void SomeMethod() {
  51 //     my_instance.Get().SomeMethod();  // MyClass::SomeMethod()
  52 //
  53 //     MyClass* ptr = my_instance.Pointer();
  54 //     ptr->DoDoDo();  // MyClass::DoDoDo
  55 //   }
  56 //
  57 // Additionally you can override the way your instance is constructed by
  58 // providing your own trait:
  59 // Example usage:
  60 //   struct MyCreateTrait {
  61 //     static void Construct(MyClass* allocated_ptr) {
  62 //       new (allocated_ptr) MyClass(/* extra parameters... */);
  63 //     }
  64 //   };
  65 //   static LazyInstance<MyClass, MyCreateTrait>::type my_instance =
  66 //      LAZY_INSTANCE_INITIALIZER;
  67 //
  68 // WARNINGS:
  69 // - This implementation of LazyInstance is NOT THREAD-SAFE by default. See
  70 //   ThreadSafeInitOnceTrait declared below for that.
  71 // - Lazy initialization comes with a cost. Make sure that you don't use it on
  72 //   critical path. Consider adding your initialization code to a function
  73 //   which is explicitly called once.
  74 //
  75 // Notes for advanced users:
  76 // LazyInstance can actually be used in two different ways:
  77 //
  78 // - "Static mode" which is the default mode since it is the most efficient
  79 //   (no extra heap allocation). In this mode, the instance is statically
  80 //   allocated (stored in the global data section at compile time).
  81 //   The macro LAZY_STATIC_INSTANCE_INITIALIZER (= LAZY_INSTANCE_INITIALIZER)
  82 //   must be used to initialize static lazy instances.
  83 //
  84 // - "Dynamic mode". In this mode, the instance is dynamically allocated and
  85 //   constructed (using new) by default. This mode is useful if you have to
  86 //   deal with some code already allocating the instance for you (e.g.
  87 //   OS::Mutex() which returns a new private OS-dependent subclass of Mutex).
  88 //   The macro LAZY_DYNAMIC_INSTANCE_INITIALIZER must be used to initialize
  89 //   dynamic lazy instances.
  90
  91 #ifndef V8_LAZY_INSTANCE_H_
  92 #define V8_LAZY_INSTANCE_H_
  93
  94 #include "once.h"
  95
  96 namespace v8 {
  97 namespace internal {
  98
  99 #define LAZY_STATIC_INSTANCE_INITIALIZER { V8_ONCE_INIT, {} }
 100 #define LAZY_DYNAMIC_INSTANCE_INITIALIZER { V8_ONCE_INIT, 0 }
 101
 102 // Default to static mode.
 103 #define LAZY_INSTANCE_INITIALIZER LAZY_STATIC_INSTANCE_INITIALIZER
 104
 105
 106 template <typename T>
 107 struct LeakyInstanceTrait {
 108   static void Destroy(T* /* instance */) {}
 109 };
 110
 111
 112 // Traits that define how an instance is allocated and accessed.
 113
 114 // TODO(kalmard): __alignof__ is only defined for GCC > 4.2. Fix alignment issue
 115 // on MIPS with other compilers.
 116 #if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ > 2))
 117 #define LAZY_ALIGN(x) __attribute__((aligned(__alignof__(x))))
 118 #else
 119 #define LAZY_ALIGN(x)
 120 #endif
 121
 122 template <typename T>
 123 struct StaticallyAllocatedInstanceTrait {
 124   typedef char StorageType[sizeof(T)] LAZY_ALIGN(T);
 125
 126   static T* MutableInstance(StorageType* storage) {
 127     return reinterpret_cast<T*>(storage);
 128   }
 129
 130   template <typename ConstructTrait>
 131   static void InitStorageUsingTrait(StorageType* storage) {
 132     ConstructTrait::Construct(MutableInstance(storage));
 133   }
 134 };
 135
 136 #undef LAZY_ALIGN
 137
 138
 139 template <typename T>
 140 struct DynamicallyAllocatedInstanceTrait {
 141   typedef T* StorageType;
 142
 143   static T* MutableInstance(StorageType* storage) {
 144     return *storage;
 145   }
 146
 147   template <typename CreateTrait>
 148   static void InitStorageUsingTrait(StorageType* storage) {
 149     *storage = CreateTrait::Create();
 150   }
 151 };
 152
 153
 154 template <typename T>
 155 struct DefaultConstructTrait {
 156   // Constructs the provided object which was already allocated.
 157   static void Construct(T* allocated_ptr) {
 158     new(allocated_ptr) T();
 159   }
 160 };
 161
 162
 163 template <typename T>
 164 struct DefaultCreateTrait {
 165   static T* Create() {
 166     return new T();
 167   }
 168 };
 169
 170
 171 struct ThreadSafeInitOnceTrait {
 172   template <typename Function, typename Storage>
 173   static void Init(OnceType* once, Function function, Storage storage) {
 174     CallOnce(once, function, storage);
 175   }
 176 };
 177
 178
 179 // Initialization trait for users who don't care about thread-safety.
 180 struct SingleThreadInitOnceTrait {
 181   template <typename Function, typename Storage>
 182   static void Init(OnceType* once, Function function, Storage storage) {
 183     if (*once == ONCE_STATE_UNINITIALIZED) {
 184       function(storage);
 185       *once = ONCE_STATE_DONE;
 186     }
 187   }
 188 };
 189
 190
 191 // TODO(pliard): Handle instances destruction (using global destructors).
 192 template <typename T, typename AllocationTrait, typename CreateTrait,
 193           typename InitOnceTrait, typename DestroyTrait  /* not used yet. */>
 194 struct LazyInstanceImpl {
 195  public:
 196   typedef typename AllocationTrait::StorageType StorageType;
 197
 198  private:
 199   static void InitInstance(StorageType* storage) {
 200     AllocationTrait::template InitStorageUsingTrait<CreateTrait>(storage);
 201   }
 202
 203   void Init() const {
 204     InitOnceTrait::Init(
 205         &once_,
 206         // Casts to void* are needed here to avoid breaking strict aliasing
 207         // rules.
 208         reinterpret_cast<void(*)(void*)>(&InitInstance),  // NOLINT
 209         reinterpret_cast<void*>(&storage_));
 210   }
 211
 212  public:
 213   T* Pointer() {
 214     Init();
 215     return AllocationTrait::MutableInstance(&storage_);
 216   }
 217
 218   const T& Get() const {
 219     Init();
 220     return *AllocationTrait::MutableInstance(&storage_);
 221   }
 222
 223   mutable OnceType once_;
 224   // Note that the previous field, OnceType, is an AtomicWord which guarantees
 225   // 4-byte alignment of the storage field below. If compiling with GCC (>4.2),
 226   // the LAZY_ALIGN macro above will guarantee correctness for any alignment.
 227   mutable StorageType storage_;
 228 };
 229
 230
 231 template <typename T,
 232           typename CreateTrait = DefaultConstructTrait<T>,
 233           typename InitOnceTrait = SingleThreadInitOnceTrait,
 234           typename DestroyTrait = LeakyInstanceTrait<T> >
 235 struct LazyStaticInstance {
 236   typedef LazyInstanceImpl<T, StaticallyAllocatedInstanceTrait<T>,
 237       CreateTrait, InitOnceTrait, DestroyTrait> type;
 238 };
 239
 240
 241 template <typename T,
 242           typename CreateTrait = DefaultConstructTrait<T>,
 243           typename InitOnceTrait = SingleThreadInitOnceTrait,
 244           typename DestroyTrait = LeakyInstanceTrait<T> >
 245 struct LazyInstance {
 246   // A LazyInstance is a LazyStaticInstance.
 247   typedef typename LazyStaticInstance<T, CreateTrait, InitOnceTrait,
 248       DestroyTrait>::type type;
 249 };
 250
 251
 252 template <typename T,
 253           typename CreateTrait = DefaultCreateTrait<T>,
 254           typename InitOnceTrait = SingleThreadInitOnceTrait,
 255           typename DestroyTrait = LeakyInstanceTrait<T> >
 256 struct LazyDynamicInstance {
 257   typedef LazyInstanceImpl<T, DynamicallyAllocatedInstanceTrait<T>,
 258       CreateTrait, InitOnceTrait, DestroyTrait> type;
 259 };
 260
 261 } }  // namespace v8::internal
 262
 263 #endif  // V8_LAZY_INSTANCE_H_