Implement External lifetime support and descriptor-keyed factories; update tests and CMake configuration

Author: Alex Radzevich

.gitignore

@@ -38,4 +38,5 @@ Makefile
 .DS_Store
 Thumbs.db
 
-cmake-build-debug
+cmake-build-debug
+build_test

build_test/Testing/Temporary/CTestCostData.txt

@@ -2,10 +2,17 @@
 
 namespace IOC {
 
-    struct Singleton {};
+struct Singleton {};
 
-    struct Scoped {};
+struct Scoped {};
 
-    struct Transient {};
+struct Transient {};
 
-}
+// External: the instance is owned outside of the container and is supplied
+// at runtime via `Container::Bind<TDescriptor>(ptr)`. Resolving an External
+// descriptor returns a non-owning pointer to that externally-managed object.
+// This is the bridge between the compile-time DI graph and runtime values
+// (configuration, OS resources, pre-existing collaborators).
+struct External {};
+
+} // namespace IOC

build_test/Testing/Temporary/LastTest.log

@@ -4,48 +4,73 @@
 #include "service_factory.h"
 #include "util/evaluate_type.h"
 #include <memory>
-#include <optional>
 
 namespace IOC {
 
-    template <typename TDescriptor, typename TLifetime = typename Binding<TDescriptor>::TLifetime>
-    struct LifetimeManager;
+template <typename TDescriptor, typename TLifetime = typename Binding<TDescriptor>::TLifetime>
+struct LifetimeManager;
 
-    template <typename TDescriptor>
-    struct LifetimeManager<TDescriptor, Transient> {
-        using TService = Binding<TDescriptor>::TService;
+template <typename TDescriptor>
+struct LifetimeManager<TDescriptor, Transient> {
+  using TService = typename Binding<TDescriptor>::TService;
+  using TFactory = ResolveFactory_t<TService, TDescriptor>;
 
-        constexpr auto GetOrCreate(auto& container) {
-            return ServiceFactory<TService>::Create(container);
-        }
-    };
+  constexpr auto GetOrCreate(auto& container) {
+    return TFactory::Create(container);
+  }
+};
 
-    template <typename TDescriptor>
-    struct LifetimeManager<TDescriptor, Scoped> {
-        using TService = Binding<TDescriptor>::TService;
-        using TRealType = Util::ReplaceDescriptors<TService>::TResult;
+template <typename TDescriptor>
+struct LifetimeManager<TDescriptor, Scoped> {
+  using TService  = typename Binding<TDescriptor>::TService;
+  using TRealType = typename Util::ReplaceDescriptors<TService>::TResult;
+  using TFactory  = ResolveFactory_t<TService, TDescriptor>;
 
-        constexpr auto GetOrCreate(auto& container) {
-            if (!Instance_.has_value()) [[unlikely]] {
-                Instance_ = ServiceFactory<TService>::Create(container);
-            }
+  // Storage is std::unique_ptr (not std::optional) so non-movable / non-copyable
+  // services are supported: heap-construct in place via make_unique.
+  auto GetOrCreate(auto& container) {
+    if (!Instance_) [[unlikely]] {
+      Instance_ = TFactory::CreateUnique(container);
+    }
+    return Instance_.get();
+  }
 
-            return std::addressof(Instance_.value());
-        }
+private:
+  std::unique_ptr<TRealType> Instance_;
+};
 
-    private:
-        std::optional<TRealType> Instance_;
-    };
+template <typename TDescriptor>
+struct LifetimeManager<TDescriptor, Singleton> {
+  using TService = typename Binding<TDescriptor>::TService;
+  using TFactory = ResolveFactory_t<TService, TDescriptor>;
 
-    template <typename TDescriptor>
-    struct LifetimeManager<TDescriptor, Singleton> {
-        using TService = Binding<TDescriptor>::TService;
+  auto GetOrCreate(auto& container) {
+    // NOTE: Singleton intentionally lives in a function-local static so
+    // its lifetime spans the whole process and is shared across
+    // containers. Per-container lifetime should use Scoped.
+    static auto instance = TFactory::Create(container);
+    return std::addressof(instance);
+  }
+};
 
-        auto GetOrCreate(auto& container) {
-            // TODO: Definition of a static variable in a constexpr function is a C++23 extension
-            static auto instance = ServiceFactory<TService>::Create(container);
-            return std::addressof(instance);
-        }
-    };
+// External: the container does not own the instance. The user must call
+// Container::Bind<TDescriptor>(ptr) before the first Resolve. GetOrCreate
+// returns the registered pointer (or nullptr if Bind was never called).
+template <typename TDescriptor>
+struct LifetimeManager<TDescriptor, External> {
+  using TService  = typename Binding<TDescriptor>::TService;
+  using TRealType = typename Util::ReplaceDescriptors<TService>::TResult;
 
-}
+  constexpr TRealType* GetOrCreate(auto&) const noexcept {
+    return Instance_;
+  }
+
+  constexpr void SetInstance(TRealType* ptr) noexcept {
+    Instance_ = ptr;
+  }
+
+private:
+  TRealType* Instance_ = nullptr;
+};
+
+} // namespace IOC

