jkummerow@chromium.org | 1456e70 | 2012-03-30 08:38:13 +0000 | [diff] [blame] | 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 | // |
fschneider@chromium.org | 7d10be5 | 2012-04-10 12:30:14 +0000 | [diff] [blame] | 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. |
danno@chromium.org | 8c0a43f | 2012-04-03 08:37:53 +0000 | [diff] [blame] | 74 | // |
jkummerow@chromium.org | 1456e70 | 2012-03-30 08:38:13 +0000 | [diff] [blame] | 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 | |
fschneider@chromium.org | 7d10be5 | 2012-04-10 12:30:14 +0000 | [diff] [blame] | 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 | |
jkummerow@chromium.org | 1456e70 | 2012-03-30 08:38:13 +0000 | [diff] [blame] | 122 | template <typename T> |
| 123 | struct StaticallyAllocatedInstanceTrait { |
fschneider@chromium.org | 7d10be5 | 2012-04-10 12:30:14 +0000 | [diff] [blame] | 124 | typedef char StorageType[sizeof(T)] LAZY_ALIGN(T); |
jkummerow@chromium.org | 1456e70 | 2012-03-30 08:38:13 +0000 | [diff] [blame] | 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 | |
fschneider@chromium.org | 7d10be5 | 2012-04-10 12:30:14 +0000 | [diff] [blame] | 136 | #undef LAZY_ALIGN |
| 137 | |
jkummerow@chromium.org | 1456e70 | 2012-03-30 08:38:13 +0000 | [diff] [blame] | 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 | |
danno@chromium.org | 8c0a43f | 2012-04-03 08:37:53 +0000 | [diff] [blame] | 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 | |
jkummerow@chromium.org | 1456e70 | 2012-03-30 08:38:13 +0000 | [diff] [blame] | 191 | // TODO(pliard): Handle instances destruction (using global destructors). |
| 192 | template <typename T, typename AllocationTrait, typename CreateTrait, |
danno@chromium.org | 8c0a43f | 2012-04-03 08:37:53 +0000 | [diff] [blame] | 193 | typename InitOnceTrait, typename DestroyTrait /* not used yet. */> |
jkummerow@chromium.org | 1456e70 | 2012-03-30 08:38:13 +0000 | [diff] [blame] | 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 { |
danno@chromium.org | 8c0a43f | 2012-04-03 08:37:53 +0000 | [diff] [blame] | 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_)); |
jkummerow@chromium.org | 1456e70 | 2012-03-30 08:38:13 +0000 | [diff] [blame] | 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 |
fschneider@chromium.org | 7d10be5 | 2012-04-10 12:30:14 +0000 | [diff] [blame] | 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. |
jkummerow@chromium.org | 1456e70 | 2012-03-30 08:38:13 +0000 | [diff] [blame] | 227 | mutable StorageType storage_; |
| 228 | }; |
| 229 | |
| 230 | |
| 231 | template <typename T, |
| 232 | typename CreateTrait = DefaultConstructTrait<T>, |
danno@chromium.org | 8c0a43f | 2012-04-03 08:37:53 +0000 | [diff] [blame] | 233 | typename InitOnceTrait = SingleThreadInitOnceTrait, |
jkummerow@chromium.org | 1456e70 | 2012-03-30 08:38:13 +0000 | [diff] [blame] | 234 | typename DestroyTrait = LeakyInstanceTrait<T> > |
| 235 | struct LazyStaticInstance { |
danno@chromium.org | 8c0a43f | 2012-04-03 08:37:53 +0000 | [diff] [blame] | 236 | typedef LazyInstanceImpl<T, StaticallyAllocatedInstanceTrait<T>, |
| 237 | CreateTrait, InitOnceTrait, DestroyTrait> type; |
jkummerow@chromium.org | 1456e70 | 2012-03-30 08:38:13 +0000 | [diff] [blame] | 238 | }; |
| 239 | |
| 240 | |
| 241 | template <typename T, |
| 242 | typename CreateTrait = DefaultConstructTrait<T>, |
danno@chromium.org | 8c0a43f | 2012-04-03 08:37:53 +0000 | [diff] [blame] | 243 | typename InitOnceTrait = SingleThreadInitOnceTrait, |
jkummerow@chromium.org | 1456e70 | 2012-03-30 08:38:13 +0000 | [diff] [blame] | 244 | typename DestroyTrait = LeakyInstanceTrait<T> > |
| 245 | struct LazyInstance { |
| 246 | // A LazyInstance is a LazyStaticInstance. |
danno@chromium.org | 8c0a43f | 2012-04-03 08:37:53 +0000 | [diff] [blame] | 247 | typedef typename LazyStaticInstance<T, CreateTrait, InitOnceTrait, |
| 248 | DestroyTrait>::type type; |
jkummerow@chromium.org | 1456e70 | 2012-03-30 08:38:13 +0000 | [diff] [blame] | 249 | }; |
| 250 | |
| 251 | |
| 252 | template <typename T, |
svenpanne@chromium.org | fb04633 | 2012-04-19 12:02:44 +0000 | [diff] [blame] | 253 | typename CreateTrait = DefaultCreateTrait<T>, |
danno@chromium.org | 8c0a43f | 2012-04-03 08:37:53 +0000 | [diff] [blame] | 254 | typename InitOnceTrait = SingleThreadInitOnceTrait, |
jkummerow@chromium.org | 1456e70 | 2012-03-30 08:38:13 +0000 | [diff] [blame] | 255 | typename DestroyTrait = LeakyInstanceTrait<T> > |
| 256 | struct LazyDynamicInstance { |
danno@chromium.org | 8c0a43f | 2012-04-03 08:37:53 +0000 | [diff] [blame] | 257 | typedef LazyInstanceImpl<T, DynamicallyAllocatedInstanceTrait<T>, |
| 258 | CreateTrait, InitOnceTrait, DestroyTrait> type; |
jkummerow@chromium.org | 1456e70 | 2012-03-30 08:38:13 +0000 | [diff] [blame] | 259 | }; |
| 260 | |
| 261 | } } // namespace v8::internal |
| 262 | |
| 263 | #endif // V8_LAZY_INSTANCE_H_ |