fischman@chromium.org | 998561e | 2012-01-24 07:56:41 +0900 | [diff] [blame] | 1 | // Copyright (c) 2012 The Chromium Authors. All rights reserved. |
deanm@google.com | a6deb00 | 2008-09-08 23:11:13 +0900 | [diff] [blame] | 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 | // When the instance is constructed it is registered with AtExitManager. The |
| 12 | // destructor will be called on program exit. |
| 13 | // |
| 14 | // LazyInstance is completely thread safe, assuming that you create it safely. |
| 15 | // The class was designed to be POD initialized, so it shouldn't require a |
| 16 | // static constructor. It really only makes sense to declare a LazyInstance as |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 17 | // a global variable using the LAZY_INSTANCE_INITIALIZER initializer. |
deanm@google.com | a6deb00 | 2008-09-08 23:11:13 +0900 | [diff] [blame] | 18 | // |
| 19 | // LazyInstance is similar to Singleton, except it does not have the singleton |
| 20 | // property. You can have multiple LazyInstance's of the same type, and each |
| 21 | // will manage a unique instance. It also preallocates the space for Type, as |
| 22 | // to avoid allocating the Type instance on the heap. This may help with the |
| 23 | // performance of creating the instance, and reducing heap fragmentation. This |
| 24 | // requires that Type be a complete type so we can determine the size. |
| 25 | // |
| 26 | // Example usage: |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 27 | // static LazyInstance<MyClass> my_instance = LAZY_INSTANCE_INITIALIZER; |
deanm@google.com | a6deb00 | 2008-09-08 23:11:13 +0900 | [diff] [blame] | 28 | // void SomeMethod() { |
| 29 | // my_instance.Get().SomeMethod(); // MyClass::SomeMethod() |
maruel@chromium.org | 8fe7adc | 2009-03-04 00:01:12 +0900 | [diff] [blame] | 30 | // |
deanm@google.com | a6deb00 | 2008-09-08 23:11:13 +0900 | [diff] [blame] | 31 | // MyClass* ptr = my_instance.Pointer(); |
| 32 | // ptr->DoDoDo(); // MyClass::DoDoDo |
| 33 | // } |
| 34 | |
| 35 | #ifndef BASE_LAZY_INSTANCE_H_ |
| 36 | #define BASE_LAZY_INSTANCE_H_ |
| 37 | |
willchan@chromium.org | 25726ef | 2010-11-20 05:34:18 +0900 | [diff] [blame] | 38 | #include <new> // For placement new. |
| 39 | |
deanm@google.com | a6deb00 | 2008-09-08 23:11:13 +0900 | [diff] [blame] | 40 | #include "base/atomicops.h" |
darin@chromium.org | e585bed | 2011-08-06 00:34:00 +0900 | [diff] [blame] | 41 | #include "base/base_export.h" |
deanm@google.com | a6deb00 | 2008-09-08 23:11:13 +0900 | [diff] [blame] | 42 | #include "base/basictypes.h" |
earthdok@google.com | 00c0afd | 2013-06-08 07:09:32 +0900 | [diff] [blame] | 43 | #include "base/debug/leak_annotations.h" |
timurrrr@chromium.org | 4814da9 | 2011-10-22 04:46:00 +0900 | [diff] [blame] | 44 | #include "base/logging.h" |
jbates@chromium.org | dde8e30 | 2012-02-24 02:52:20 +0900 | [diff] [blame] | 45 | #include "base/memory/aligned_memory.h" |
brettw@chromium.org | 5b5f5e0 | 2011-01-01 10:01:06 +0900 | [diff] [blame] | 46 | #include "base/threading/thread_restrictions.h" |
deanm@google.com | a6deb00 | 2008-09-08 23:11:13 +0900 | [diff] [blame] | 47 | |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 48 | // LazyInstance uses its own struct initializer-list style static |
| 49 | // initialization, as base's LINKER_INITIALIZED requires a constructor and on |
| 50 | // some compilers (notably gcc 4.4) this still ends up needing runtime |
| 51 | // initialization. |
| 52 | #define LAZY_INSTANCE_INITIALIZER {0} |
| 53 | |
deanm@google.com | a6deb00 | 2008-09-08 23:11:13 +0900 | [diff] [blame] | 54 | namespace base { |
| 55 | |
| 56 | template <typename Type> |
| 57 | struct DefaultLazyInstanceTraits { |
joth@chromium.org | 524b5ce | 2011-10-26 04:04:48 +0900 | [diff] [blame] | 58 | static const bool kRegisterOnExit = true; |
thakis@chromium.org | 2a1f926 | 2014-03-06 10:11:54 +0900 | [diff] [blame] | 59 | #ifndef NDEBUG |
willchan@chromium.org | 25726ef | 2010-11-20 05:34:18 +0900 | [diff] [blame] | 60 | static const bool kAllowedToAccessOnNonjoinableThread = false; |
thakis@chromium.org | 2a1f926 | 2014-03-06 10:11:54 +0900 | [diff] [blame] | 61 | #endif |
willchan@chromium.org | 25726ef | 2010-11-20 05:34:18 +0900 | [diff] [blame] | 62 | |
craig.schlenter@chromium.org | 0cf5833 | 2010-03-13 00:28:48 +0900 | [diff] [blame] | 63 | static Type* New(void* instance) { |
jbates@chromium.org | dde8e30 | 2012-02-24 02:52:20 +0900 | [diff] [blame] | 64 | DCHECK_EQ(reinterpret_cast<uintptr_t>(instance) & (ALIGNOF(Type) - 1), 0u) |
timurrrr@chromium.org | 4814da9 | 2011-10-22 04:46:00 +0900 | [diff] [blame] | 65 | << ": Bad boy, the buffer passed to placement new is not aligned!\n" |
| 66 | "This may break some stuff like SSE-based optimizations assuming the " |
| 67 | "<Type> objects are word aligned."; |
deanm@google.com | a6deb00 | 2008-09-08 23:11:13 +0900 | [diff] [blame] | 68 | // Use placement new to initialize our instance in our preallocated space. |
| 69 | // The parenthesis is very important here to force POD type initialization. |
craig.schlenter@chromium.org | 0cf5833 | 2010-03-13 00:28:48 +0900 | [diff] [blame] | 70 | return new (instance) Type(); |
deanm@google.com | a6deb00 | 2008-09-08 23:11:13 +0900 | [diff] [blame] | 71 | } |
joth@chromium.org | 524b5ce | 2011-10-26 04:04:48 +0900 | [diff] [blame] | 72 | static void Delete(Type* instance) { |
deanm@google.com | a6deb00 | 2008-09-08 23:11:13 +0900 | [diff] [blame] | 73 | // Explicitly call the destructor. |
joth@chromium.org | 524b5ce | 2011-10-26 04:04:48 +0900 | [diff] [blame] | 74 | instance->~Type(); |
deanm@google.com | a6deb00 | 2008-09-08 23:11:13 +0900 | [diff] [blame] | 75 | } |
| 76 | }; |
| 77 | |
fischman@chromium.org | dfdfa90 | 2012-01-26 10:56:19 +0900 | [diff] [blame] | 78 | // We pull out some of the functionality into non-templated functions, so we |
| 79 | // can implement the more complicated pieces out of line in the .cc file. |
| 80 | namespace internal { |
| 81 | |
fischman@chromium.org | 998561e | 2012-01-24 07:56:41 +0900 | [diff] [blame] | 82 | // Use LazyInstance<T>::Leaky for a less-verbose call-site typedef; e.g.: |
| 83 | // base::LazyInstance<T>::Leaky my_leaky_lazy_instance; |
| 84 | // instead of: |
fischman@chromium.org | dfdfa90 | 2012-01-26 10:56:19 +0900 | [diff] [blame] | 85 | // base::LazyInstance<T, base::internal::LeakyLazyInstanceTraits<T> > |
| 86 | // my_leaky_lazy_instance; |
fischman@chromium.org | 998561e | 2012-01-24 07:56:41 +0900 | [diff] [blame] | 87 | // (especially when T is MyLongTypeNameImplClientHolderFactory). |
fischman@chromium.org | dfdfa90 | 2012-01-26 10:56:19 +0900 | [diff] [blame] | 88 | // Only use this internal::-qualified verbose form to extend this traits class |
| 89 | // (depending on its implementation details). |
evan@chromium.org | a04f70c | 2010-10-22 05:41:47 +0900 | [diff] [blame] | 90 | template <typename Type> |
| 91 | struct LeakyLazyInstanceTraits { |
joth@chromium.org | 524b5ce | 2011-10-26 04:04:48 +0900 | [diff] [blame] | 92 | static const bool kRegisterOnExit = false; |
thakis@chromium.org | 2a1f926 | 2014-03-06 10:11:54 +0900 | [diff] [blame] | 93 | #ifndef NDEBUG |
willchan@chromium.org | 25726ef | 2010-11-20 05:34:18 +0900 | [diff] [blame] | 94 | static const bool kAllowedToAccessOnNonjoinableThread = true; |
thakis@chromium.org | 2a1f926 | 2014-03-06 10:11:54 +0900 | [diff] [blame] | 95 | #endif |
willchan@chromium.org | 25726ef | 2010-11-20 05:34:18 +0900 | [diff] [blame] | 96 | |
evan@chromium.org | a04f70c | 2010-10-22 05:41:47 +0900 | [diff] [blame] | 97 | static Type* New(void* instance) { |
earthdok@google.com | 00c0afd | 2013-06-08 07:09:32 +0900 | [diff] [blame] | 98 | ANNOTATE_SCOPED_MEMORY_LEAK; |
evan@chromium.org | a04f70c | 2010-10-22 05:41:47 +0900 | [diff] [blame] | 99 | return DefaultLazyInstanceTraits<Type>::New(instance); |
| 100 | } |
joth@chromium.org | 524b5ce | 2011-10-26 04:04:48 +0900 | [diff] [blame] | 101 | static void Delete(Type* instance) { |
| 102 | } |
evan@chromium.org | a04f70c | 2010-10-22 05:41:47 +0900 | [diff] [blame] | 103 | }; |
| 104 | |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 105 | // Our AtomicWord doubles as a spinlock, where a value of |
| 106 | // kBeingCreatedMarker means the spinlock is being held for creation. |
| 107 | static const subtle::AtomicWord kLazyInstanceStateCreating = 1; |
dvyukov@google.com | 6beeb83 | 2011-05-17 00:01:54 +0900 | [diff] [blame] | 108 | |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 109 | // Check if instance needs to be created. If so return true otherwise |
| 110 | // if another thread has beat us, wait for instance to be created and |
| 111 | // return false. |
| 112 | BASE_EXPORT bool NeedsLazyInstance(subtle::AtomicWord* state); |
deanm@google.com | a6deb00 | 2008-09-08 23:11:13 +0900 | [diff] [blame] | 113 | |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 114 | // After creating an instance, call this to register the dtor to be called |
| 115 | // at program exit and to update the atomic state to hold the |new_instance| |
| 116 | BASE_EXPORT void CompleteLazyInstance(subtle::AtomicWord* state, |
| 117 | subtle::AtomicWord new_instance, |
| 118 | void* lazy_instance, |
| 119 | void (*dtor)(void*)); |
dvyukov@google.com | 6beeb83 | 2011-05-17 00:01:54 +0900 | [diff] [blame] | 120 | |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 121 | } // namespace internal |
deanm@google.com | a6deb00 | 2008-09-08 23:11:13 +0900 | [diff] [blame] | 122 | |
| 123 | template <typename Type, typename Traits = DefaultLazyInstanceTraits<Type> > |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 124 | class LazyInstance { |
deanm@google.com | a6deb00 | 2008-09-08 23:11:13 +0900 | [diff] [blame] | 125 | public: |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 126 | // Do not define a destructor, as doing so makes LazyInstance a |
| 127 | // non-POD-struct. We don't want that because then a static initializer will |
| 128 | // be created to register the (empty) destructor with atexit() under MSVC, for |
| 129 | // example. We handle destruction of the contained Type class explicitly via |
| 130 | // the OnExit member function, where needed. |
dvyukov@google.com | 6beeb83 | 2011-05-17 00:01:54 +0900 | [diff] [blame] | 131 | // ~LazyInstance() {} |
deanm@google.com | a6deb00 | 2008-09-08 23:11:13 +0900 | [diff] [blame] | 132 | |
fischman@chromium.org | 998561e | 2012-01-24 07:56:41 +0900 | [diff] [blame] | 133 | // Convenience typedef to avoid having to repeat Type for leaky lazy |
| 134 | // instances. |
fischman@chromium.org | dfdfa90 | 2012-01-26 10:56:19 +0900 | [diff] [blame] | 135 | typedef LazyInstance<Type, internal::LeakyLazyInstanceTraits<Type> > Leaky; |
fischman@chromium.org | 998561e | 2012-01-24 07:56:41 +0900 | [diff] [blame] | 136 | |
deanm@google.com | a6deb00 | 2008-09-08 23:11:13 +0900 | [diff] [blame] | 137 | Type& Get() { |
| 138 | return *Pointer(); |
| 139 | } |
| 140 | |
| 141 | Type* Pointer() { |
joth@chromium.org | d70623d | 2011-11-05 02:29:10 +0900 | [diff] [blame] | 142 | #ifndef NDEBUG |
| 143 | // Avoid making TLS lookup on release builds. |
willchan@chromium.org | 25726ef | 2010-11-20 05:34:18 +0900 | [diff] [blame] | 144 | if (!Traits::kAllowedToAccessOnNonjoinableThread) |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 145 | ThreadRestrictions::AssertSingletonAllowed(); |
joth@chromium.org | d70623d | 2011-11-05 02:29:10 +0900 | [diff] [blame] | 146 | #endif |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 147 | // If any bit in the created mask is true, the instance has already been |
| 148 | // fully constructed. |
| 149 | static const subtle::AtomicWord kLazyInstanceCreatedMask = |
| 150 | ~internal::kLazyInstanceStateCreating; |
willchan@chromium.org | 25726ef | 2010-11-20 05:34:18 +0900 | [diff] [blame] | 151 | |
deanm@google.com | a6deb00 | 2008-09-08 23:11:13 +0900 | [diff] [blame] | 152 | // We will hopefully have fast access when the instance is already created. |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 153 | // Since a thread sees private_instance_ == 0 or kLazyInstanceStateCreating |
| 154 | // at most once, the load is taken out of NeedsInstance() as a fast-path. |
dvyukov@google.com | 6beeb83 | 2011-05-17 00:01:54 +0900 | [diff] [blame] | 155 | // The load has acquire memory ordering as a thread which sees |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 156 | // private_instance_ > creating needs to acquire visibility over |
| 157 | // the associated data (private_buf_). Pairing Release_Store is in |
| 158 | // CompleteLazyInstance(). |
| 159 | subtle::AtomicWord value = subtle::Acquire_Load(&private_instance_); |
| 160 | if (!(value & kLazyInstanceCreatedMask) && |
| 161 | internal::NeedsLazyInstance(&private_instance_)) { |
| 162 | // Create the instance in the space provided by |private_buf_|. |
jbates@chromium.org | dde8e30 | 2012-02-24 02:52:20 +0900 | [diff] [blame] | 163 | value = reinterpret_cast<subtle::AtomicWord>( |
| 164 | Traits::New(private_buf_.void_data())); |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 165 | internal::CompleteLazyInstance(&private_instance_, value, this, |
| 166 | Traits::kRegisterOnExit ? OnExit : NULL); |
craig.schlenter@chromium.org | 0cf5833 | 2010-03-13 00:28:48 +0900 | [diff] [blame] | 167 | } |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 168 | return instance(); |
deanm@google.com | a6deb00 | 2008-09-08 23:11:13 +0900 | [diff] [blame] | 169 | } |
| 170 | |
dilmah@chromium.org | 19b6869 | 2011-02-23 04:21:59 +0900 | [diff] [blame] | 171 | bool operator==(Type* p) { |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 172 | switch (subtle::NoBarrier_Load(&private_instance_)) { |
| 173 | case 0: |
dilmah@chromium.org | 19b6869 | 2011-02-23 04:21:59 +0900 | [diff] [blame] | 174 | return p == NULL; |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 175 | case internal::kLazyInstanceStateCreating: |
jbates@chromium.org | dde8e30 | 2012-02-24 02:52:20 +0900 | [diff] [blame] | 176 | return static_cast<void*>(p) == private_buf_.void_data(); |
dilmah@chromium.org | 19b6869 | 2011-02-23 04:21:59 +0900 | [diff] [blame] | 177 | default: |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 178 | return p == instance(); |
dilmah@chromium.org | 19b6869 | 2011-02-23 04:21:59 +0900 | [diff] [blame] | 179 | } |
| 180 | } |
| 181 | |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 182 | // Effectively private: member data is only public to allow the linker to |
jbates@chromium.org | dde8e30 | 2012-02-24 02:52:20 +0900 | [diff] [blame] | 183 | // statically initialize it and to maintain a POD class. DO NOT USE FROM |
| 184 | // OUTSIDE THIS CLASS. |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 185 | |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 186 | subtle::AtomicWord private_instance_; |
jbates@chromium.org | dde8e30 | 2012-02-24 02:52:20 +0900 | [diff] [blame] | 187 | // Preallocated space for the Type instance. |
| 188 | base::AlignedMemory<sizeof(Type), ALIGNOF(Type)> private_buf_; |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 189 | |
deanm@google.com | a6deb00 | 2008-09-08 23:11:13 +0900 | [diff] [blame] | 190 | private: |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 191 | Type* instance() { |
| 192 | return reinterpret_cast<Type*>(subtle::NoBarrier_Load(&private_instance_)); |
| 193 | } |
| 194 | |
satish@chromium.org | 2940ad1 | 2010-12-14 16:48:49 +0900 | [diff] [blame] | 195 | // Adapter function for use with AtExit. This should be called single |
joth@chromium.org | 524b5ce | 2011-10-26 04:04:48 +0900 | [diff] [blame] | 196 | // threaded, so don't synchronize across threads. |
satish@chromium.org | 2940ad1 | 2010-12-14 16:48:49 +0900 | [diff] [blame] | 197 | // Calling OnExit while the instance is in use by other threads is a mistake. |
| 198 | static void OnExit(void* lazy_instance) { |
| 199 | LazyInstance<Type, Traits>* me = |
| 200 | reinterpret_cast<LazyInstance<Type, Traits>*>(lazy_instance); |
joth@chromium.org | b24883c | 2011-11-15 22:31:49 +0900 | [diff] [blame] | 201 | Traits::Delete(me->instance()); |
jbates@chromium.org | dde8e30 | 2012-02-24 02:52:20 +0900 | [diff] [blame] | 202 | subtle::NoBarrier_Store(&me->private_instance_, 0); |
satish@chromium.org | 2940ad1 | 2010-12-14 16:48:49 +0900 | [diff] [blame] | 203 | } |
deanm@google.com | a6deb00 | 2008-09-08 23:11:13 +0900 | [diff] [blame] | 204 | }; |
| 205 | |
| 206 | } // namespace base |
| 207 | |
| 208 | #endif // BASE_LAZY_INSTANCE_H_ |