switch root namespace name to NITLOAD

2026-09-02 18:15:03 +08:00
parent 4218baad48
commit 7c7101ee48
502 changed files with 710 additions and 721 deletions
@@ -0,0 +1,282 @@
+// -----------------------------------------------------------------------------
+// file="IStaticModule"
+// Project: StgSharp
+// Copyright (c) Nitload.
+// SPDX-License-Identifier: MIT
+// -----------------------------------------------------------------------------
+
+using System;
+using System.Collections;
+using System.Collections.Generic;
+
+namespace Nitload
+{
+    /// <summary>
+    ///   Represents a statically activated module that can be registered and initialized as part of
+    ///   the application startup sequence, and gracefully torn down on shutdown.
+    /// </summary>
+    public interface IStaticModule
+    {
+
+        /// <summary>
+        ///   Gets the display name of this module, used for logging and diagnostics.
+        /// </summary>
+        string ModuleName { get; }
+
+        /// <summary>
+        ///   Performs all initialization work for this module using the provided profile.
+        /// </summary>
+        /// <param name="profile">
+        ///   The configuration profile supplied at registration time. Use <see ///  
+        ///   cref="IModuleInitializeConfiguration.Empty" /> if no configuration is required.
+        /// </param>
+        void InitializeModule(
+             IModuleInitializeConfiguration profile
+        );
+
+        /// <summary>
+        ///   Releases all resources acquired during <see cref="InitializeModule" />. Implementations should
+        ///   be idempotent: calling this method more than once must not throw.
+        /// </summary>
+        void UninitializeModule();
+
+    }
+
+    /// <summary>
+    ///   Marker interface for module initialization configuration. Implementations are plain data
+    ///   carriers; no static factory is required.
+    /// </summary>
+    public interface IModuleInitializeConfiguration
+    {
+
+        /// <summary>
+        ///   A shared, allocation-free empty profile for modules that require no configuration.
+        /// </summary>
+        static readonly IModuleInitializeConfiguration Empty = EmptyModuleInitializeProfile.Instance;
+
+        private sealed class EmptyModuleInitializeProfile : IModuleInitializeConfiguration
+        {
+
+            public static readonly EmptyModuleInitializeProfile Instance = new();
+
+            private EmptyModuleInitializeProfile() { }
+
+        }
+
+    }
+
+    /// <summary>
+    ///   Pairs an <see cref="IStaticModule" /> with its <see cref="IModuleInitializeConfiguration"
+    ///   />, ensuring the two are never stored or iterated independently.
+    /// </summary>
+    /// <remarks>
+    ///   Using a <see langword="readonly struct" /> avoids the boxing overhead that would occur if
+    ///   the pair were stored as two parallel lists of reference types.
+    /// </remarks>
+    public readonly struct ModuleDescriptor
+    {
+
+        /// <summary>
+        ///   Initializes a new <see cref="ModuleDescriptor" /> using <see ///  
+        ///   cref="IModuleInitializeConfiguration.Empty" /> as the profile.
+        /// </summary>
+        public ModuleDescriptor(
+               IStaticModule module
+        )
+            : this(module, IModuleInitializeConfiguration.Empty) { }
+
+        /// <summary>
+        ///   Initializes a new <see cref="ModuleDescriptor" /> with an explicit profile.
+        /// </summary>
+        public ModuleDescriptor(
+               IStaticModule module,
+               IModuleInitializeConfiguration profile
+        )
+        {
+            Module = module;
+            Profile = profile;
+        }
+
+        /// <summary>
+        ///   Gets the configuration profile associated with the module.
+        /// </summary>
+        public IModuleInitializeConfiguration Profile { get; }
+
+        /// <summary>
+        ///   Gets the module to be initialized.
+        /// </summary>
+        public IStaticModule Module { get; }
+
+        /// <summary>
+        ///   Calls <see cref="IStaticModule.InitializeModule" /> with the stored profile.
+        /// </summary>
+        public void Initialize()
+        {
+            Module.InitializeModule(Profile);
+        }
+
+        /// <summary>
+        ///   Calls <see cref="IStaticModule.UninitializeModule" /> on the stored module.
+        /// </summary>
+        public void Uninitialize()
+        {
+            Module.UninitializeModule();
+        }
+
+    }
+
+    /// <summary>
+    ///   An ordered collection of modules to be initialized during application startup and
+    ///   uninitialized on shutdown. Supports three registration strategies so that the <c>new()
+    ///   ///</c> generic constraint is never a hard requirement.
+    /// </summary>
+    public sealed class ModuleToInitializeCollection : IEnumerable<IStaticModule>, IStaticModule
+    {
+
+        private readonly List<ModuleDescriptor> _descriptors = [];
+
+        internal ModuleToInitializeCollection(
+                 World.Initializer init,
+                 World.InitializeConfiguration config
+        )
+        {
+            _descriptors.Add(new ModuleDescriptor(init, config));
+        }
+
+        // ── IEnumerable<IStaticModule> ───────────────────────────────────────────
+
+        /// <inheritdoc />
+        public IEnumerator<IStaticModule> GetEnumerator()
+        {
+            foreach (ModuleDescriptor d in _descriptors) {
+                yield return d.Module;
+            }
+        }
+
+        // ── Initialization / Uninitialization ────────────────────────────────────
+
+        /// <summary>
+        ///   Initializes all registered modules in the order they were registered. Each module
+        ///   receives the profile that was supplied at registration time.
+        /// </summary>
+        public void InitializeModule()
+        {
+            for (int i = 0; i < _descriptors.Count; i++) {
+                _descriptors[i].Initialize();
+            }
+        }
+
+        /// <summary>
+        ///   Uninitializes all registered modules in <b> reverse </b> registration order, mirroring
+        ///   the typical LIFO teardown convention (e.g., GLFW must be unloaded after all subsystems
+        ///   that depend on it).
+        /// </summary>
+        public void UninitializeModule()
+        {
+            for (int i = _descriptors.Count - 1; i >= 0; i--) {
+                _descriptors[i].Uninitialize();
+            }
+        }
+
+        // ── Registration API ─────────────────────────────────────────────────────
+
+        /// <summary>
+        ///   Registers a module of type <typeparamref name="T" /> using its default constructor.
+        ///   This is the most concise overload for simple modules that expose a public
+        ///   parameterless constructor.
+        /// </summary>
+        /// <typeparam name="T">
+        ///   A concrete module type that implements <see cref="IStaticModule" /> and exposes a
+        ///   public parameterless constructor.
+        /// </typeparam>
+        /// <param name="profile">
+        ///   Optional initialization profile. Defaults to <see ///  
+        ///   cref="IModuleInitializeConfiguration.Empty" /> when <see langword="null" />.
+        /// </param>
+        public ModuleToInitializeCollection UseModule<T>(
+                                            IModuleInitializeConfiguration? profile = null
+        ) where T : IStaticModule, new()
+        {
+            return UseModule(static() => new T(), profile);
+        }
+
+        /// <summary>
+        ///   Registers a module produced by a factory delegate. This overload imposes no generic
+        ///   constraints and supports any construction strategy, including dependency injection and
+        ///   parameterized constructors.
+        /// </summary>
+        /// <param name="factory">
+        ///   A delegate that constructs and returns the module instance. The delegate is invoked
+        ///   once, immediately at registration time. If <paramref name="factory" /> is <see ///  
+        ///   langword="null" /> or returns <see langword="null" />, the call is silently ignored
+        ///   and the collection is returned unchanged.
+        /// </param>
+        /// <param name="profile">
+        ///   Optional initialization profile. Defaults to <see ///  
+        ///   cref="IModuleInitializeConfiguration.Empty" /> when <see langword="null" />.
+        /// </param>
+        public ModuleToInitializeCollection UseModule(
+                                            Func<IStaticModule> factory,
+                                            IModuleInitializeConfiguration? profile = null
+        )
+        {
+            if (factory is null) {
+                return this;
+            }
+            IStaticModule? mod = factory();
+            if (mod is null) {
+                return this;
+            }
+            _descriptors.Add(new ModuleDescriptor(
+                mod,
+                profile ?? IModuleInitializeConfiguration.Empty));
+            return this;
+        }
+
+        /// <summary>
+        ///   Registers a pre-existing module instance. Use this overload when the module is
+        ///   provided externally, such as from a DI container, an object pool, or a singleton.
+        /// </summary>
+        /// <param name="module">
+        ///   The module instance to register.
+        /// </param>
+        /// <param name="profile">
+        ///   Optional initialization profile. Defaults to <see ///  
+        ///   cref="IModuleInitializeConfiguration.Empty" /> when <see langword="null" />.
+        /// </param>
+        public ModuleToInitializeCollection UseModule(
+                                            IStaticModule module,
+                                            IModuleInitializeConfiguration? profile = null
+        )
+        {
+            _descriptors.Add(new ModuleDescriptor(
+                module,
+                profile ?? IModuleInitializeConfiguration.Empty));
+            return this;
+        }
+
+        /// <inheritdoc />
+        IEnumerator IEnumerable.GetEnumerator()
+        {
+            return GetEnumerator();
+        }
+
+        // ── IStaticModule explicit implementation ────────────────────────────────
+
+        /// <summary>
+        ///   Explicit <see cref="IStaticModule" /> implementation. Delegates to <see ///  
+        ///   cref="InitializeModule()" />, ignoring the supplied profile because each contained module uses
+        ///   its own registered profile.
+        /// </summary>
+        void IStaticModule.InitializeModule(
+                           IModuleInitializeConfiguration profile
+        )
+        {
+            InitializeModule();
+        }
+
+        /// <inheritdoc />
+        string IStaticModule.ModuleName => "Module Initializer";
+
+    }
+}