Home | History | Annotate | Download | only in base
      1 // Copyright 2012 the V8 project authors. All rights reserved.
      2 // Use of this source code is governed by a BSD-style license that can be
      3 // found in the LICENSE file.
      4 
      5 // The LazyInstance<Type, Traits> class manages a single instance of Type,
      6 // which will be lazily created on the first time it's accessed.  This class is
      7 // useful for places you would normally use a function-level static, but you
      8 // need to have guaranteed thread-safety.  The Type constructor will only ever
      9 // be called once, even if two threads are racing to create the object.  Get()
     10 // and Pointer() will always return the same, completely initialized instance.
     11 //
     12 // LazyInstance is completely thread safe, assuming that you create it safely.
     13 // The class was designed to be POD initialized, so it shouldn't require a
     14 // static constructor.  It really only makes sense to declare a LazyInstance as
     15 // a global variable using the LAZY_INSTANCE_INITIALIZER initializer.
     16 //
     17 // LazyInstance is similar to Singleton, except it does not have the singleton
     18 // property.  You can have multiple LazyInstance's of the same type, and each
     19 // will manage a unique instance.  It also preallocates the space for Type, as
     20 // to avoid allocating the Type instance on the heap.  This may help with the
     21 // performance of creating the instance, and reducing heap fragmentation.  This
     22 // requires that Type be a complete type so we can determine the size. See
     23 // notes for advanced users below for more explanations.
     24 //
     25 // Example usage:
     26 //   static LazyInstance<MyClass>::type my_instance = LAZY_INSTANCE_INITIALIZER;
     27 //   void SomeMethod() {
     28 //     my_instance.Get().SomeMethod();  // MyClass::SomeMethod()
     29 //
     30 //     MyClass* ptr = my_instance.Pointer();
     31 //     ptr->DoDoDo();  // MyClass::DoDoDo
     32 //   }
     33 //
     34 // Additionally you can override the way your instance is constructed by
     35 // providing your own trait:
     36 // Example usage:
     37 //   struct MyCreateTrait {
     38 //     static void Construct(MyClass* allocated_ptr) {
     39 //       new (allocated_ptr) MyClass(/* extra parameters... */);
     40 //     }
     41 //   };
     42 //   static LazyInstance<MyClass, MyCreateTrait>::type my_instance =
     43 //      LAZY_INSTANCE_INITIALIZER;
     44 //
     45 // WARNINGS:
     46 // - This implementation of LazyInstance IS THREAD-SAFE by default. See
     47 //   SingleThreadInitOnceTrait if you don't care about thread safety.
     48 // - Lazy initialization comes with a cost. Make sure that you don't use it on
     49 //   critical path. Consider adding your initialization code to a function
     50 //   which is explicitly called once.
     51 //
     52 // Notes for advanced users:
     53 // LazyInstance can actually be used in two different ways:
     54 //
     55 // - "Static mode" which is the default mode since it is the most efficient
     56 //   (no extra heap allocation). In this mode, the instance is statically
     57 //   allocated (stored in the global data section at compile time).
     58 //   The macro LAZY_STATIC_INSTANCE_INITIALIZER (= LAZY_INSTANCE_INITIALIZER)
     59 //   must be used to initialize static lazy instances.
     60 //
     61 // - "Dynamic mode". In this mode, the instance is dynamically allocated and
     62 //   constructed (using new) by default. This mode is useful if you have to
     63 //   deal with some code already allocating the instance for you (e.g.
     64 //   OS::Mutex() which returns a new private OS-dependent subclass of Mutex).
     65 //   The macro LAZY_DYNAMIC_INSTANCE_INITIALIZER must be used to initialize
     66 //   dynamic lazy instances.
     67 
     68 #ifndef V8_BASE_LAZY_INSTANCE_H_
     69 #define V8_BASE_LAZY_INSTANCE_H_
     70 
     71 #include "src/base/macros.h"
     72 #include "src/base/once.h"
     73 
     74 namespace v8 {
     75 namespace base {
     76 
     77 #define LAZY_STATIC_INSTANCE_INITIALIZER { V8_ONCE_INIT, { {} } }
     78 #define LAZY_DYNAMIC_INSTANCE_INITIALIZER { V8_ONCE_INIT, 0 }
     79 
     80 // Default to static mode.
     81 #define LAZY_INSTANCE_INITIALIZER LAZY_STATIC_INSTANCE_INITIALIZER
     82 
     83 
     84 template <typename T>
     85 struct LeakyInstanceTrait {
     86   static void Destroy(T* /* instance */) {}
     87 };
     88 
     89 
     90 // Traits that define how an instance is allocated and accessed.
     91 
     92 
     93 template <typename T>
     94 struct StaticallyAllocatedInstanceTrait {
     95   // 16-byte alignment fallback to be on the safe side here.
     96   struct V8_ALIGNAS(T, 16) StorageType {
     97     char x[sizeof(T)];
     98   };
     99 
    100   STATIC_ASSERT(V8_ALIGNOF(StorageType) >= V8_ALIGNOF(T));
    101 
    102   static T* MutableInstance(StorageType* storage) {
    103     return reinterpret_cast<T*>(storage);
    104   }
    105 
    106   template <typename ConstructTrait>
    107   static void InitStorageUsingTrait(StorageType* storage) {
    108     ConstructTrait::Construct(MutableInstance(storage));
    109   }
    110 };
    111 
    112 
    113 template <typename T>
    114 struct DynamicallyAllocatedInstanceTrait {
    115   typedef T* StorageType;
    116 
    117   static T* MutableInstance(StorageType* storage) {
    118     return *storage;
    119   }
    120 
    121   template <typename CreateTrait>
    122   static void InitStorageUsingTrait(StorageType* storage) {
    123     *storage = CreateTrait::Create();
    124   }
    125 };
    126 
    127 
    128 template <typename T>
    129 struct DefaultConstructTrait {
    130   // Constructs the provided object which was already allocated.
    131   static void Construct(T* allocated_ptr) {
    132     new(allocated_ptr) T();
    133   }
    134 };
    135 
    136 
    137 template <typename T>
    138 struct DefaultCreateTrait {
    139   static T* Create() {
    140     return new T();
    141   }
    142 };
    143 
    144 
    145 struct ThreadSafeInitOnceTrait {
    146   template <typename Function, typename Storage>
    147   static void Init(OnceType* once, Function function, Storage storage) {
    148     CallOnce(once, function, storage);
    149   }
    150 };
    151 
    152 
    153 // Initialization trait for users who don't care about thread-safety.
    154 struct SingleThreadInitOnceTrait {
    155   template <typename Function, typename Storage>
    156   static void Init(OnceType* once, Function function, Storage storage) {
    157     if (*once == ONCE_STATE_UNINITIALIZED) {
    158       function(storage);
    159       *once = ONCE_STATE_DONE;
    160     }
    161   }
    162 };
    163 
    164 
    165 // TODO(pliard): Handle instances destruction (using global destructors).
    166 template <typename T, typename AllocationTrait, typename CreateTrait,
    167           typename InitOnceTrait, typename DestroyTrait  /* not used yet. */>
    168 struct LazyInstanceImpl {
    169  public:
    170   typedef typename AllocationTrait::StorageType StorageType;
    171 
    172  private:
    173   static void InitInstance(StorageType* storage) {
    174     AllocationTrait::template InitStorageUsingTrait<CreateTrait>(storage);
    175   }
    176 
    177   void Init() const {
    178     InitOnceTrait::Init(
    179         &once_,
    180         // Casts to void* are needed here to avoid breaking strict aliasing
    181         // rules.
    182         reinterpret_cast<void(*)(void*)>(&InitInstance),  // NOLINT
    183         reinterpret_cast<void*>(&storage_));
    184   }
    185 
    186  public:
    187   T* Pointer() {
    188     Init();
    189     return AllocationTrait::MutableInstance(&storage_);
    190   }
    191 
    192   const T& Get() const {
    193     Init();
    194     return *AllocationTrait::MutableInstance(&storage_);
    195   }
    196 
    197   mutable OnceType once_;
    198   // Note that the previous field, OnceType, is an AtomicWord which guarantees
    199   // 4-byte alignment of the storage field below. If compiling with GCC (>4.2),
    200   // the LAZY_ALIGN macro above will guarantee correctness for any alignment.
    201   mutable StorageType storage_;
    202 };
    203 
    204 
    205 template <typename T,
    206           typename CreateTrait = DefaultConstructTrait<T>,
    207           typename InitOnceTrait = ThreadSafeInitOnceTrait,
    208           typename DestroyTrait = LeakyInstanceTrait<T> >
    209 struct LazyStaticInstance {
    210   typedef LazyInstanceImpl<T, StaticallyAllocatedInstanceTrait<T>,
    211       CreateTrait, InitOnceTrait, DestroyTrait> type;
    212 };
    213 
    214 
    215 template <typename T,
    216           typename CreateTrait = DefaultConstructTrait<T>,
    217           typename InitOnceTrait = ThreadSafeInitOnceTrait,
    218           typename DestroyTrait = LeakyInstanceTrait<T> >
    219 struct LazyInstance {
    220   // A LazyInstance is a LazyStaticInstance.
    221   typedef typename LazyStaticInstance<T, CreateTrait, InitOnceTrait,
    222       DestroyTrait>::type type;
    223 };
    224 
    225 
    226 template <typename T,
    227           typename CreateTrait = DefaultCreateTrait<T>,
    228           typename InitOnceTrait = ThreadSafeInitOnceTrait,
    229           typename DestroyTrait = LeakyInstanceTrait<T> >
    230 struct LazyDynamicInstance {
    231   typedef LazyInstanceImpl<T, DynamicallyAllocatedInstanceTrait<T>,
    232       CreateTrait, InitOnceTrait, DestroyTrait> type;
    233 };
    234 
    235 } }  // namespace v8::base
    236 
    237 #endif  // V8_BASE_LAZY_INSTANCE_H_
    238