build_test/tests/ioc_tests

@@ -3,35 +3,53 @@
 #include "binding.h"
 #include "lifetime_manager.h"
 
-namespace IOC {
-
-    template <typename TDescriptor, typename... TDescriptors>
-    concept OneOf = (std::same_as<TDescriptor, TDescriptors> || ...);
-
-    template <typename ...TDescriptors>
-    class Container;
-
-    template <typename ...TDescriptors>
-    class Container {
-    private:
-        std::tuple<LifetimeManager<TDescriptors>...> LifetimeManagers_;
+#include <concepts>
+#include <optional>
+#include <tuple>
+#include <type_traits>
 
-    public:
-        template <OneOf<TDescriptors...> TDescriptor>
-        constexpr auto Resolve() {
-            return std::get<LifetimeManager<TDescriptor>>(LifetimeManagers_)
-                .GetOrCreate(*this);
-        }
-
-        template <typename TDescriptor>
-        constexpr auto Resolve() {
-            return std::nullopt;
-        }
-    };
-
-    template <typename ...TContainerArs, typename ...Rest>
-    class Container<Container<TContainerArs...>, Rest...>
-        : public Container<Rest..., TContainerArs...> {
-    };
+namespace IOC {
 
-}
+template <typename TDescriptor, typename... TDescriptors>
+concept OneOf = (std::same_as<TDescriptor, TDescriptors> || ...);
+
+template <typename... TDescriptors>
+class Container;
+
+template <typename... TDescriptors>
+class Container {
+private:
+  std::tuple<LifetimeManager<TDescriptors>...> LifetimeManagers_;
+
+public:
+  template <OneOf<TDescriptors...> TDescriptor>
+  constexpr auto Resolve() {
+    return std::get<LifetimeManager<TDescriptor>>(LifetimeManagers_).GetOrCreate(*this);
+  }
+
+  template <typename TDescriptor>
+  constexpr auto Resolve() {
+    // Unregistered descriptor. Returning std::nullopt keeps SFINAE-style
+    // probes working but resolving a missing descriptor in production code
+    // is almost always a wiring bug.
+    return std::nullopt;
+  }
+
+  // Register an externally-owned instance for an `External`-lifetime
+  // descriptor. Must be called before the first Resolve<TDescriptor>().
+  // Compile error if TDescriptor is not registered or is not External.
+  template <OneOf<TDescriptors...> TDescriptor, typename T>
+  constexpr void Bind(T* ptr) {
+    using Manager = LifetimeManager<TDescriptor>;
+    static_assert(std::is_same_v<typename Binding<TDescriptor>::TLifetime, External>,
+                  "Container::Bind<D>(ptr) only applies to descriptors with "
+                  "TLifetime = IOC::External.");
+    std::get<Manager>(LifetimeManagers_).SetInstance(ptr);
+  }
+};
+
+template <typename... TContainerArs, typename... Rest>
+class Container<Container<TContainerArs...>, Rest...> :
+    public Container<Rest..., TContainerArs...> {};
+
+} // namespace IOC

include/ioc/lifetime.h

@@ -1,32 +1,99 @@
 #pragma once
 
-#include <type_traits>
 #include "util/evaluate_type.h"
