michael@0: // Copyright (c) 2011 The Chromium Authors. All rights reserved. michael@0: // Use of this source code is governed by a BSD-style license that can be michael@0: // found in the LICENSE file. michael@0: michael@0: // PLEASE READ: Do you really need a singleton? michael@0: // michael@0: // Singletons make it hard to determine the lifetime of an object, which can michael@0: // lead to buggy code and spurious crashes. michael@0: // michael@0: // Instead of adding another singleton into the mix, try to identify either: michael@0: // a) An existing singleton that can manage your object's lifetime michael@0: // b) Locations where you can deterministically create the object and pass michael@0: // into other objects michael@0: // michael@0: // If you absolutely need a singleton, please keep them as trivial as possible michael@0: // and ideally a leaf dependency. Singletons get problematic when they attempt michael@0: // to do too much in their destructor or have circular dependencies. michael@0: michael@0: #ifndef BASE_MEMORY_SINGLETON_H_ michael@0: #define BASE_MEMORY_SINGLETON_H_ michael@0: michael@0: #include "base/at_exit.h" michael@0: #include "base/atomicops.h" michael@0: #include "base/base_export.h" michael@0: #include "base/memory/aligned_memory.h" michael@0: #include "base/third_party/dynamic_annotations/dynamic_annotations.h" michael@0: #include "base/threading/thread_restrictions.h" michael@0: michael@0: namespace base { michael@0: namespace internal { michael@0: michael@0: // Our AtomicWord doubles as a spinlock, where a value of michael@0: // kBeingCreatedMarker means the spinlock is being held for creation. michael@0: static const subtle::AtomicWord kBeingCreatedMarker = 1; michael@0: michael@0: // We pull out some of the functionality into a non-templated function, so that michael@0: // we can implement the more complicated pieces out of line in the .cc file. michael@0: BASE_EXPORT subtle::AtomicWord WaitForInstance(subtle::AtomicWord* instance); michael@0: michael@0: } // namespace internal michael@0: } // namespace base michael@0: michael@0: // TODO(joth): Move more of this file into namespace base michael@0: michael@0: // Default traits for Singleton. Calls operator new and operator delete on michael@0: // the object. Registers automatic deletion at process exit. michael@0: // Overload if you need arguments or another memory allocation function. michael@0: template michael@0: struct DefaultSingletonTraits { michael@0: // Allocates the object. michael@0: static Type* New() { michael@0: // The parenthesis is very important here; it forces POD type michael@0: // initialization. michael@0: return new Type(); michael@0: } michael@0: michael@0: // Destroys the object. michael@0: static void Delete(Type* x) { michael@0: delete x; michael@0: } michael@0: michael@0: // Set to true to automatically register deletion of the object on process michael@0: // exit. See below for the required call that makes this happen. michael@0: static const bool kRegisterAtExit = true; michael@0: michael@0: // Set to false to disallow access on a non-joinable thread. This is michael@0: // different from kRegisterAtExit because StaticMemorySingletonTraits allows michael@0: // access on non-joinable threads, and gracefully handles this. michael@0: static const bool kAllowedToAccessOnNonjoinableThread = false; michael@0: }; michael@0: michael@0: michael@0: // Alternate traits for use with the Singleton. Identical to michael@0: // DefaultSingletonTraits except that the Singleton will not be cleaned up michael@0: // at exit. michael@0: template michael@0: struct LeakySingletonTraits : public DefaultSingletonTraits { michael@0: static const bool kRegisterAtExit = false; michael@0: static const bool kAllowedToAccessOnNonjoinableThread = true; michael@0: }; michael@0: michael@0: michael@0: // Alternate traits for use with the Singleton. Allocates memory michael@0: // for the singleton instance from a static buffer. The singleton will michael@0: // be cleaned up at exit, but can't be revived after destruction unless michael@0: // the Resurrect() method is called. michael@0: // michael@0: // This is useful for a certain category of things, notably logging and michael@0: // tracing, where the singleton instance is of a type carefully constructed to michael@0: // be safe to access post-destruction. michael@0: // In logging and tracing you'll typically get stray calls at odd times, like michael@0: // during static destruction, thread teardown and the like, and there's a michael@0: // termination race on the heap-based singleton - e.g. if one thread calls michael@0: // get(), but then another thread initiates AtExit processing, the first thread michael@0: // may call into an object residing in unallocated memory. If the instance is michael@0: // allocated from the data segment, then this is survivable. michael@0: // michael@0: // The destructor is to deallocate system resources, in this case to unregister michael@0: // a callback the system will invoke when logging levels change. Note that michael@0: // this is also used in e.g. Chrome Frame, where you have to allow for the michael@0: // possibility of loading briefly into someone else's process space, and michael@0: // so leaking is not an option, as that would sabotage the state of your host michael@0: // process once you've unloaded. michael@0: template michael@0: struct StaticMemorySingletonTraits { michael@0: // WARNING: User has to deal with get() in the singleton class michael@0: // this is traits for returning NULL. michael@0: static Type* New() { michael@0: // Only constructs once and returns pointer; otherwise returns NULL. michael@0: if (base::subtle::NoBarrier_AtomicExchange(&dead_, 1)) michael@0: return NULL; michael@0: michael@0: return new(buffer_.void_data()) Type(); michael@0: } michael@0: michael@0: static void Delete(Type* p) { michael@0: if (p != NULL) michael@0: p->Type::~Type(); michael@0: } michael@0: michael@0: static const bool kRegisterAtExit = true; michael@0: static const bool kAllowedToAccessOnNonjoinableThread = true; michael@0: michael@0: // Exposed for unittesting. michael@0: static void Resurrect() { michael@0: base::subtle::NoBarrier_Store(&dead_, 0); michael@0: } michael@0: michael@0: private: michael@0: static base::AlignedMemory buffer_; michael@0: // Signal the object was already deleted, so it is not revived. michael@0: static base::subtle::Atomic32 dead_; michael@0: }; michael@0: michael@0: template base::AlignedMemory michael@0: StaticMemorySingletonTraits::buffer_; michael@0: template base::subtle::Atomic32 michael@0: StaticMemorySingletonTraits::dead_ = 0; michael@0: michael@0: // The Singleton class manages a single michael@0: // instance of Type which will be created on first use and will be destroyed at michael@0: // normal process exit). The Trait::Delete function will not be called on michael@0: // abnormal process exit. michael@0: // michael@0: // DifferentiatingType is used as a key to differentiate two different michael@0: // singletons having the same memory allocation functions but serving a michael@0: // different purpose. This is mainly used for Locks serving different purposes. michael@0: // michael@0: // Example usage: michael@0: // michael@0: // In your header: michael@0: // template struct DefaultSingletonTraits; michael@0: // class FooClass { michael@0: // public: michael@0: // static FooClass* GetInstance(); <-- See comment below on this. michael@0: // void Bar() { ... } michael@0: // private: michael@0: // FooClass() { ... } michael@0: // friend struct DefaultSingletonTraits; michael@0: // michael@0: // DISALLOW_COPY_AND_ASSIGN(FooClass); michael@0: // }; michael@0: // michael@0: // In your source file: michael@0: // #include "base/memory/singleton.h" michael@0: // FooClass* FooClass::GetInstance() { michael@0: // return Singleton::get(); michael@0: // } michael@0: // michael@0: // And to call methods on FooClass: michael@0: // FooClass::GetInstance()->Bar(); michael@0: // michael@0: // NOTE: The method accessing Singleton::get() has to be named as GetInstance michael@0: // and it is important that FooClass::GetInstance() is not inlined in the michael@0: // header. This makes sure that when source files from multiple targets include michael@0: // this header they don't end up with different copies of the inlined code michael@0: // creating multiple copies of the singleton. michael@0: // michael@0: // Singleton<> has no non-static members and doesn't need to actually be michael@0: // instantiated. michael@0: // michael@0: // This class is itself thread-safe. The underlying Type must of course be michael@0: // thread-safe if you want to use it concurrently. Two parameters may be tuned michael@0: // depending on the user's requirements. michael@0: // michael@0: // Glossary: michael@0: // RAE = kRegisterAtExit michael@0: // michael@0: // On every platform, if Traits::RAE is true, the singleton will be destroyed at michael@0: // process exit. More precisely it uses base::AtExitManager which requires an michael@0: // object of this type to be instantiated. AtExitManager mimics the semantics michael@0: // of atexit() such as LIFO order but under Windows is safer to call. For more michael@0: // information see at_exit.h. michael@0: // michael@0: // If Traits::RAE is false, the singleton will not be freed at process exit, michael@0: // thus the singleton will be leaked if it is ever accessed. Traits::RAE michael@0: // shouldn't be false unless absolutely necessary. Remember that the heap where michael@0: // the object is allocated may be destroyed by the CRT anyway. michael@0: // michael@0: // Caveats: michael@0: // (a) Every call to get(), operator->() and operator*() incurs some overhead michael@0: // (16ns on my P4/2.8GHz) to check whether the object has already been michael@0: // initialized. You may wish to cache the result of get(); it will not michael@0: // change. michael@0: // michael@0: // (b) Your factory function must never throw an exception. This class is not michael@0: // exception-safe. michael@0: // michael@0: template , michael@0: typename DifferentiatingType = Type> michael@0: class Singleton { michael@0: private: michael@0: // Classes using the Singleton pattern should declare a GetInstance() michael@0: // method and call Singleton::get() from within that. michael@0: friend Type* Type::GetInstance(); michael@0: michael@0: // Allow TraceLog tests to test tracing after OnExit. michael@0: friend class DeleteTraceLogForTesting; michael@0: michael@0: // This class is safe to be constructed and copy-constructed since it has no michael@0: // member. michael@0: michael@0: // Return a pointer to the one true instance of the class. michael@0: static Type* get() { michael@0: #ifndef NDEBUG michael@0: // Avoid making TLS lookup on release builds. michael@0: if (!Traits::kAllowedToAccessOnNonjoinableThread) michael@0: base::ThreadRestrictions::AssertSingletonAllowed(); michael@0: #endif michael@0: michael@0: base::subtle::AtomicWord value = base::subtle::NoBarrier_Load(&instance_); michael@0: if (value != 0 && value != base::internal::kBeingCreatedMarker) { michael@0: // See the corresponding HAPPENS_BEFORE below. michael@0: ANNOTATE_HAPPENS_AFTER(&instance_); michael@0: return reinterpret_cast(value); michael@0: } michael@0: michael@0: // Object isn't created yet, maybe we will get to create it, let's try... michael@0: if (base::subtle::Acquire_CompareAndSwap( michael@0: &instance_, 0, base::internal::kBeingCreatedMarker) == 0) { michael@0: // instance_ was NULL and is now kBeingCreatedMarker. Only one thread michael@0: // will ever get here. Threads might be spinning on us, and they will michael@0: // stop right after we do this store. michael@0: Type* newval = Traits::New(); michael@0: michael@0: // This annotation helps race detectors recognize correct lock-less michael@0: // synchronization between different threads calling get(). michael@0: // See the corresponding HAPPENS_AFTER below and above. michael@0: ANNOTATE_HAPPENS_BEFORE(&instance_); michael@0: base::subtle::Release_Store( michael@0: &instance_, reinterpret_cast(newval)); michael@0: michael@0: if (newval != NULL && Traits::kRegisterAtExit) michael@0: base::AtExitManager::RegisterCallback(OnExit, NULL); michael@0: michael@0: return newval; michael@0: } michael@0: michael@0: // We hit a race. Wait for the other thread to complete it. michael@0: value = base::internal::WaitForInstance(&instance_); michael@0: michael@0: // See the corresponding HAPPENS_BEFORE above. michael@0: ANNOTATE_HAPPENS_AFTER(&instance_); michael@0: return reinterpret_cast(value); michael@0: } michael@0: michael@0: // Adapter function for use with AtExit(). This should be called single michael@0: // threaded, so don't use atomic operations. michael@0: // Calling OnExit while singleton is in use by other threads is a mistake. michael@0: static void OnExit(void* /*unused*/) { michael@0: // AtExit should only ever be register after the singleton instance was michael@0: // created. We should only ever get here with a valid instance_ pointer. michael@0: Traits::Delete( michael@0: reinterpret_cast(base::subtle::NoBarrier_Load(&instance_))); michael@0: instance_ = 0; michael@0: } michael@0: static base::subtle::AtomicWord instance_; michael@0: }; michael@0: michael@0: template michael@0: base::subtle::AtomicWord Singleton:: michael@0: instance_ = 0; michael@0: michael@0: #endif // BASE_MEMORY_SINGLETON_H_