/* DEPENDENCY-FACTORY.hpp - managing the lifecycle of singletons and dependencies Copyright (C) Lumiera.org 2013, Hermann Vosseler This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ /** @file dependency-factory.hpp ** Implementation of a singleton factory used to bring up services as dependency. ** @internal this implementation header belongs to our framework to deal with ** [service dependencies](\ref depend.hpp) and should not be used directly. ** @todo WIP-WIP 3/18 rework of the singleton / dependency factory is underway */ #ifndef LIB_DEPEND_INJECT_H #define LIB_DEPEND_INJECT_H #include "lib/error.hpp" #include "lib/depend2.hpp" #include "lib/sync-classlock.hpp" #include #include namespace lib { namespace error = lumiera::error; using std::move; /** * This framework allows to (re)configure the lib::Depend front-end for dependency-injection. * By default, `Depend` will create a singleton instance of `TY` lazily, on demand. * When instantiating one of the configuration handles provided here -- _prior_ to using * retrieving the instance through `Depend` -- this default (singleton) behaviour * can be reconfigured in various ways, without the client being aware of it * - instead of a singleton, a service instance with well defined lifecycle can be * exposed through the `Depend` front-end. When the service is shut down, * clients will receive an exception on access. * - instead of the interface type `TY` mentioned in `Depend`, an implementation subclass * can be specified, optionally with a closure for the actual creation of this subclass * singleton type, which still happens lazily, on demand * - the current state and configuration can be shadowed temporarily by a test mock instance, * which is managed automatically and removed when leaving the scope of the test. */ template struct DependInject { using Factory = typename Depend::Factory; /** configure dependency-injection for type SRV to build a subclass singleton * @tparam SUB concrete subclass type to build on demand when invoking `Depend` * @throws error::Logic (LUMIERA_ERROR_LIFECYCLE) when the default factory has already * been invoked at the point when calling this (re)configuration function. */ template static void useSingleton() { __assert_compatible(); static InstanceHolder singleton; installFactory ([&]() { return singleton.buildInstance(); }); } /** * Configuration handle to expose a service implementation through the `Depend` front-end. * This noncopyable (but movable) handle shall be planted within the context operating the service * to be exposed. It will immediately create (in RAII style) and manage a heap-allocated instance * of the subclass `IMP` and expose a baseclass pointer to this specific instance through `Depend`. * Moreover, the implementation subclass can be accessed through this handle, which acts as smart-ptr. * When the handle goes out of scope, the implementation instance is destroyed and the access through * `Depend` is closed and inhibited, to prevent on-demand creation of a baseclass `SRV` singleton. * @tparam IMP concrete service implementation subclass to build, manage and expose. * @throws error::Logic (LUMIERA_ERROR_LIFECYCLE) when the default factory has already * been invoked at the point when calling this (re)configuration function. */ template class ServiceInstance { std::unique_ptr instance_; public: ServiceInstance() : instance_(new IMP{}) { __assert_compatible(); activateServiceAccess (*instance_); } ~ServiceInstance() { deactivateServiceAccess(); } ServiceInstance (ServiceInstance&&) = default; ServiceInstance (ServiceInstance const&) = delete; ServiceInstance& operator= (ServiceInstance&&) = delete; explicit operator bool() const { return bool(instance_); } IMP& operator* () const { ENSURE (instance_); return *instance_; } IMP* operator-> () const { ENSURE (instance_); return instance_.get(); } }; /** * Configuration handle for temporarily shadowing a dependency by a test mock instance. * This noncopyable (but movable) handle shall be planted within the immediate test context. * It immediately stashes away the existing state and configuration from `Depend`, but * waits for actual invocation of the `Depend`-front-end to create a heap-allocated * instance of the `MOC` subclass, which it manages and exposes like a smart-ptr. * When the handle goes out of scope, the original state and configuration is restored */ template class Local { std::unique_ptr mock_; SRV* origInstance_; Factory origFactory_; public: Local() { __assert_compatible(); temporarilyInstallAlternateFactory (origInstance_, origFactory_ ,[this]() { mock_.reset(new MOC{}); return mock_.get(); }); } ~Local() { restoreOriginalFactory (origInstance_, origFactory_); } Local (Local&&) = default; Local (Local const&) = delete; Local& operator= (Local&&) = delete; explicit operator bool() const { return bool(mock_); } MOC& operator* () const { ENSURE (mock_); return *mock_; } MOC* operator-> () const { ENSURE (mock_); return mock_.get(); } }; protected: /* ======= internal access-API for those configurations to manipulate Depend ======= */ template friend class ServiceInstance; template friend class Local; template static void __assert_compatible() { static_assert (std::is_base_of::value, "Installed implementation class must be compatible to the interface."); } static void installFactory (Factory&& otherFac) { ClassLock guard; if (Depend::instance) throw error::Logic("Attempt to reconfigure dependency injection after the fact. " "The previously installed factory (typically Singleton) was already used." , error::LUMIERA_ERROR_LIFECYCLE); Depend::factory = move (otherFac); } static void temporarilyInstallAlternateFactory (SRV*& stashInstance, Factory& stashFac, Factory&& newFac) { ClassLock guard; stashFac = move(Depend::factory); stashInstance = Depend::instance; Depend::factory = move(newFac); Depend::instance = nullptr; } static void restoreOriginalFactory (SRV*& stashInstance, Factory& stashFac) { ClassLock guard; Depend::factory = move(stashFac); Depend::instance = stashInstance; } static void activateServiceAccess (SRV& newInstance) { ClassLock guard; if (Depend::instance) throw error::Logic("Attempt to activate an external service implementation, " "but another instance has already been dependency-injected." , error::LUMIERA_ERROR_LIFECYCLE); Depend::instance = &newInstance; Depend::factory = Depend::disabledFactory; } static void deactivateServiceAccess() { ClassLock guard; Depend::instance = nullptr; Depend::factory = Depend::disabledFactory; } }; } // namespace lib #endif