V8 API Reference, 7.2.502.16 (for Deno 0.2.4)
lazy-instance.h
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(void* 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>
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>
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(storage);
109  }
110 };
111 
112 
113 template <typename T>
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>
130  // Constructs the provided object which was already allocated.
131  static void Construct(void* allocated_ptr) { new (allocated_ptr) T(); }
132 };
133 
134 
135 template <typename T>
137  static T* Create() {
138  return new T();
139  }
140 };
141 
142 
144  template <typename Function, typename Storage>
145  static void Init(OnceType* once, Function function, Storage storage) {
146  CallOnce(once, function, storage);
147  }
148 };
149 
150 
151 // Initialization trait for users who don't care about thread-safety.
153  template <typename Function, typename Storage>
154  static void Init(OnceType* once, Function function, Storage storage) {
155  if (*once == ONCE_STATE_UNINITIALIZED) {
156  function(storage);
157  *once = ONCE_STATE_DONE;
158  }
159  }
160 };
161 
162 
163 // TODO(pliard): Handle instances destruction (using global destructors).
164 template <typename T, typename AllocationTrait, typename CreateTrait,
165  typename InitOnceTrait, typename DestroyTrait /* not used yet. */>
167  public:
168  typedef typename AllocationTrait::StorageType StorageType;
169 
170  private:
171  static void InitInstance(void* storage) {
172  AllocationTrait::template InitStorageUsingTrait<CreateTrait>(
173  static_cast<StorageType*>(storage));
174  }
175 
176  void Init() const {
177  InitOnceTrait::Init(&once_, &InitInstance, static_cast<void*>(&storage_));
178  }
179 
180  public:
181  T* Pointer() {
182  Init();
183  return AllocationTrait::MutableInstance(&storage_);
184  }
185 
186  const T& Get() const {
187  Init();
188  return *AllocationTrait::MutableInstance(&storage_);
189  }
190 
191  mutable OnceType once_;
192  // Note that the previous field, OnceType, is an AtomicWord which guarantees
193  // 4-byte alignment of the storage field below. If compiling with GCC (>4.2),
194  // the LAZY_ALIGN macro above will guarantee correctness for any alignment.
195  mutable StorageType storage_;
196 };
197 
198 
199 template <typename T,
200  typename CreateTrait = DefaultConstructTrait<T>,
201  typename InitOnceTrait = ThreadSafeInitOnceTrait,
202  typename DestroyTrait = LeakyInstanceTrait<T> >
205  CreateTrait, InitOnceTrait, DestroyTrait> type;
206 };
207 
208 
209 template <typename T,
210  typename CreateTrait = DefaultConstructTrait<T>,
211  typename InitOnceTrait = ThreadSafeInitOnceTrait,
212  typename DestroyTrait = LeakyInstanceTrait<T> >
213 struct LazyInstance {
214  // A LazyInstance is a LazyStaticInstance.
215  typedef typename LazyStaticInstance<T, CreateTrait, InitOnceTrait,
216  DestroyTrait>::type type;
217 };
218 
219 
220 template <typename T,
221  typename CreateTrait = DefaultCreateTrait<T>,
222  typename InitOnceTrait = ThreadSafeInitOnceTrait,
223  typename DestroyTrait = LeakyInstanceTrait<T> >
226  CreateTrait, InitOnceTrait, DestroyTrait> type;
227 };
228 
229 } // namespace base
230 } // namespace v8
231 
232 #endif // V8_BASE_LAZY_INSTANCE_H_
Definition: libplatform.h:13