diff options
Diffstat (limited to 'indra/llcommon/llsingleton.h')
| -rw-r--r-- | indra/llcommon/llsingleton.h | 409 |
1 files changed, 340 insertions, 69 deletions
diff --git a/indra/llcommon/llsingleton.h b/indra/llcommon/llsingleton.h index 859e271e26..0da6d548ab 100644 --- a/indra/llcommon/llsingleton.h +++ b/indra/llcommon/llsingleton.h @@ -31,6 +31,18 @@ #include <vector> #include <typeinfo> +#if LL_WINDOWS +#pragma warning (push) +#pragma warning (disable:4265) +#endif +// warning C4265: 'std::_Pad' : class has virtual functions, but destructor is not virtual + +#include <mutex> + +#if LL_WINDOWS +#pragma warning (pop) +#endif + class LLSingletonBase: private boost::noncopyable { public: @@ -43,7 +55,6 @@ private: // This, on the other hand, is a stack whose top indicates the LLSingleton // currently being initialized. static list_t& get_initializing(); - static list_t& get_initializing_from(MasterList*); // Produce a vector<LLSingletonBase*> of master list, in dependency order. typedef std::vector<LLSingletonBase*> vec_t; static vec_t dep_sort(); @@ -57,10 +68,11 @@ protected: typedef enum e_init_state { UNINITIALIZED = 0, // must be default-initialized state - CONSTRUCTING, - INITIALIZING, - INITIALIZED, - DELETED + CONSTRUCTING, // within DERIVED_TYPE constructor + CONSTRUCTED, // finished DERIVED_TYPE constructor + INITIALIZING, // within DERIVED_TYPE::initSingleton() + INITIALIZED, // normal case + DELETED // deleteSingleton() or deleteAll() called } EInitState; // Define tag<T> to pass to our template constructor. You can't explicitly @@ -100,6 +112,9 @@ protected: // That being the case, we control exactly when it happens -- and we can // pop the stack immediately thereafter. void pop_initializing(); + // Remove 'this' from the init stack in case of exception in the + // LLSingleton subclass constructor. + static void reset_initializing(list_t::size_type size); private: // logging static void log_initializing(const char* verb, const char* name); @@ -115,6 +130,10 @@ protected: static void logwarns(const char* p1, const char* p2="", const char* p3="", const char* p4=""); static std::string demangle(const char* mangled); + template <typename T> + static std::string classname() { return demangle(typeid(T).name()); } + template <typename T> + static std::string classname(T* ptr) { return demangle(typeid(*ptr).name()); } // Default methods in case subclass doesn't declare them. virtual void initSingleton() {} @@ -178,7 +197,15 @@ struct LLSingleton_manage_master void remove(LLSingletonBase* sb) { sb->remove_master(); } void push_initializing(LLSingletonBase* sb) { sb->push_initializing(typeid(T).name()); } void pop_initializing (LLSingletonBase* sb) { sb->pop_initializing(); } - LLSingletonBase::list_t& get_initializing(T*) { return LLSingletonBase::get_initializing(); } + // used for init stack cleanup in case an LLSingleton subclass constructor + // throws an exception + void reset_initializing(LLSingletonBase::list_t::size_type size) + { + LLSingletonBase::reset_initializing(size); + } + // For any LLSingleton subclass except the MasterList, obtain the init + // stack from the MasterList singleton instance. + LLSingletonBase::list_t& get_initializing() { return LLSingletonBase::get_initializing(); } }; // But for the specific case of LLSingletonBase::MasterList, don't. @@ -189,9 +216,14 @@ struct LLSingleton_manage_master<LLSingletonBase::MasterList> void remove(LLSingletonBase*) {} void push_initializing(LLSingletonBase*) {} void pop_initializing (LLSingletonBase*) {} - LLSingletonBase::list_t& get_initializing(LLSingletonBase::MasterList* instance) + // since we never pushed, no need to clean up + void reset_initializing(LLSingletonBase::list_t::size_type size) {} + LLSingletonBase::list_t& get_initializing() { - return LLSingletonBase::get_initializing_from(instance); + // The MasterList shouldn't depend on any other LLSingletons. We'd + // get into trouble if we tried to recursively engage that machinery. + static LLSingletonBase::list_t sDummyList; + return sDummyList; } }; @@ -201,10 +233,19 @@ LLSingletonBase::LLSingletonBase(tag<DERIVED_TYPE>): mCleaned(false), mDeleteSingleton(NULL) { - // Make this the currently-initializing LLSingleton. + // This is the earliest possible point at which we can push this new + // instance onto the init stack. LLSingleton::constructSingleton() can't + // do it before calling the constructor, because it doesn't have an + // instance pointer until the constructor returns. Fortunately this + // constructor is guaranteed to be called before any subclass constructor. + // Make this new instance the currently-initializing LLSingleton. LLSingleton_manage_master<DERIVED_TYPE>().push_initializing(this); } +// forward declare for friend directive within LLSingleton +template <typename DERIVED_TYPE> +class LLParamSingleton; + /** * LLSingleton implements the getInstance() method part of the Singleton * pattern. It can't make the derived class constructors protected, though, so @@ -270,9 +311,94 @@ template <typename DERIVED_TYPE> class LLSingleton : public LLSingletonBase { private: - static DERIVED_TYPE* constructSingleton() + // Allow LLParamSingleton subclass -- but NOT DERIVED_TYPE itself -- to + // access our private members. + friend class LLParamSingleton<DERIVED_TYPE>; + + // LLSingleton only supports a nullary constructor. However, the specific + // purpose for its subclass LLParamSingleton is to support Singletons + // requiring constructor arguments. constructSingleton() supports both use + // cases. + template <typename... Args> + static void constructSingleton(Args&&... args) + { + auto prev_size = LLSingleton_manage_master<DERIVED_TYPE>().get_initializing().size(); + // getInstance() calls are from within constructor + sData.mInitState = CONSTRUCTING; + try + { + sData.mInstance = new DERIVED_TYPE(std::forward<Args>(args)...); + // we have called constructor, have not yet called initSingleton() + sData.mInitState = CONSTRUCTED; + } + catch (const std::exception& err) + { + // LLSingletonBase might -- or might not -- have pushed the new + // instance onto the init stack before the exception. Reset the + // init stack to its previous size BEFORE logging so log-machinery + // LLSingletons don't record a dependency on DERIVED_TYPE! + LLSingleton_manage_master<DERIVED_TYPE>().reset_initializing(prev_size); + logwarns("Error constructing ", classname<DERIVED_TYPE>().c_str(), + ": ", err.what()); + // There isn't a separate EInitState value meaning "we attempted + // to construct this LLSingleton subclass but could not," so use + // DELETED. That seems slightly more appropriate than UNINITIALIZED. + sData.mInitState = DELETED; + // propagate the exception + throw; + } + } + + static void finishInitializing() + { + // getInstance() calls are from within initSingleton() + sData.mInitState = INITIALIZING; + try + { + // initialize singleton after constructing it so that it can + // reference other singletons which in turn depend on it, thus + // breaking cyclic dependencies + sData.mInstance->initSingleton(); + sData.mInitState = INITIALIZED; + + // pop this off stack of initializing singletons + pop_initializing(); + } + catch (const std::exception& err) + { + // pop this off stack of initializing singletons here, too -- + // BEFORE logging, so log-machinery LLSingletons don't record a + // dependency on DERIVED_TYPE! + pop_initializing(); + logwarns("Error in ", classname<DERIVED_TYPE>().c_str(), + "::initSingleton(): ", err.what()); + // and get rid of the instance entirely + deleteSingleton(); + // propagate the exception + throw; + } + } + + static void pop_initializing() { - return new DERIVED_TYPE(); + // route through LLSingleton_manage_master so we Do The Right Thing + // (namely, nothing) for MasterList + LLSingleton_manage_master<DERIVED_TYPE>().pop_initializing(sData.mInstance); + } + + // Without this 'using' declaration, the static method we're declaring + // here would hide the base-class method we want it to call. + using LLSingletonBase::capture_dependency; + static void capture_dependency() + { + // By this point, if DERIVED_TYPE was pushed onto the initializing + // stack, it has been popped off. So the top of that stack, if any, is + // an LLSingleton that directly depends on DERIVED_TYPE. If + // getInstance() was called by another LLSingleton, rather than from + // vanilla application code, record the dependency. + sData.mInstance->capture_dependency( + LLSingleton_manage_master<DERIVED_TYPE>().get_initializing(), + sData.mInitState); } // We know of no way to instruct the compiler that every subclass @@ -285,34 +411,17 @@ private: // subclass body. virtual void you_must_use_LLSINGLETON_macro() = 0; - // stores pointer to singleton instance - struct SingletonLifetimeManager + // The purpose of this struct is to engage the C++11 guarantee that static + // variables declared in function scope are initialized exactly once, even + // if multiple threads concurrently reach the same declaration. + // https://en.cppreference.com/w/cpp/language/storage_duration#Static_local_variables + // Since getInstance() declares a static instance of SingletonInitializer, + // only the first call to getInstance() calls constructSingleton(). + struct SingletonInitializer { - SingletonLifetimeManager() - { - construct(); - } - - static void construct() - { - sData.mInitState = CONSTRUCTING; - sData.mInstance = constructSingleton(); - sData.mInitState = INITIALIZING; - } - - ~SingletonLifetimeManager() + SingletonInitializer() { - // The dependencies between LLSingletons, and the arbitrary order - // of static-object destruction, mean that we DO NOT WANT this - // destructor to delete this LLSingleton. This destructor will run - // without regard to any other LLSingleton whose cleanup might - // depend on its existence. If you want to clean up LLSingletons, - // call LLSingletonBase::deleteAll() sometime before static-object - // destruction begins. That method will properly honor cross- - // LLSingleton dependencies. Otherwise we simply leak LLSingleton - // instances at shutdown. Since the whole process is terminating - // anyway, that's not necessarily a bad thing; it depends on what - // resources your LLSingleton instances are managing. + constructSingleton(); } }; @@ -363,64 +472,59 @@ public: static void deleteSingleton() { delete sData.mInstance; - sData.mInstance = NULL; - sData.mInitState = DELETED; + // SingletonData state handled by destructor, above } static DERIVED_TYPE* getInstance() { - static SingletonLifetimeManager sLifeTimeMgr; + // call constructSingleton() only the first time we get here + static SingletonInitializer sInitializer; switch (sData.mInitState) { case UNINITIALIZED: // should never be uninitialized at this point logerrs("Uninitialized singleton ", - demangle(typeid(DERIVED_TYPE).name()).c_str()); + classname<DERIVED_TYPE>().c_str()); return NULL; case CONSTRUCTING: + // here if DERIVED_TYPE's constructor (directly or indirectly) + // calls DERIVED_TYPE::getInstance() logerrs("Tried to access singleton ", - demangle(typeid(DERIVED_TYPE).name()).c_str(), + classname<DERIVED_TYPE>().c_str(), " from singleton constructor!"); return NULL; - case INITIALIZING: - // go ahead and flag ourselves as initialized so we can be - // reentrant during initialization - sData.mInitState = INITIALIZED; - // initialize singleton after constructing it so that it can - // reference other singletons which in turn depend on it, thus - // breaking cyclic dependencies - sData.mInstance->initSingleton(); - // pop this off stack of initializing singletons - LLSingleton_manage_master<DERIVED_TYPE>().pop_initializing(sData.mInstance); + case CONSTRUCTED: + // first time through: set to CONSTRUCTED by + // constructSingleton(), called by sInitializer's constructor; + // still have to call initSingleton() + finishInitializing(); break; + case INITIALIZING: + // here if DERIVED_TYPE::initSingleton() (directly or indirectly) + // calls DERIVED_TYPE::getInstance(): go ahead and allow it case INITIALIZED: + // normal subsequent calls break; case DELETED: + // called after deleteSingleton() logwarns("Trying to access deleted singleton ", - demangle(typeid(DERIVED_TYPE).name()).c_str(), + classname<DERIVED_TYPE>().c_str(), " -- creating new instance"); - SingletonLifetimeManager::construct(); - // same as first time construction - sData.mInitState = INITIALIZED; - sData.mInstance->initSingleton(); - // pop this off stack of initializing singletons - LLSingleton_manage_master<DERIVED_TYPE>().pop_initializing(sData.mInstance); + // This recovery sequence is NOT thread-safe! We would need a + // recursive_mutex a la LLParamSingleton. + constructSingleton(); + finishInitializing(); break; } - // By this point, if DERIVED_TYPE was pushed onto the initializing - // stack, it has been popped off. So the top of that stack, if any, is - // an LLSingleton that directly depends on DERIVED_TYPE. If this call - // came from another LLSingleton, rather than from vanilla application - // code, record the dependency. - sData.mInstance->capture_dependency( - LLSingleton_manage_master<DERIVED_TYPE>().get_initializing(sData.mInstance), - sData.mInitState); + // record the dependency, if any: check if we got here from another + // LLSingleton's constructor or initSingleton() method + capture_dependency(); return sData.mInstance; } @@ -460,6 +564,173 @@ private: template<typename T> typename LLSingleton<T>::SingletonData LLSingleton<T>::sData; + +/** + * LLParamSingleton<T> is like LLSingleton<T>, except in the following ways: + * + * * It is NOT instantiated on demand (instance() or getInstance()). You must + * first call initParamSingleton(constructor args...). + * * Before initParamSingleton(), calling instance() or getInstance() dies with + * LL_ERRS. + * * initParamSingleton() may be called only once. A second call dies with + * LL_ERRS. + * * However, distinct initParamSingleton() calls can be used to engage + * different constructors, as long as only one such call is executed at + * runtime. + * * Unlike LLSingleton, an LLParamSingleton cannot be "revived" by an + * instance() or getInstance() call after deleteSingleton(). + * + * Importantly, though, each LLParamSingleton subclass does participate in the + * dependency-ordered LLSingletonBase::deleteAll() processing. + */ +template <typename DERIVED_TYPE> +class LLParamSingleton : public LLSingleton<DERIVED_TYPE> +{ +private: + typedef LLSingleton<DERIVED_TYPE> super; + // Use a recursive_mutex in case of constructor circularity. With a + // non-recursive mutex, that would result in deadlock rather than the + // logerrs() call in getInstance(). + typedef std::recursive_mutex mutex_t; + +public: + using super::deleteSingleton; + using super::instanceExists; + using super::wasDeleted; + + // Passes arguments to DERIVED_TYPE's constructor and sets appropriate states + template <typename... Args> + static void initParamSingleton(Args&&... args) + { + // In case racing threads both call initParamSingleton() at the same + // time, serialize them. One should initialize; the other should see + // mInitState already set. + std::unique_lock<mutex_t> lk(getMutex()); + // For organizational purposes this function shouldn't be called twice + if (super::sData.mInitState != super::UNINITIALIZED) + { + super::logerrs("Tried to initialize singleton ", + super::template classname<DERIVED_TYPE>().c_str(), + " twice!"); + } + else + { + super::constructSingleton(std::forward<Args>(args)...); + super::finishInitializing(); + } + } + + static DERIVED_TYPE* getInstance() + { + // In case racing threads call getInstance() at the same moment as + // initParamSingleton(), serialize the calls. + std::unique_lock<mutex_t> lk(getMutex()); + + switch (super::sData.mInitState) + { + case super::UNINITIALIZED: + super::logerrs("Uninitialized param singleton ", + super::template classname<DERIVED_TYPE>().c_str()); + break; + + case super::CONSTRUCTING: + super::logerrs("Tried to access param singleton ", + super::template classname<DERIVED_TYPE>().c_str(), + " from singleton constructor!"); + break; + + case super::CONSTRUCTED: + // Should never happen!? The CONSTRUCTED state is specifically to + // navigate through LLSingleton::SingletonInitializer getting + // constructed (once) before LLSingleton::getInstance()'s switch + // on mInitState. But our initParamSingleton() method calls + // constructSingleton() and then calls finishInitializing(), which + // immediately sets INITIALIZING. Why are we here? + super::logerrs("Param singleton ", + super::template classname<DERIVED_TYPE>().c_str(), + "::initSingleton() not yet called"); + break; + + case super::INITIALIZING: + // As with LLSingleton, explicitly permit circular calls from + // within initSingleton() + case super::INITIALIZED: + // for any valid call, capture dependencies + super::capture_dependency(); + return super::sData.mInstance; + + case super::DELETED: + super::logerrs("Trying to access deleted param singleton ", + super::template classname<DERIVED_TYPE>().c_str()); + break; + } + + // should never actually get here; this is to pacify the compiler, + // which assumes control might return from logerrs() + return nullptr; + } + + // instance() is replicated here so it calls + // LLParamSingleton::getInstance() rather than LLSingleton::getInstance() + // -- avoid making getInstance() virtual + static DERIVED_TYPE& instance() + { + return *getInstance(); + } + +private: + // sMutex must be a function-local static rather than a static member. One + // of the essential features of LLSingleton and friends is that they must + // support getInstance() even when the containing module's static + // variables have not yet been runtime-initialized. A mutex requires + // construction. A static class member might not yet have been + // constructed. + // + // We could store a dumb mutex_t*, notice when it's NULL and allocate a + // heap mutex -- but that's vulnerable to race conditions. And we can't + // defend the dumb pointer with another mutex. + // + // We could store a std::atomic<mutex_t*> -- but a default-constructed + // std::atomic<T> does not contain a valid T, even a default-constructed + // T! Which means std::atomic, too, requires runtime initialization. + // + // But a function-local static is guaranteed to be initialized exactly + // once, the first time control reaches that declaration. + static mutex_t& getMutex() + { + static mutex_t sMutex; + return sMutex; + } +}; + +/** + * Initialization locked singleton, only derived class can decide when to initialize. + * Starts locked. + * For cases when singleton has a dependency onto something or. + * + * LLLockedSingleton is like an LLParamSingleton with a nullary constructor. + * It cannot be instantiated on demand (instance() or getInstance() call) -- + * it must be instantiated by calling construct(). However, it does + * participate in dependency-ordered LLSingletonBase::deleteAll() processing. + */ +template <typename DT> +class LLLockedSingleton : public LLParamSingleton<DT> +{ + typedef LLParamSingleton<DT> super; + +public: + using super::deleteSingleton; + using super::getInstance; + using super::instance; + using super::instanceExists; + using super::wasDeleted; + + static void construct() + { + super::initParamSingleton(); + } +}; + /** * Use LLSINGLETON(Foo); at the start of an LLSingleton<Foo> subclass body * when you want to declare an out-of-line constructor: @@ -484,13 +755,13 @@ typename LLSingleton<T>::SingletonData LLSingleton<T>::sData; * file, use 'inline' (unless it's a template class) to avoid duplicate-symbol * errors at link time. */ -#define LLSINGLETON(DERIVED_CLASS) \ +#define LLSINGLETON(DERIVED_CLASS, ...) \ private: \ /* implement LLSingleton pure virtual method whose sole purpose */ \ /* is to remind people to use this macro */ \ virtual void you_must_use_LLSINGLETON_macro() {} \ friend class LLSingleton<DERIVED_CLASS>; \ - DERIVED_CLASS() + DERIVED_CLASS(__VA_ARGS__) /** * Use LLSINGLETON_EMPTY_CTOR(Foo); at the start of an LLSingleton<Foo> |