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