X-Git-Url: http://plrg.eecs.uci.edu/git/?p=folly.git;a=blobdiff_plain;f=folly%2FSingleton.h;h=01a9d5d12448a4c097664e3d4c7243f47eda87b6;hp=ac5b8328d3e28bda1868682c35482a82d72f4465;hb=192d78d40551ec5d9aade5ca72dd6e33ad700a2b;hpb=f54fbf88038aacc4bcc0f3bf98995375fddcde78 diff --git a/folly/Singleton.h b/folly/Singleton.h index ac5b8328..01a9d5d1 100644 --- a/folly/Singleton.h +++ b/folly/Singleton.h @@ -1,5 +1,5 @@ /* - * Copyright 2015 Facebook, Inc. + * Copyright 2017 Facebook, Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -17,29 +17,36 @@ // SingletonVault - a library to manage the creation and destruction // of interdependent singletons. // -// Basic usage of this class is very simple; suppose you have a class +// Recommended usage of this class: suppose you have a class // called MyExpensiveService, and you only want to construct one (ie, // it's a singleton), but you only want to construct it if it is used. // // In your .h file: -// class MyExpensiveService { ... }; +// class MyExpensiveService { +// // Caution - may return a null ptr during startup and shutdown. +// static std::shared_ptr getInstance(); +// .... +// }; // // In your .cpp file: -// namespace { folly::Singleton the_singleton; } +// namespace { struct PrivateTag {}; } +// static folly::Singleton the_singleton; +// std::shared_ptr MyExpensiveService::getInstance() { +// return the_singleton.try_get(); +// } // -// Code can access it via: +// Code in other modules can access it via: // -// MyExpensiveService* instance = Singleton::get(); -// or -// std::weak_ptr instance = -// Singleton::get_weak(); +// auto instance = MyExpensiveService::getInstance(); // -// You also can directly access it by the variable defining the -// singleton rather than via get(), and even treat that variable like -// a smart pointer (dereferencing it or using the -> operator). +// Advanced usage and notes: // -// Please note, however, that all non-weak_ptr interfaces are -// inherently subject to races with destruction. Use responsibly. +// You can also access a singleton instance with +// `Singleton::try_get()`. We recommend +// that you prefer the form `the_singleton.try_get()` because it ensures that +// `the_singleton` is used and cannot be garbage-collected during linking: this +// is necessary because the constructor of `the_singleton` is what registers it +// to the SingletonVault. // // The singleton will be created on demand. If the constructor for // MyExpensiveService actually makes use of *another* Singleton, then @@ -48,7 +55,10 @@ // circular dependency, a runtime error will occur. // // You can have multiple singletons of the same underlying type, but -// each must be given a unique tag. If no tag is specified - default tag is used +// each must be given a unique tag. If no tag is specified a default tag is +// used. We recommend that you use a tag from an anonymous namespace private to +// your implementation file, as this ensures that the singleton is only +// available via your interface and not also through Singleton::try_get() // // namespace { // struct Tag1 {}; @@ -71,6 +81,15 @@ // Where create and destroy are functions, Singleton::CreateFunc // Singleton::TeardownFunc. // +// For example, if you need to pass arguments to your class's constructor: +// class X { +// public: +// X(int a1, std::string a2); +// // ... +// } +// Make your singleton like this: +// folly::Singleton singleton_x([]() { return new X(42, "foo"); }); +// // The above examples detail a situation where an expensive singleton is loaded // on-demand (thus only if needed). However if there is an expensive singleton // that will likely be needed, and initialization takes a potentially long time, @@ -103,25 +122,29 @@ #pragma once #include +#include #include -#include +#include #include #include -#include -#include -#include +#include +#include +#include +#include #include -#include -#include -#include +#include #include +#include +#include +#include #include +#include +#include +#include #include #include -#include -#include -#include +#include #include @@ -215,16 +238,20 @@ class TypeDescriptorHasher { // SingletonHolders. class SingletonHolderBase { public: + explicit SingletonHolderBase(TypeDescriptor typeDesc) : type_(typeDesc) {} virtual ~SingletonHolderBase() = default; - virtual TypeDescriptor type() = 0; + TypeDescriptor type() const { + return type_; + } virtual bool hasLiveInstance() = 0; virtual void createInstance() = 0; virtual bool creationStarted() = 0; + virtual void preDestroyInstance(ReadMostlyMainPtrDeleter<>&) = 0; virtual void destroyInstance() = 0; - protected: - static constexpr std::chrono::seconds kDestroyWaitTime{5}; + private: + TypeDescriptor type_; }; // An actual instance of a singleton, tracking the instance itself, @@ -241,14 +268,16 @@ struct SingletonHolder : public SingletonHolderBase { inline T* get(); inline std::weak_ptr get_weak(); + inline std::shared_ptr try_get(); + inline folly::ReadMostlySharedPtr try_get_fast(); void registerSingleton(CreateFunc c, TeardownFunc t); void registerSingletonMock(CreateFunc c, TeardownFunc t); - virtual TypeDescriptor type() override; - virtual bool hasLiveInstance() override; - virtual void createInstance() override; - virtual bool creationStarted() override; - virtual void destroyInstance() override; + bool hasLiveInstance() override; + void createInstance() override; + bool creationStarted() override; + void preDestroyInstance(ReadMostlyMainPtrDeleter<>&) override; + void destroyInstance() override; private: SingletonHolder(TypeDescriptor type, SingletonVault& vault); @@ -259,7 +288,6 @@ struct SingletonHolder : public SingletonHolderBase { Living, }; - TypeDescriptor type_; SingletonVault& vault_; // mutex protects the entire entry during construction/destruction @@ -274,14 +302,18 @@ struct SingletonHolder : public SingletonHolderBase { // The singleton itself and related functions. - // holds a shared_ptr to singleton instance, set when state is changed from - // Dead to Living. Reset when state is changed from Living to Dead. - std::shared_ptr instance_; + // holds a ReadMostlyMainPtr to singleton instance, set when state is changed + // from Dead to Living. Reset when state is changed from Living to Dead. + folly::ReadMostlyMainPtr instance_; + // used to release all ReadMostlyMainPtrs at once + folly::ReadMostlySharedPtr instance_copy_; // weak_ptr to the singleton instance, set when state is changed from Dead // to Living. We never write to this object after initialization, so it is // safe to read it from different threads w/o synchronization if we know // that state is set to Living std::weak_ptr instance_weak_; + // Fast equivalent of instance_weak_ + folly::ReadMostlyWeakPtr instance_weak_fast_; // Time we wait on destroy_baton after releasing Singleton shared_ptr. std::shared_ptr> destroy_baton_; T* instance_ptr_ = nullptr; @@ -296,7 +328,7 @@ struct SingletonHolder : public SingletonHolderBase { SingletonHolder(SingletonHolder&&) = delete; }; -} +} // namespace detail class SingletonVault { public: @@ -305,7 +337,30 @@ class SingletonVault { Relaxed, // Singletons can be created before registrationComplete() }; - explicit SingletonVault(Type type = Type::Relaxed) : type_(type) {} + /** + * Clears all singletons in the given vault at ctor and dtor times. + * Useful for unit-tests that need to clear the world. + * + * This need can arise when a unit-test needs to swap out an object used by a + * singleton for a test-double, but the singleton needing its dependency to be + * swapped has a type or a tag local to some other translation unit and + * unavailable in the current translation unit. + * + * Other, better approaches to this need are "plz 2 refactor" .... + */ + struct ScopedExpunger { + SingletonVault* vault; + explicit ScopedExpunger(SingletonVault* v) : vault(v) { expunge(); } + ~ScopedExpunger() { expunge(); } + void expunge() { + vault->destroyInstances(); + vault->reenableInstances(); + } + }; + + static Type defaultVaultType(); + + explicit SingletonVault(Type type = defaultVaultType()) : type_(type) {} // Destructor is only called by unit tests to check destroyInstances. ~SingletonVault(); @@ -340,8 +395,23 @@ class SingletonVault { /** * Schedule eager singletons' initializations through the given executor. + * If baton ptr is not null, its `post` method is called after all + * early initialization has completed. + * + * If exceptions are thrown during initialization, this method will still + * `post` the baton to indicate completion. The exception will not propagate + * and future attempts to `try_get` or `get_weak` the failed singleton will + * retry initialization. + * + * Sample usage: + * + * folly::IOThreadPoolExecutor executor(max_concurrency_level); + * folly::Baton<> done; + * doEagerInitVia(executor, &done); + * done.wait(); // or 'timed_wait', or spin with 'try_wait' + * */ - void doEagerInitVia(Executor* exe); + void doEagerInitVia(Executor& exe, folly::Baton<>* done = nullptr); // Destroy all singletons; when complete, the vault can't create // singletons once again until reenableInstances() is called. @@ -352,16 +422,20 @@ class SingletonVault { // For testing; how many registered and living singletons we have. size_t registeredSingletonCount() const { - RWSpinLock::ReadHolder rh(&mutex_); - - return singletons_.size(); + return singletons_.rlock()->size(); } + /** + * Flips to true if eager initialization was used, and has completed. + * Never set to true if "doEagerInit()" or "doEagerInitVia" never called. + */ + bool eagerInitComplete() const; + size_t livingSingletonCount() const { - RWSpinLock::ReadHolder rh(&mutex_); + auto singletons = singletons_.rlock(); size_t ret = 0; - for (const auto& p : singletons_) { + for (const auto& p : *singletons) { if (p.second->hasLiveInstance()) { ++ret; } @@ -380,15 +454,21 @@ class SingletonVault { // tests only. template static SingletonVault* singleton() { - static SingletonVault* vault = new SingletonVault(); + /* library-local */ static auto vault = + detail::createGlobal(); return vault; } typedef std::string(*StackTraceGetterPtr)(); static std::atomic& stackTraceGetter() { - static std::atomic stackTraceGetterPtr; - return stackTraceGetterPtr; + /* library-local */ static auto stackTraceGetterPtr = detail:: + createGlobal, SingletonVault>(); + return *stackTraceGetterPtr; + } + + void setType(Type type) { + type_ = type; } private: @@ -401,13 +481,20 @@ class SingletonVault { Quiescing, }; + struct State { + SingletonVaultState state{SingletonVaultState::Running}; + bool registrationComplete{false}; + }; + // Each singleton in the vault can be in two states: dead // (registered but never created), living (CreateFunc returned an instance). - void stateCheck(SingletonVaultState expected, - const char* msg="Unexpected singleton state change") { - if (expected != state_) { - throw std::logic_error(msg); + static void stateCheck( + SingletonVaultState expected, + const State& state, + const char* msg = "Unexpected singleton state change") { + if (expected != state.state) { + throw std::logic_error(msg); } } @@ -427,15 +514,17 @@ class SingletonVault { typedef std::unordered_map SingletonMap; + folly::Synchronized singletons_; + folly::Synchronized> + eagerInitSingletons_; + folly::Synchronized> creationOrder_; + + // Using SharedMutexReadPriority is important here, because we want to make + // sure we don't block nested singleton creation happening concurrently with + // destroyInstances(). + folly::Synchronized state_; - mutable folly::RWSpinLock mutex_; - SingletonMap singletons_; - std::unordered_set eagerInitSingletons_; - std::vector creation_order_; - SingletonVaultState state_{SingletonVaultState::Running}; - bool registrationComplete_{false}; - folly::RWSpinLock stateMutex_; - Type type_{Type::Relaxed}; + Type type_; }; // This is the wrapper class that most users actually interact with. @@ -443,9 +532,10 @@ class SingletonVault { // singletons. Create instances of this class in the global scope of // type Singleton to register your singleton for later access via // Singleton::try_get(). -template +template < + typename T, + typename Tag = detail::DefaultTag, + typename VaultTag = detail::DefaultTag /* for testing */> class Singleton { public: typedef std::function CreateFunc; @@ -454,38 +544,35 @@ class Singleton { // Generally your program life cycle should be fine with calling // get() repeatedly rather than saving the reference, and then not // call get() during process shutdown. - static T* get() __attribute__ ((__deprecated__("Replaced by try_get"))) { - return getEntry().get(); - } + FOLLY_DEPRECATED("Replaced by try_get") + static T* get() { return getEntry().get(); } // If, however, you do need to hold a reference to the specific // singleton, you can try to do so with a weak_ptr. Avoid this when // possible but the inability to lock the weak pointer can be a // signal that the vault has been destroyed. - static std::weak_ptr get_weak() { - return getEntry().get_weak(); - } + FOLLY_DEPRECATED("Replaced by try_get") + static std::weak_ptr get_weak() { return getEntry().get_weak(); } // Preferred alternative to get_weak, it returns shared_ptr that can be // stored; a singleton won't be destroyed unless shared_ptr is destroyed. // Avoid holding these shared_ptrs beyond the scope of a function; // don't put them in member variables, always use try_get() instead + // + // try_get() can return nullptr if the singleton was destroyed, caller is + // responsible for handling nullptr return static std::shared_ptr try_get() { - auto ret = get_weak().lock(); - if (!ret) { - LOG(DFATAL) << - "folly::Singleton<" << getEntry().type().name() << - ">::get_weak() called on destructed singleton; " - "returning nullptr, possible segfault coming"; - } - return ret; + return getEntry().try_get(); } - explicit Singleton(std::nullptr_t _ = nullptr, - typename Singleton::TeardownFunc t = nullptr) : - Singleton ([]() { return new T; }, std::move(t)) { + static folly::ReadMostlySharedPtr try_get_fast() { + return getEntry().try_get_fast(); } + explicit Singleton(std::nullptr_t /* _ */ = nullptr, + typename Singleton::TeardownFunc t = nullptr) + : Singleton([]() { return new T; }, std::move(t)) {} + explicit Singleton(typename Singleton::CreateFunc c, typename Singleton::TeardownFunc t = nullptr) { if (c == nullptr) { @@ -530,7 +617,7 @@ class Singleton { * the injection. The returned mock singleton is functionality identical to * regular singletons. */ - static void make_mock(std::nullptr_t c = nullptr, + static void make_mock(std::nullptr_t /* c */ = nullptr, typename Singleton::TeardownFunc t = nullptr) { make_mock([]() { return new T; }, t); } @@ -563,6 +650,90 @@ class Singleton { } }; -} +template +class LeakySingleton { + public: + using CreateFunc = std::function; + + LeakySingleton() : LeakySingleton([] { return new T(); }) {} + + explicit LeakySingleton(CreateFunc createFunc) { + auto& entry = entryInstance(); + if (entry.state != State::NotRegistered) { + LOG(FATAL) << "Double registration of singletons of the same " + << "underlying type; check for multiple definitions " + << "of type folly::LeakySingleton<" + entry.type_.name() + ">"; + } + entry.createFunc = createFunc; + entry.state = State::Dead; + } + + static T& get() { return instance(); } + + static void make_mock(std::nullptr_t /* c */ = nullptr) { + make_mock([]() { return new T; }); + } + + static void make_mock(CreateFunc createFunc) { + auto& entry = entryInstance(); + if (createFunc == nullptr) { + throw std::logic_error( + "nullptr_t should be passed if you want T to be default constructed"); + } + + entry.createFunc = createFunc; + entry.state = State::Dead; + } + + private: + enum class State { NotRegistered, Dead, Living }; + + struct Entry { + Entry() {} + Entry(const Entry&) = delete; + Entry& operator=(const Entry&) = delete; + + std::atomic state{State::NotRegistered}; + T* ptr{nullptr}; + CreateFunc createFunc; + std::mutex mutex; + detail::TypeDescriptor type_{typeid(T), typeid(Tag)}; + }; + + static Entry& entryInstance() { + /* library-local */ static auto entry = detail::createGlobal(); + return *entry; + } + + static T& instance() { + auto& entry = entryInstance(); + if (UNLIKELY(entry.state != State::Living)) { + createInstance(); + } + + return *entry.ptr; + } + + static void createInstance() { + auto& entry = entryInstance(); + + std::lock_guard lg(entry.mutex); + if (entry.state == State::Living) { + return; + } + + if (entry.state == State::NotRegistered) { + auto ptr = SingletonVault::stackTraceGetter().load(); + LOG(FATAL) << "Creating instance for unregistered singleton: " + << entry.type_.name() << "\n" + << "Stacktrace:" + << "\n" << (ptr ? (*ptr)() : "(not available)"); + } + + entry.ptr = entry.createFunc(); + entry.state = State::Living; + } +}; +} // namespace folly #include