1 // Copyright (c) 2011 The Chromium 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.
5 // PLEASE READ: Do you really need a singleton?
7 // Singletons make it hard to determine the lifetime of an object, which can
8 // lead to buggy code and spurious crashes.
10 // Instead of adding another singleton into the mix, try to identify either:
11 // a) An existing singleton that can manage your object's lifetime
12 // b) Locations where you can deterministically create the object and pass
15 // If you absolutely need a singleton, please keep them as trivial as possible
16 // and ideally a leaf dependency. Singletons get problematic when they attempt
17 // to do too much in their destructor or have circular dependencies.
19 #ifndef BASE_MEMORY_SINGLETON_H_
20 #define BASE_MEMORY_SINGLETON_H_
22 #include "base/at_exit.h"
23 #include "base/atomicops.h"
24 #include "base/base_export.h"
25 #include "base/memory/aligned_memory.h"
26 #include "base/third_party/dynamic_annotations/dynamic_annotations.h"
27 #include "base/threading/thread_restrictions.h"
32 // Our AtomicWord doubles as a spinlock, where a value of
33 // kBeingCreatedMarker means the spinlock is being held for creation.
34 static const subtle::AtomicWord kBeingCreatedMarker
= 1;
36 // We pull out some of the functionality into a non-templated function, so that
37 // we can implement the more complicated pieces out of line in the .cc file.
38 BASE_EXPORT
subtle::AtomicWord
WaitForInstance(subtle::AtomicWord
* instance
);
40 } // namespace internal
43 // TODO(joth): Move more of this file into namespace base
45 // Default traits for Singleton<Type>. Calls operator new and operator delete on
46 // the object. Registers automatic deletion at process exit.
47 // Overload if you need arguments or another memory allocation function.
48 template<typename Type
>
49 struct DefaultSingletonTraits
{
50 // Allocates the object.
52 // The parenthesis is very important here; it forces POD type
57 // Destroys the object.
58 static void Delete(Type
* x
) {
62 // Set to true to automatically register deletion of the object on process
63 // exit. See below for the required call that makes this happen.
64 static const bool kRegisterAtExit
= true;
67 // Set to false to disallow access on a non-joinable thread. This is
68 // different from kRegisterAtExit because StaticMemorySingletonTraits allows
69 // access on non-joinable threads, and gracefully handles this.
70 static const bool kAllowedToAccessOnNonjoinableThread
= false;
75 // Alternate traits for use with the Singleton<Type>. Identical to
76 // DefaultSingletonTraits except that the Singleton will not be cleaned up
78 template<typename Type
>
79 struct LeakySingletonTraits
: public DefaultSingletonTraits
<Type
> {
80 static const bool kRegisterAtExit
= false;
82 static const bool kAllowedToAccessOnNonjoinableThread
= true;
87 // Alternate traits for use with the Singleton<Type>. Allocates memory
88 // for the singleton instance from a static buffer. The singleton will
89 // be cleaned up at exit, but can't be revived after destruction unless
90 // the Resurrect() method is called.
92 // This is useful for a certain category of things, notably logging and
93 // tracing, where the singleton instance is of a type carefully constructed to
94 // be safe to access post-destruction.
95 // In logging and tracing you'll typically get stray calls at odd times, like
96 // during static destruction, thread teardown and the like, and there's a
97 // termination race on the heap-based singleton - e.g. if one thread calls
98 // get(), but then another thread initiates AtExit processing, the first thread
99 // may call into an object residing in unallocated memory. If the instance is
100 // allocated from the data segment, then this is survivable.
102 // The destructor is to deallocate system resources, in this case to unregister
103 // a callback the system will invoke when logging levels change. Note that
104 // this is also used in e.g. Chrome Frame, where you have to allow for the
105 // possibility of loading briefly into someone else's process space, and
106 // so leaking is not an option, as that would sabotage the state of your host
107 // process once you've unloaded.
108 template <typename Type
>
109 struct StaticMemorySingletonTraits
{
110 // WARNING: User has to deal with get() in the singleton class
111 // this is traits for returning NULL.
113 // Only constructs once and returns pointer; otherwise returns NULL.
114 if (base::subtle::NoBarrier_AtomicExchange(&dead_
, 1))
117 return new(buffer_
.void_data()) Type();
120 static void Delete(Type
* p
) {
125 static const bool kRegisterAtExit
= true;
126 static const bool kAllowedToAccessOnNonjoinableThread
= true;
128 // Exposed for unittesting.
129 static void Resurrect() {
130 base::subtle::NoBarrier_Store(&dead_
, 0);
134 static base::AlignedMemory
<sizeof(Type
), ALIGNOF(Type
)> buffer_
;
135 // Signal the object was already deleted, so it is not revived.
136 static base::subtle::Atomic32 dead_
;
139 template <typename Type
> base::AlignedMemory
<sizeof(Type
), ALIGNOF(Type
)>
140 StaticMemorySingletonTraits
<Type
>::buffer_
;
141 template <typename Type
> base::subtle::Atomic32
142 StaticMemorySingletonTraits
<Type
>::dead_
= 0;
144 // The Singleton<Type, Traits, DifferentiatingType> class manages a single
145 // instance of Type which will be created on first use and will be destroyed at
146 // normal process exit). The Trait::Delete function will not be called on
147 // abnormal process exit.
149 // DifferentiatingType is used as a key to differentiate two different
150 // singletons having the same memory allocation functions but serving a
151 // different purpose. This is mainly used for Locks serving different purposes.
156 // template <typename T> struct DefaultSingletonTraits;
159 // static FooClass* GetInstance(); <-- See comment below on this.
160 // void Bar() { ... }
162 // FooClass() { ... }
163 // friend struct DefaultSingletonTraits<FooClass>;
165 // DISALLOW_COPY_AND_ASSIGN(FooClass);
168 // In your source file:
169 // #include "base/memory/singleton.h"
170 // FooClass* FooClass::GetInstance() {
171 // return Singleton<FooClass>::get();
174 // And to call methods on FooClass:
175 // FooClass::GetInstance()->Bar();
177 // NOTE: The method accessing Singleton<T>::get() has to be named as GetInstance
178 // and it is important that FooClass::GetInstance() is not inlined in the
179 // header. This makes sure that when source files from multiple targets include
180 // this header they don't end up with different copies of the inlined code
181 // creating multiple copies of the singleton.
183 // Singleton<> has no non-static members and doesn't need to actually be
186 // This class is itself thread-safe. The underlying Type must of course be
187 // thread-safe if you want to use it concurrently. Two parameters may be tuned
188 // depending on the user's requirements.
191 // RAE = kRegisterAtExit
193 // On every platform, if Traits::RAE is true, the singleton will be destroyed at
194 // process exit. More precisely it uses base::AtExitManager which requires an
195 // object of this type to be instantiated. AtExitManager mimics the semantics
196 // of atexit() such as LIFO order but under Windows is safer to call. For more
197 // information see at_exit.h.
199 // If Traits::RAE is false, the singleton will not be freed at process exit,
200 // thus the singleton will be leaked if it is ever accessed. Traits::RAE
201 // shouldn't be false unless absolutely necessary. Remember that the heap where
202 // the object is allocated may be destroyed by the CRT anyway.
205 // (a) Every call to get(), operator->() and operator*() incurs some overhead
206 // (16ns on my P4/2.8GHz) to check whether the object has already been
207 // initialized. You may wish to cache the result of get(); it will not
210 // (b) Your factory function must never throw an exception. This class is not
213 template <typename Type
,
214 typename Traits
= DefaultSingletonTraits
<Type
>,
215 typename DifferentiatingType
= Type
>
218 // Classes using the Singleton<T> pattern should declare a GetInstance()
219 // method and call Singleton::get() from within that.
220 friend Type
* Type::GetInstance();
222 // Allow TraceLog tests to test tracing after OnExit.
223 friend class DeleteTraceLogForTesting
;
225 // This class is safe to be constructed and copy-constructed since it has no
228 // Return a pointer to the one true instance of the class.
231 // Avoid making TLS lookup on release builds.
232 if (!Traits::kAllowedToAccessOnNonjoinableThread
)
233 base::ThreadRestrictions::AssertSingletonAllowed();
236 // The load has acquire memory ordering as the thread which reads the
237 // instance_ pointer must acquire visibility over the singleton data.
238 base::subtle::AtomicWord value
= base::subtle::Acquire_Load(&instance_
);
239 if (value
!= 0 && value
!= base::internal::kBeingCreatedMarker
) {
240 // See the corresponding HAPPENS_BEFORE below.
241 ANNOTATE_HAPPENS_AFTER(&instance_
);
242 return reinterpret_cast<Type
*>(value
);
245 // Object isn't created yet, maybe we will get to create it, let's try...
246 if (base::subtle::Acquire_CompareAndSwap(
247 &instance_
, 0, base::internal::kBeingCreatedMarker
) == 0) {
248 // instance_ was NULL and is now kBeingCreatedMarker. Only one thread
249 // will ever get here. Threads might be spinning on us, and they will
250 // stop right after we do this store.
251 Type
* newval
= Traits::New();
253 // This annotation helps race detectors recognize correct lock-less
254 // synchronization between different threads calling get().
255 // See the corresponding HAPPENS_AFTER below and above.
256 ANNOTATE_HAPPENS_BEFORE(&instance_
);
257 // Releases the visibility over instance_ to the readers.
258 base::subtle::Release_Store(
259 &instance_
, reinterpret_cast<base::subtle::AtomicWord
>(newval
));
261 if (newval
!= NULL
&& Traits::kRegisterAtExit
)
262 base::AtExitManager::RegisterCallback(OnExit
, NULL
);
267 // We hit a race. Wait for the other thread to complete it.
268 value
= base::internal::WaitForInstance(&instance_
);
270 // See the corresponding HAPPENS_BEFORE above.
271 ANNOTATE_HAPPENS_AFTER(&instance_
);
272 return reinterpret_cast<Type
*>(value
);
275 // Adapter function for use with AtExit(). This should be called single
276 // threaded, so don't use atomic operations.
277 // Calling OnExit while singleton is in use by other threads is a mistake.
278 static void OnExit(void* /*unused*/) {
279 // AtExit should only ever be register after the singleton instance was
280 // created. We should only ever get here with a valid instance_ pointer.
282 reinterpret_cast<Type
*>(base::subtle::NoBarrier_Load(&instance_
)));
285 static base::subtle::AtomicWord instance_
;
288 template <typename Type
, typename Traits
, typename DifferentiatingType
>
289 base::subtle::AtomicWord Singleton
<Type
, Traits
, DifferentiatingType
>::
292 #endif // BASE_MEMORY_SINGLETON_H_