michael@0: // Copyright (c) 2006-2008 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: #ifndef BASE_SINGLETON_H_ michael@0: #define BASE_SINGLETON_H_ michael@0: michael@0: #include "base/at_exit.h" michael@0: #include "base/atomicops.h" michael@0: #include "base/platform_thread.h" 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: 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: }; michael@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 usages: (none are preferred, they all result in the same code) michael@0: // 1. FooClass* ptr = Singleton::get(); michael@0: // ptr->Bar(); michael@0: // 2. Singleton()->Bar(); michael@0: // 3. Singleton::get()->Bar(); michael@0: // michael@0: // Singleton<> has no non-static members and doesn't need to actually be michael@0: // instantiated. It does no harm to instantiate it and use it as a class member michael@0: // or at global level since it is acting as a POD type. 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 instanciated. 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: // If you want to ensure that your class can only exist as a singleton, make michael@0: // its constructors private, and make DefaultSingletonTraits<> a friend: michael@0: // michael@0: // #include "base/singleton.h" michael@0: // class FooClass { michael@0: // public: michael@0: // void Bar() { ... } michael@0: // private: michael@0: // FooClass() { ... } michael@0: // friend struct DefaultSingletonTraits; michael@0: // michael@0: // DISALLOW_EVIL_CONSTRUCTORS(FooClass); michael@0: // }; 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: public: 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: // 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 base::subtle::AtomicWord kBeingCreatedMarker = 1; michael@0: michael@0: base::subtle::AtomicWord value = base::subtle::NoBarrier_Load(&instance_); michael@0: if (value != 0 && value != kBeingCreatedMarker) michael@0: return reinterpret_cast(value); 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(&instance_, michael@0: 0, michael@0: 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: base::subtle::Release_Store( michael@0: &instance_, reinterpret_cast(newval)); michael@0: michael@0: if (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. Another thread beat us and either: michael@0: // - Has the object in BeingCreated state michael@0: // - Already has the object created... michael@0: // We know value != NULL. It could be kBeingCreatedMarker, or a valid ptr. michael@0: // Unless your constructor can be very time consuming, it is very unlikely michael@0: // to hit this race. When it does, we just spin and yield the thread until michael@0: // the object has been created. michael@0: while (true) { michael@0: value = base::subtle::NoBarrier_Load(&instance_); michael@0: if (value != kBeingCreatedMarker) michael@0: break; michael@0: PlatformThread::YieldCurrentThread(); michael@0: } michael@0: michael@0: return reinterpret_cast(value); michael@0: } michael@0: michael@0: // Shortcuts. michael@0: Type& operator*() { michael@0: return *get(); michael@0: } michael@0: michael@0: Type* operator->() { michael@0: return get(); michael@0: } michael@0: michael@0: private: michael@0: // Adapter function for use with AtExit(). This should be called single michael@0: // threaded, but we might as well take the precautions anyway. 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(reinterpret_cast( michael@0: base::subtle::NoBarrier_AtomicExchange(&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_SINGLETON_H_