| // Copyright (c) 2009 The Chromium Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| #ifndef BASE_SINGLETON_H_ |
| #define BASE_SINGLETON_H_ |
| |
| #include "base/at_exit.h" |
| #include "base/atomicops.h" |
| #include "base/dynamic_annotations.h" |
| #include "base/platform_thread.h" |
| |
| // Default traits for Singleton<Type>. Calls operator new and operator delete on |
| // the object. Registers automatic deletion at process exit. |
| // Overload if you need arguments or another memory allocation function. |
| template<typename Type> |
| struct DefaultSingletonTraits { |
| // Allocates the object. |
| static Type* New() { |
| // The parenthesis is very important here; it forces POD type |
| // initialization. |
| return new Type(); |
| } |
| |
| // Destroys the object. |
| static void Delete(Type* x) { |
| delete x; |
| } |
| |
| // Set to true to automatically register deletion of the object on process |
| // exit. See below for the required call that makes this happen. |
| static const bool kRegisterAtExit = true; |
| }; |
| |
| |
| // Alternate traits for use with the Singleton<Type>. Identical to |
| // DefaultSingletonTraits except that the Singleton will not be cleaned up |
| // at exit. |
| template<typename Type> |
| struct LeakySingletonTraits : public DefaultSingletonTraits<Type> { |
| static const bool kRegisterAtExit = false; |
| }; |
| |
| |
| // The Singleton<Type, Traits, DifferentiatingType> class manages a single |
| // instance of Type which will be created on first use and will be destroyed at |
| // normal process exit). The Trait::Delete function will not be called on |
| // abnormal process exit. |
| // |
| // DifferentiatingType is used as a key to differentiate two different |
| // singletons having the same memory allocation functions but serving a |
| // different purpose. This is mainly used for Locks serving different purposes. |
| // |
| // Example usages: (none are preferred, they all result in the same code) |
| // 1. FooClass* ptr = Singleton<FooClass>::get(); |
| // ptr->Bar(); |
| // 2. Singleton<FooClass>()->Bar(); |
| // 3. Singleton<FooClass>::get()->Bar(); |
| // |
| // Singleton<> has no non-static members and doesn't need to actually be |
| // instantiated. It does no harm to instantiate it and use it as a class member |
| // or at global level since it is acting as a POD type. |
| // |
| // This class is itself thread-safe. The underlying Type must of course be |
| // thread-safe if you want to use it concurrently. Two parameters may be tuned |
| // depending on the user's requirements. |
| // |
| // Glossary: |
| // RAE = kRegisterAtExit |
| // |
| // On every platform, if Traits::RAE is true, the singleton will be destroyed at |
| // process exit. More precisely it uses base::AtExitManager which requires an |
| // object of this type to be instantiated. AtExitManager mimics the semantics |
| // of atexit() such as LIFO order but under Windows is safer to call. For more |
| // information see at_exit.h. |
| // |
| // If Traits::RAE is false, the singleton will not be freed at process exit, |
| // thus the singleton will be leaked if it is ever accessed. Traits::RAE |
| // shouldn't be false unless absolutely necessary. Remember that the heap where |
| // the object is allocated may be destroyed by the CRT anyway. |
| // |
| // If you want to ensure that your class can only exist as a singleton, make |
| // its constructors private, and make DefaultSingletonTraits<> a friend: |
| // |
| // #include "base/singleton.h" |
| // class FooClass { |
| // public: |
| // void Bar() { ... } |
| // private: |
| // FooClass() { ... } |
| // friend struct DefaultSingletonTraits<FooClass>; |
| // |
| // DISALLOW_EVIL_CONSTRUCTORS(FooClass); |
| // }; |
| // |
| // Caveats: |
| // (a) Every call to get(), operator->() and operator*() incurs some overhead |
| // (16ns on my P4/2.8GHz) to check whether the object has already been |
| // initialized. You may wish to cache the result of get(); it will not |
| // change. |
| // |
| // (b) Your factory function must never throw an exception. This class is not |
| // exception-safe. |
| // |
| template <typename Type, |
| typename Traits = DefaultSingletonTraits<Type>, |
| typename DifferentiatingType = Type> |
| class Singleton { |
| public: |
| // This class is safe to be constructed and copy-constructed since it has no |
| // member. |
| |
| // Return a pointer to the one true instance of the class. |
| static Type* get() { |
| // Our AtomicWord doubles as a spinlock, where a value of |
| // kBeingCreatedMarker means the spinlock is being held for creation. |
| static const base::subtle::AtomicWord kBeingCreatedMarker = 1; |
| |
| base::subtle::AtomicWord value = base::subtle::NoBarrier_Load(&instance_); |
| if (value != 0 && value != kBeingCreatedMarker) { |
| // See the corresponding HAPPENS_BEFORE below. |
| ANNOTATE_HAPPENS_AFTER(&instance_); |
| return reinterpret_cast<Type*>(value); |
| } |
| |
| // Object isn't created yet, maybe we will get to create it, let's try... |
| if (base::subtle::Acquire_CompareAndSwap(&instance_, |
| 0, |
| kBeingCreatedMarker) == 0) { |
| // instance_ was NULL and is now kBeingCreatedMarker. Only one thread |
| // will ever get here. Threads might be spinning on us, and they will |
| // stop right after we do this store. |
| Type* newval = Traits::New(); |
| |
| // This annotation helps race detectors recognize correct lock-less |
| // synchronization between different threads calling get(). |
| // See the corresponding HAPPENS_AFTER below and above. |
| ANNOTATE_HAPPENS_BEFORE(&instance_); |
| base::subtle::Release_Store( |
| &instance_, reinterpret_cast<base::subtle::AtomicWord>(newval)); |
| |
| if (Traits::kRegisterAtExit) |
| base::AtExitManager::RegisterCallback(OnExit, NULL); |
| |
| return newval; |
| } |
| |
| // We hit a race. Another thread beat us and either: |
| // - Has the object in BeingCreated state |
| // - Already has the object created... |
| // We know value != NULL. It could be kBeingCreatedMarker, or a valid ptr. |
| // Unless your constructor can be very time consuming, it is very unlikely |
| // to hit this race. When it does, we just spin and yield the thread until |
| // the object has been created. |
| while (true) { |
| value = base::subtle::NoBarrier_Load(&instance_); |
| if (value != kBeingCreatedMarker) |
| break; |
| PlatformThread::YieldCurrentThread(); |
| } |
| |
| // See the corresponding HAPPENS_BEFORE above. |
| ANNOTATE_HAPPENS_AFTER(&instance_); |
| return reinterpret_cast<Type*>(value); |
| } |
| |
| // Shortcuts. |
| Type& operator*() { |
| return *get(); |
| } |
| |
| Type* operator->() { |
| return get(); |
| } |
| |
| private: |
| // Adapter function for use with AtExit(). This should be called single |
| // threaded, but we might as well take the precautions anyway. |
| static void OnExit(void* unused) { |
| // AtExit should only ever be register after the singleton instance was |
| // created. We should only ever get here with a valid instance_ pointer. |
| Traits::Delete(reinterpret_cast<Type*>( |
| base::subtle::NoBarrier_AtomicExchange(&instance_, 0))); |
| } |
| static base::subtle::AtomicWord instance_; |
| }; |
| |
| template <typename Type, typename Traits, typename DifferentiatingType> |
| base::subtle::AtomicWord Singleton<Type, Traits, DifferentiatingType>:: |
| instance_ = 0; |
| |
| #endif // BASE_SINGLETON_H_ |