+#include <memory>
+#include <type_traits>
+#include <utility>
 
 namespace IOC {
 
-    template <typename TService>
+    // Factory keyed by both the service type AND the requesting descriptor.
+    // The descriptor parameter defaults to `void` so the common case ("one
+    // factory per service type") keeps the simpler descriptor-less form.
+    // Specialise with an explicit descriptor when several descriptors share
+    // the same service type but need different construction recipes (e.g.
+    // multiple `SpScBytesQueue` instances with different names/capacities).
+    //
+    // Lookup precedence (see ResolveFactory_t below):
+    //   1. ServiceFactory<TService, TDescriptor>  (user-provided per-descriptor)
+    //   2. ServiceFactory<TService, void>          (auto / default)
+    template <typename TService, typename TDescriptor = void>
     struct ServiceFactory;
 
+    // Default specialisation: descriptor-less, default-constructs the service.
     template <typename TService>
-    struct ServiceFactory {
+    struct ServiceFactory<TService, void> {
         static constexpr TService Create(auto&) {
-            static_assert(std::is_default_constructible_v<TService>);
+            static_assert(std::is_default_constructible_v<TService>,
+                          "Service has no descriptor parameters and is not default-constructible. "
+                          "Specialise IOC::ServiceFactory<TService> (or "
+                          "IOC::ServiceFactory<TService, TDescriptor>) with a custom Create().");
             return TService();
         }
+
+        static auto CreateUnique(auto& container) {
+            if constexpr (std::is_default_constructible_v<TService>) {
+                return std::make_unique<TService>();
+            } else {
+                return std::unique_ptr<TService>(new TService(Create(container)));
+            }
+        }
     };
 
-    template <template<typename ...> class TService, typename... TDescriptors>
-    struct ServiceFactory<TService<TDescriptors...>> {
+    // Templated-service specialisation: resolves each TDescriptor from the
+    // container and forwards it to the actual constructor.
+    template <template <typename...> class TService, typename... TDescriptors>
+    struct ServiceFactory<TService<TDescriptors...>, void> {
+        using TActualServiceType =
+            typename Util::ReplaceDescriptors<TService<TDescriptors...>>::TResult;
+
         static constexpr auto Create(auto& container) {
-            using TActualServiceType = typename Util::ReplaceDescriptors<TService<TDescriptors...>>::TResult;
+            static_assert(
+                std::is_constructible_v<TActualServiceType,
+                                        decltype(container.template Resolve<TDescriptors>())...>,
+                "Service is not constructible from its resolved dependencies. "
+                "Either fix the constructor signature or specialise IOC::ServiceFactory<...>.");
+            return TActualServiceType(container.template Resolve<TDescriptors>()...);
+        }
 
-            if constexpr (std::is_constructible_v<TActualServiceType, decltype(container.template Resolve<TDescriptors>())...>) {
-                return TActualServiceType(container.template Resolve<TDescriptors>()...);
-            } else {
-                return TActualServiceType();
-            }
+        static auto CreateUnique(auto& container) {
+            static_assert(
+                std::is_constructible_v<TActualServiceType,
+                                        decltype(container.template Resolve<TDescriptors>())...>,
+                "Service is not constructible from its resolved dependencies (CreateUnique).");
+            return std::make_unique<TActualServiceType>(
+                container.template Resolve<TDescriptors>()...);
         }
     };
 
+    // Selects the matching ServiceFactory specialisation for a (Service,
+    // Descriptor) pair. If the user specialised
+    // `ServiceFactory<TService, TDescriptor>` it is picked; otherwise the
+    // descriptor-less `ServiceFactory<TService, void>` is used.
+    //
+    // Detection: the primary `ServiceFactory<TService, TDescriptor>` is only
+    // forward-declared, so `sizeof(ServiceFactory<T, D>)` is valid *only* when
+    // (a) D == void (the default partial spec is complete), or (b) the user
+    // supplied a descriptor-keyed specialisation. Probe via SFINAE and use a
+    // descriptor-keyed factory only when D != void.
+    namespace detail {
+
+        template <typename TService, typename TDescriptor, typename = void>
+        struct HasDescriptorKeyedFactory : std::false_type {};
+
+        template <typename TService, typename TDescriptor>
+        struct HasDescriptorKeyedFactory<
+            TService,
+            TDescriptor,
+            std::void_t<decltype(sizeof(ServiceFactory<TService, TDescriptor>))>>
+            : std::bool_constant<!std::is_void_v<TDescriptor>> {};
+
+    } // namespace detail
+
+    template <typename TService, typename TDescriptor>
+    using ResolveFactory_t =
+        std::conditional_t<detail::HasDescriptorKeyedFactory<TService, TDescriptor>::value,
+                           ServiceFactory<TService, TDescriptor>,
+                           ServiceFactory<TService, void>>;
+
 }