Skip to content

feat(bootstrap): implement SystemBootstrapper for runtime binding (#176)#183

Merged
kcenon merged 3 commits into
mainfrom
feat/system-bootstrapper-176
Dec 5, 2025
Merged

feat(bootstrap): implement SystemBootstrapper for runtime binding (#176)#183
kcenon merged 3 commits into
mainfrom
feat/system-bootstrapper-176

Conversation

@kcenon

@kcenon kcenon commented Dec 5, 2025

Copy link
Copy Markdown
Owner

Summary

This PR implements Issue #176, adding SystemBootstrapper - a fluent API class for centralized system initialization and logger registration at the application level. It completes the runtime binding infrastructure started in Issues #174 and #175.

Key Features

1. Fluent Configuration API

  • with_default_logger(factory): Register factory for the default logger
  • with_logger(name, factory): Register factory for a named logger
  • on_initialize(callback): Add initialization hook (called in registration order)
  • on_shutdown(callback): Add shutdown hook (called in reverse order - LIFO)

2. Lifecycle Management

  • initialize(): Register all loggers, execute init callbacks
  • shutdown(): Execute shutdown callbacks, clear loggers from registry
  • is_initialized(): Query initialization state
  • reset(): Clear all configuration and reset state

3. RAII Support

  • Destructor automatically calls shutdown() if initialized
  • Move semantics support for transferring ownership
  • Prevention of duplicate initialization/shutdown

Files Changed

File Description
include/kcenon/common/bootstrap/system_bootstrapper.h New: SystemBootstrapper implementation
include/kcenon/common/common.h Updated: Include new bootstrap header
tests/system_bootstrapper_test.cpp New: Comprehensive unit tests (28 tests)
tests/CMakeLists.txt Updated: Add test target
docs/API_REFERENCE.md Updated: Document SystemBootstrapper API
docs/CHANGELOG.md Updated: Add changelog entry

Usage Example

#include <kcenon/common/bootstrap/system_bootstrapper.h>

using namespace kcenon::common::bootstrap;

int main() {
    SystemBootstrapper bootstrapper;
    bootstrapper
        .with_default_logger([]() { return std::make_shared<ConsoleLogger>(); })
        .with_logger("database", []() { return std::make_shared<FileLogger>("db.log"); })
        .on_initialize([]() { LOG_INFO("System started"); })
        .on_shutdown([]() { LOG_INFO("System stopped"); });

    auto result = bootstrapper.initialize();
    if (result.is_err()) {
        std::cerr << "Initialization failed: " << result.error().message;
        return 1;
    }

    // Application logic...
    LOG_INFO("Application running");

    // Shutdown is called automatically by destructor (RAII)
    return 0;
}

Test Plan

  • All 28 unit tests pass (common_system_bootstrapper_test)
  • Build succeeds on macOS with C++17
  • No regressions in existing tests (GlobalLoggerRegistry, log_functions)
  • Documentation updated with complete API reference

Test Coverage

28 test cases covering:

  • Basic initialization/shutdown
  • Fluent API method chaining
  • Callback execution order (init: FIFO, shutdown: LIFO)
  • RAII automatic shutdown
  • Move semantics
  • Error handling (null factories, duplicate init)
  • Reset and reinitialization
  • Integration scenarios

Thread Safety

  • Configuration methods (with_*, on_*) are NOT thread-safe
  • initialize() and shutdown() use mutex for state protection
  • Once initialized, registered loggers are thread-safe via GlobalLoggerRegistry

Dependencies

Closes #176

This commit introduces SystemBootstrapper, a fluent API class for
centralized system initialization and logger registration at the
application level.

Key features implemented:
- Fluent API with method chaining for expressive configuration
- Factory-based logger registration for lazy initialization
- Default logger and named logger support via GlobalLoggerRegistry
- Initialization and shutdown callback hooks
- RAII support with automatic shutdown on destruction
- Prevention of duplicate initialization/shutdown
- Move semantics support for transferring ownership

API design:
- with_default_logger(factory): Register default logger factory
- with_logger(name, factory): Register named logger factory
- on_initialize(callback): Add initialization hook
- on_shutdown(callback): Add shutdown hook (LIFO order)
- initialize(): Start the system and register all loggers
- shutdown(): Stop the system and clear loggers
- is_initialized(): Query initialization state
- reset(): Clear all configuration and reset state

Thread Safety:
- Configuration methods are NOT thread-safe
- Lifecycle methods use mutex for state protection
- Registered loggers are thread-safe via GlobalLoggerRegistry

RAII guarantees:
- Destructor calls shutdown() if initialized
- Move assignment handles cleanup of current state
- Move constructor transfers ownership without double shutdown

The implementation follows the existing codebase patterns from
global_logger_registry.h and integrates seamlessly with the
runtime binding infrastructure from Issues #174 and #175.

Refs: #176
This commit adds unit tests covering all aspects of the SystemBootstrapper
implementation, ensuring correctness and proper behavior.

Test categories implemented:

1. Basic Initialization Tests:
   - Initialize with and without default logger
   - Duplicate initialization returns error
   - Shutdown success and idempotency
   - Shutdown before initialize has no effect

2. Fluent API Tests:
   - Method chaining verification
   - Default logger registration via factory
   - Named logger registration via factory
   - Duplicate name overwrites previous factory

3. Callback Execution Tests:
   - Init callbacks executed in registration order
   - Shutdown callbacks executed in reverse order (LIFO)
   - Init callbacks execute after logger registration
   - Shutdown callbacks execute before logger clear

4. RAII Tests:
   - Destructor automatically calls shutdown
   - Registry cleared on destruction

5. Move Semantics Tests:
   - Move construction transfers ownership
   - Move assignment transfers ownership and cleans up
   - Move prevents double shutdown

6. Error Handling Tests:
   - Null factory result returns error
   - Named logger null factory returns error
   - Null callback ignored safely

7. Reset Tests:
   - Reset clears all configuration
   - Reset calls shutdown if initialized
   - Reset allows reinitialization with new config

8. Integration Tests:
   - Complete lifecycle (create, init, use, shutdown)
   - Multiple bootstrappers in sequence

All 28 tests pass successfully.

Refs: #176
…apper

This commit updates documentation to reflect the new SystemBootstrapper
class introduced in Issue #176.

API Reference updates:
- Added "Bootstrap" section with complete API documentation
- Documented SystemBootstrapper class with all methods:
  - Constructor/Destructor with RAII behavior
  - Fluent configuration API: with_default_logger(), with_logger(),
    on_initialize(), on_shutdown()
  - Lifecycle methods: initialize(), shutdown(), is_initialized(), reset()
- Added comprehensive usage examples including RAII pattern
- Documented thread safety characteristics
- Updated version to 2.2 and updated table of contents

Changelog updates:
- Added entry for SystemBootstrapper under [Unreleased]
- Listed all new features:
  - Factory-based logger registration
  - Default and named logger support
  - Init/shutdown hooks with ordering guarantees
  - RAII support with automatic shutdown
  - Move semantics support
  - Duplicate initialization/shutdown prevention
  - Reset method for reconfiguration

Updated common.h:
- Added include for bootstrap/system_bootstrapper.h
- Added "Bootstrap (Issue #176)" section comment

Refs: #176
@kcenon kcenon merged commit a55cf69 into main Dec 5, 2025
25 checks passed
@kcenon kcenon deleted the feat/system-bootstrapper-176 branch December 5, 2025 15:04
kcenon added a commit that referenced this pull request Apr 13, 2026
…) (#183)

* feat(bootstrap): implement SystemBootstrapper for runtime binding

This commit introduces SystemBootstrapper, a fluent API class for
centralized system initialization and logger registration at the
application level.

Key features implemented:
- Fluent API with method chaining for expressive configuration
- Factory-based logger registration for lazy initialization
- Default logger and named logger support via GlobalLoggerRegistry
- Initialization and shutdown callback hooks
- RAII support with automatic shutdown on destruction
- Prevention of duplicate initialization/shutdown
- Move semantics support for transferring ownership

API design:
- with_default_logger(factory): Register default logger factory
- with_logger(name, factory): Register named logger factory
- on_initialize(callback): Add initialization hook
- on_shutdown(callback): Add shutdown hook (LIFO order)
- initialize(): Start the system and register all loggers
- shutdown(): Stop the system and clear loggers
- is_initialized(): Query initialization state
- reset(): Clear all configuration and reset state

Thread Safety:
- Configuration methods are NOT thread-safe
- Lifecycle methods use mutex for state protection
- Registered loggers are thread-safe via GlobalLoggerRegistry

RAII guarantees:
- Destructor calls shutdown() if initialized
- Move assignment handles cleanup of current state
- Move constructor transfers ownership without double shutdown

The implementation follows the existing codebase patterns from
global_logger_registry.h and integrates seamlessly with the
runtime binding infrastructure from Issues #174 and #175.

Refs: #176

* test(bootstrap): add comprehensive tests for SystemBootstrapper

This commit adds unit tests covering all aspects of the SystemBootstrapper
implementation, ensuring correctness and proper behavior.

Test categories implemented:

1. Basic Initialization Tests:
   - Initialize with and without default logger
   - Duplicate initialization returns error
   - Shutdown success and idempotency
   - Shutdown before initialize has no effect

2. Fluent API Tests:
   - Method chaining verification
   - Default logger registration via factory
   - Named logger registration via factory
   - Duplicate name overwrites previous factory

3. Callback Execution Tests:
   - Init callbacks executed in registration order
   - Shutdown callbacks executed in reverse order (LIFO)
   - Init callbacks execute after logger registration
   - Shutdown callbacks execute before logger clear

4. RAII Tests:
   - Destructor automatically calls shutdown
   - Registry cleared on destruction

5. Move Semantics Tests:
   - Move construction transfers ownership
   - Move assignment transfers ownership and cleans up
   - Move prevents double shutdown

6. Error Handling Tests:
   - Null factory result returns error
   - Named logger null factory returns error
   - Null callback ignored safely

7. Reset Tests:
   - Reset clears all configuration
   - Reset calls shutdown if initialized
   - Reset allows reinitialization with new config

8. Integration Tests:
   - Complete lifecycle (create, init, use, shutdown)
   - Multiple bootstrappers in sequence

All 28 tests pass successfully.

Refs: #176

* docs(bootstrap): update API reference and changelog for SystemBootstrapper

This commit updates documentation to reflect the new SystemBootstrapper
class introduced in Issue #176.

API Reference updates:
- Added "Bootstrap" section with complete API documentation
- Documented SystemBootstrapper class with all methods:
  - Constructor/Destructor with RAII behavior
  - Fluent configuration API: with_default_logger(), with_logger(),
    on_initialize(), on_shutdown()
  - Lifecycle methods: initialize(), shutdown(), is_initialized(), reset()
- Added comprehensive usage examples including RAII pattern
- Documented thread safety characteristics
- Updated version to 2.2 and updated table of contents

Changelog updates:
- Added entry for SystemBootstrapper under [Unreleased]
- Listed all new features:
  - Factory-based logger registration
  - Default and named logger support
  - Init/shutdown hooks with ordering guarantees
  - RAII support with automatic shutdown
  - Move semantics support
  - Duplicate initialization/shutdown prevention
  - Reset method for reconfiguration

Updated common.h:
- Added include for bootstrap/system_bootstrapper.h
- Added "Bootstrap (Issue #176)" section comment

Refs: #176
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(bootstrap): implement SystemBootstrapper for runtime binding

1 participant