v8  3.14.5(node0.10.28)
V8 is Google's open source JavaScript engine
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
lazy-instance.h
Go to the documentation of this file.
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>
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>
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>
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>
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>
165  static T* Create() {
166  return new T();
167  }
168 };
169 
170 
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.
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. */>
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.
228 };
229 
230 
231 template <typename T,
232  typename CreateTrait = DefaultConstructTrait<T>,
233  typename InitOnceTrait = SingleThreadInitOnceTrait,
234  typename DestroyTrait = LeakyInstanceTrait<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> >
258  CreateTrait, InitOnceTrait, DestroyTrait> type;
259 };
260 
261 } } // namespace v8::internal
262 
263 #endif // V8_LAZY_INSTANCE_H_
static T * MutableInstance(StorageType *storage)
static void Construct(T *allocated_ptr)
AllocationTrait::StorageType StorageType
void CallOnce(OnceType *once, NoArgFunction init_func)
Definition: once.h:105
static void InitStorageUsingTrait(StorageType *storage)
LazyInstanceImpl< T, StaticallyAllocatedInstanceTrait< T >, CreateTrait, InitOnceTrait, DestroyTrait > type
AtomicWord OnceType
Definition: once.h:83
static void InitStorageUsingTrait(StorageType *storage)
char StorageType[sizeof(T)] LAZY_ALIGN(T)
static void Init(OnceType *once, Function function, Storage storage)
#define T(name, string, precedence)
Definition: token.cc:48
static T * MutableInstance(StorageType *storage)
static void Init(OnceType *once, Function function, Storage storage)
LazyStaticInstance< T, CreateTrait, InitOnceTrait, DestroyTrait >::type type
LazyInstanceImpl< T, DynamicallyAllocatedInstanceTrait< T >, CreateTrait, InitOnceTrait, DestroyTrait > type