X-Git-Url: http://plrg.eecs.uci.edu/git/?a=blobdiff_plain;f=folly%2FSingleton.h;h=a08954fc222a02c4e97be02c133bbfdf78ca6683;hb=d0956208d06806377b05e4daef5450603ce4ad63;hp=1eb52f64068096c225852d9a75137161de3ced7c;hpb=4092256e604e1cd140b991edeb0eb86c36ded56e;p=folly.git diff --git a/folly/Singleton.h b/folly/Singleton.h index 1eb52f64..a08954fc 100644 --- a/folly/Singleton.h +++ b/folly/Singleton.h @@ -1,5 +1,5 @@ /* - * Copyright 2016 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 {}; @@ -111,16 +121,16 @@ // should call reenableInstances. #pragma once -#include -#include + #include #include -#include #include #include #include #include #include +#include +#include #include #include @@ -196,14 +206,7 @@ class TypeDescriptor { return *this; } - std::string name() const { - auto ret = demangle(ti_.name()); - if (tag_ti_ != std::type_index(typeid(DefaultTag))) { - ret += "/"; - ret += demangle(tag_ti_.name()); - } - return ret.toStdString(); - } + std::string name() const; friend class TypeDescriptorHasher; @@ -223,6 +226,59 @@ class TypeDescriptorHasher { } }; +[[noreturn]] void singletonWarnLeakyDoubleRegistrationAndAbort( + const TypeDescriptor& type); + +[[noreturn]] void singletonWarnLeakyInstantiatingNotRegisteredAndAbort( + const TypeDescriptor& type); + +[[noreturn]] void singletonWarnRegisterMockEarlyAndAbort( + const TypeDescriptor& type); + +void singletonWarnDestroyInstanceLeak( + const TypeDescriptor& type, + const void* ptr); + +[[noreturn]] void singletonWarnCreateCircularDependencyAndAbort( + const TypeDescriptor& type); + +[[noreturn]] void singletonWarnCreateUnregisteredAndAbort( + const TypeDescriptor& type); + +[[noreturn]] void singletonWarnCreateBeforeRegistrationCompleteAndAbort( + const TypeDescriptor& type); + +void singletonPrintDestructionStackTrace(const TypeDescriptor& type); + +[[noreturn]] void singletonThrowNullCreator(const std::type_info& type); + +[[noreturn]] void singletonThrowGetInvokedAfterDestruction( + const TypeDescriptor& type); + +struct SingletonVaultState { + // The two stages of life for a vault, as mentioned in the class comment. + enum class Type { + Running, + Quiescing, + }; + + Type state{Type::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 check( + Type expected, + const char* msg = "Unexpected singleton state change") const { + if (expected != state) { + throwUnexpectedState(msg); + } + } + + [[noreturn]] static void throwUnexpectedState(const char* msg); +}; + // This interface is used by SingletonVault to interact with SingletonHolders. // Having a non-template interface allows SingletonVault to keep a list of all // SingletonHolders. @@ -263,11 +319,11 @@ struct SingletonHolder : public SingletonHolderBase { void registerSingleton(CreateFunc c, TeardownFunc t); void registerSingletonMock(CreateFunc c, TeardownFunc t); - virtual bool hasLiveInstance() override; - virtual void createInstance() override; - virtual bool creationStarted() override; - virtual void preDestroyInstance(ReadMostlyMainPtrDeleter<>&) 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); @@ -318,7 +374,7 @@ struct SingletonHolder : public SingletonHolderBase { SingletonHolder(SingletonHolder&&) = delete; }; -} +} // namespace detail class SingletonVault { public: @@ -348,7 +404,9 @@ class SingletonVault { } }; - explicit SingletonVault(Type type = Type::Strict) : type_(type) {} + static Type defaultVaultType(); + + explicit SingletonVault(Type type = defaultVaultType()) : type_(type) {} // Destructor is only called by unit tests to check destroyInstances. ~SingletonVault(); @@ -393,10 +451,10 @@ class SingletonVault { * * Sample usage: * - * wangle::IOThreadPoolExecutor executor(max_concurrency_level); + * folly::IOThreadPoolExecutor executor(max_concurrency_level); * folly::Baton<> done; * doEagerInitVia(executor, &done); - * done.wait(); // or 'timed_wait', or spin with 'try_wait' + * done.wait(); // or 'try_wait_for', etc. * */ void doEagerInitVia(Executor& exe, folly::Baton<>* done = nullptr); @@ -463,29 +521,6 @@ class SingletonVault { template friend struct detail::SingletonHolder; - // The two stages of life for a vault, as mentioned in the class comment. - enum class SingletonVaultState { - Running, - 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). - - static void stateCheck( - SingletonVaultState expected, - const State& state, - const char* msg = "Unexpected singleton state change") { - if (expected != state.state) { - throw std::logic_error(msg); - } - } - // This method only matters if registrationComplete() is never called. // Otherwise destroyInstances is scheduled to be executed atexit. // @@ -502,15 +537,15 @@ class SingletonVault { typedef std::unordered_map SingletonMap; - folly::Synchronized singletons_; - folly::Synchronized> + Synchronized singletons_; + Synchronized> eagerInitSingletons_; - folly::Synchronized> creationOrder_; + 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_; + Synchronized state_; Type type_; }; @@ -520,9 +555,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; @@ -563,8 +599,7 @@ class Singleton { explicit Singleton(typename Singleton::CreateFunc c, typename Singleton::TeardownFunc t = nullptr) { if (c == nullptr) { - throw std::logic_error( - "nullptr_t should be passed if you want T to be default constructed"); + detail::singletonThrowNullCreator(typeid(T)); } auto vault = SingletonVault::singleton(); @@ -612,8 +647,7 @@ class Singleton { static void make_mock(CreateFunc c, typename Singleton::TeardownFunc t = nullptr) { if (c == nullptr) { - throw std::logic_error( - "nullptr_t should be passed if you want T to be default constructed"); + detail::singletonThrowNullCreator(typeid(T)); } auto& entry = getEntry(); @@ -647,9 +681,7 @@ class LeakySingleton { 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() + ">"; + detail::singletonWarnLeakyDoubleRegistrationAndAbort(entry.type_); } entry.createFunc = createFunc; entry.state = State::Dead; @@ -657,6 +689,20 @@ class LeakySingleton { 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) { + if (createFunc == nullptr) { + detail::singletonThrowNullCreator(typeid(T)); + } + + auto& entry = entryInstance(); + entry.createFunc = createFunc; + entry.state = State::Dead; + } + private: enum class State { NotRegistered, Dead, Living }; @@ -695,17 +741,13 @@ class LeakySingleton { } 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)"); + detail::singletonWarnLeakyInstantiatingNotRegisteredAndAbort(entry.type_); } entry.ptr = entry.createFunc(); entry.state = State::Living; } }; -} +} // namespace folly #include