kcenon::common::bootstrap::SystemBootstrapper Class Reference

Fluent API for system initialization and logger registration. More...

#include <system_bootstrapper.h>

Collaboration diagram for kcenon::common::bootstrap::SystemBootstrapper:

Public Member Functions
	SystemBootstrapper ()=default
	Default constructor.
	~SystemBootstrapper ()
	Destructor with automatic shutdown.
	SystemBootstrapper (const SystemBootstrapper &)=delete
SystemBootstrapper &	operator= (const SystemBootstrapper &)=delete
	SystemBootstrapper (SystemBootstrapper &&other) noexcept
SystemBootstrapper &	operator= (SystemBootstrapper &&other) noexcept
SystemBootstrapper &	with_default_logger (interfaces::LoggerFactory factory)
	Register a factory for the default logger.
SystemBootstrapper &	with_logger (const std::string &name, interfaces::LoggerFactory factory)
	Register a factory for a named logger.
SystemBootstrapper &	on_initialize (std::function< void()> callback)
	Register an initialization callback.
SystemBootstrapper &	on_shutdown (std::function< void()> callback)
	Register a shutdown callback.
SystemBootstrapper &	with_auto_freeze (bool freeze_logger_registry=true, bool freeze_service_container=true)
	Enable automatic freezing of registries after initialization.
VoidResult	initialize ()
	Initialize the system.
void	shutdown ()
	Shutdown the system.
bool	is_initialized () const noexcept
	Check if the system is initialized.
void	reset ()
	Reset the bootstrapper to initial state.

Private Member Functions
VoidResult	register_loggers ()
	Register all loggers with GlobalLoggerRegistry.
void	execute_init_callbacks ()
	Execute all initialization callbacks.
void	execute_shutdown_callbacks ()
	Execute all shutdown callbacks in reverse order.
void	clear_loggers ()
	Clear all loggers from GlobalLoggerRegistry.

Private Attributes
interfaces::LoggerFactory	default_logger_factory_
std::vector< std::pair< std::string, interfaces::LoggerFactory > >	named_logger_factories_
std::vector< std::function< void()> >	init_callbacks_
std::vector< std::function< void()> >	shutdown_callbacks_
bool	auto_freeze_logger_registry_ = false
bool	auto_freeze_service_container_ = false
bool	initialized_ = false
std::mutex	state_mutex_

Detailed Description

Fluent API for system initialization and logger registration.

SystemBootstrapper provides a centralized mechanism for:

• Registering default and named loggers using factory functions
• Defining initialization and shutdown callbacks
• Managing application lifecycle with RAII support

Key Features:

• Fluent API with method chaining for expressive configuration
• Factory-based lazy initialization of loggers
• RAII support with automatic shutdown on destruction
• Prevention of duplicate initialization/shutdown
• Integration with GlobalLoggerRegistry for thread-safe logger access

Design Notes:

• Configuration methods are not thread-safe; call from single thread
• Once initialize() succeeds, loggers are available globally
• Shutdown callbacks are called in reverse order of registration
• Initialize callbacks are called in order of registration

Definition at line 90 of file system_bootstrapper.h.

Constructor & Destructor Documentation

SystemBootstrapper() [1/3]

kcenon::common::bootstrap::SystemBootstrapper::SystemBootstrapper ( )

default

Default constructor.

Creates an uninitialized bootstrapper. Call configuration methods and then initialize() to start the system.

~SystemBootstrapper()

kcenon::common::bootstrap::SystemBootstrapper::~SystemBootstrapper ( )

inline

Destructor with automatic shutdown.

Automatically calls shutdown() if the bootstrapper was initialized. This ensures proper cleanup even if shutdown() is not called explicitly.

Definition at line 304 of file system_bootstrapper.h.

                                               {
    if (initialized_) {
        shutdown();
    }
}

References initialized_, and shutdown().

Here is the call graph for this function:

SystemBootstrapper() [2/3]

kcenon::common::bootstrap::SystemBootstrapper::SystemBootstrapper ( const SystemBootstrapper & )

delete

SystemBootstrapper() [3/3]

kcenon::common::bootstrap::SystemBootstrapper::SystemBootstrapper ( SystemBootstrapper && other )

inlinenoexcept

Definition at line 310 of file system_bootstrapper.h.

    : default_logger_factory_(std::move(other.default_logger_factory_))
    , named_logger_factories_(std::move(other.named_logger_factories_))
    , init_callbacks_(std::move(other.init_callbacks_))
    , shutdown_callbacks_(std::move(other.shutdown_callbacks_))
    , auto_freeze_logger_registry_(other.auto_freeze_logger_registry_)
    , auto_freeze_service_container_(other.auto_freeze_service_container_)
    , initialized_(other.initialized_) {
    other.initialized_ = false;  // Prevent double shutdown
}

Member Function Documentation

clear_loggers()

void kcenon::common::bootstrap::SystemBootstrapper::clear_loggers ( )

inlineprivate

Clear all loggers from GlobalLoggerRegistry.

Definition at line 520 of file system_bootstrapper.h.

                                              {
    interfaces::GlobalLoggerRegistry::instance().clear();
}

References kcenon::common::interfaces::GlobalLoggerRegistry::clear(), and kcenon::common::interfaces::GlobalLoggerRegistry::instance().

Referenced by register_loggers(), and shutdown().

Here is the call graph for this function:

Here is the caller graph for this function:

execute_init_callbacks()

void kcenon::common::bootstrap::SystemBootstrapper::execute_init_callbacks ( )

inlineprivate

Execute all initialization callbacks.

Definition at line 501 of file system_bootstrapper.h.

                                                       {
    for (const auto& callback : init_callbacks_) {
        if (callback) {
            callback();
        }
    }
}

References init_callbacks_.

Referenced by initialize().

Here is the caller graph for this function:

execute_shutdown_callbacks()

void kcenon::common::bootstrap::SystemBootstrapper::execute_shutdown_callbacks ( )

inlineprivate

Execute all shutdown callbacks in reverse order.

Definition at line 509 of file system_bootstrapper.h.

                                                           {
    // Execute in reverse order (LIFO)
    for (auto it = shutdown_callbacks_.rbegin();
         it != shutdown_callbacks_.rend();
         ++it) {
        if (*it) {
            (*it)();
        }
    }
}

References shutdown_callbacks_.

Referenced by shutdown().

Here is the caller graph for this function:

initialize()

VoidResult kcenon::common::bootstrap::SystemBootstrapper::initialize ( )

inline

Initialize the system.

Performs the following steps in order:

1. Validates that initialization hasn't already occurred
2. Creates and registers the default logger (if configured)
3. Creates and registers all named loggers
4. Calls all initialization callbacks in registration order
5. Marks the bootstrapper as initialized

If any step fails, the operation is rolled back and an error is returned.

Returns

VoidResult indicating success or error

Note

This method should only be called once. Subsequent calls return an error.

Definition at line 385 of file system_bootstrapper.h.

                                                 {
    std::lock_guard<std::mutex> lock(state_mutex_);
 
    if (initialized_) {
        return make_error<std::monostate>(
            error_codes::ALREADY_EXISTS,
            "SystemBootstrapper already initialized",
            "bootstrap::SystemBootstrapper"
        );
    }
 
    // Step 1: Register all loggers
    auto result = register_loggers();
    if (result.is_err()) {
        return result;
    }
 
    // Step 2: Execute initialization callbacks
    execute_init_callbacks();
 
    // Step 3: Freeze registries if auto-freeze is enabled
    if (auto_freeze_logger_registry_) {
        interfaces::GlobalLoggerRegistry::instance().freeze();
    }
    if (auto_freeze_service_container_) {
        di::service_container::global().freeze();
    }
 
    // Step 4: Mark as initialized
    initialized_ = true;
 
    return VoidResult::ok({});
}

References kcenon::common::error_codes::ALREADY_EXISTS, auto_freeze_logger_registry_, auto_freeze_service_container_, execute_init_callbacks(), kcenon::common::di::service_container::freeze(), kcenon::common::interfaces::GlobalLoggerRegistry::freeze(), kcenon::common::di::service_container::global(), initialized_, kcenon::common::interfaces::GlobalLoggerRegistry::instance(), kcenon::common::make_error(), kcenon::common::Result< T >::ok(), register_loggers(), and state_mutex_.

Here is the call graph for this function:

is_initialized()

bool kcenon::common::bootstrap::SystemBootstrapper::is_initialized ( ) const

inlinenoexcept

Check if the system is initialized.

Returns

true if initialize() has been called successfully

Definition at line 436 of file system_bootstrapper.h.

                                                              {
    std::lock_guard<std::mutex> lock(state_mutex_);
    return initialized_;
}

References initialized_, and state_mutex_.

Referenced by reset().

Here is the caller graph for this function:

on_initialize()

SystemBootstrapper & kcenon::common::bootstrap::SystemBootstrapper::on_initialize ( std::function< void()> callback )

inline

Register an initialization callback.

The callback will be invoked during initialize() after all loggers are registered. Multiple callbacks can be registered and will be called in the order of registration.

Parameters

callback

Function to call during initialization

Returns

Reference to this bootstrapper for method chaining

Definition at line 361 of file system_bootstrapper.h.

                                  {
    if (callback) {
        init_callbacks_.push_back(std::move(callback));
    }
    return *this;
}

References init_callbacks_.

on_shutdown()

SystemBootstrapper & kcenon::common::bootstrap::SystemBootstrapper::on_shutdown ( std::function< void()> callback )

inline

Register a shutdown callback.

The callback will be invoked during shutdown() before loggers are cleared. Multiple callbacks can be registered and will be called in reverse order of registration (LIFO).

Parameters

callback

Function to call during shutdown

Returns

Reference to this bootstrapper for method chaining

Definition at line 369 of file system_bootstrapper.h.

                                  {
    if (callback) {
        shutdown_callbacks_.push_back(std::move(callback));
    }
    return *this;
}

References shutdown_callbacks_.

operator=() [1/2]

SystemBootstrapper & kcenon::common::bootstrap::SystemBootstrapper::operator= ( const SystemBootstrapper & )

delete

operator=() [2/2]

SystemBootstrapper & kcenon::common::bootstrap::SystemBootstrapper::operator= ( SystemBootstrapper && other )

inlinenoexcept

Definition at line 321 of file system_bootstrapper.h.

                                         {
    if (this != &other) {
        // Shutdown current state if initialized
        if (initialized_) {
            shutdown();
        }
 
        default_logger_factory_ = std::move(other.default_logger_factory_);
        named_logger_factories_ = std::move(other.named_logger_factories_);
        init_callbacks_ = std::move(other.init_callbacks_);
        shutdown_callbacks_ = std::move(other.shutdown_callbacks_);
        auto_freeze_logger_registry_ = other.auto_freeze_logger_registry_;
        auto_freeze_service_container_ = other.auto_freeze_service_container_;
        initialized_ = other.initialized_;
        other.initialized_ = false;  // Prevent double shutdown
    }
    return *this;
}

References auto_freeze_logger_registry_, auto_freeze_service_container_, default_logger_factory_, init_callbacks_, initialized_, named_logger_factories_, shutdown(), and shutdown_callbacks_.

Here is the call graph for this function:

register_loggers()

VoidResult kcenon::common::bootstrap::SystemBootstrapper::register_loggers ( )

inlineprivate

Register all loggers with GlobalLoggerRegistry.

Returns

VoidResult indicating success or error

Definition at line 458 of file system_bootstrapper.h.

                                                       {
    auto& registry = interfaces::GlobalLoggerRegistry::instance();
 
    // Register default logger
    if (default_logger_factory_) {
        auto logger = default_logger_factory_();
        if (!logger) {
            return make_error<std::monostate>(
                error_codes::INTERNAL_ERROR,
                "Default logger factory returned null",
                "bootstrap::SystemBootstrapper"
            );
        }
        auto result = registry.set_default_logger(std::move(logger));
        if (result.is_err()) {
            return result;
        }
    }
 
    // Register named loggers
    for (const auto& [name, factory] : named_logger_factories_) {
        if (!factory) {
            continue;  // Skip null factories
        }
        auto logger = factory();
        if (!logger) {
            return make_error<std::monostate>(
                error_codes::INTERNAL_ERROR,
                "Logger factory for '" + name + "' returned null",
                "bootstrap::SystemBootstrapper"
            );
        }
        auto result = registry.register_logger(name, std::move(logger));
        if (result.is_err()) {
            // Clean up already registered loggers
            clear_loggers();
            return result;
        }
    }
 
    return VoidResult::ok({});
}

References clear_loggers(), default_logger_factory_, kcenon::common::interfaces::GlobalLoggerRegistry::instance(), kcenon::common::error_codes::INTERNAL_ERROR, kcenon::common::make_error(), named_logger_factories_, and kcenon::common::Result< T >::ok().

Referenced by initialize().

Here is the call graph for this function:

Here is the caller graph for this function:

reset()

void kcenon::common::bootstrap::SystemBootstrapper::reset ( )

inline

Reset the bootstrapper to initial state.

Clears all registered factories, callbacks, and resets the initialized state. If currently initialized, shutdown() is called first.

Useful for testing or reconfiguration scenarios.

Definition at line 441 of file system_bootstrapper.h.

                                      {
    // Shutdown if initialized
    if (is_initialized()) {
        shutdown();
    }
 
    std::lock_guard<std::mutex> lock(state_mutex_);
 
    // Clear all configuration
    default_logger_factory_ = nullptr;
    named_logger_factories_.clear();
    init_callbacks_.clear();
    shutdown_callbacks_.clear();
    auto_freeze_logger_registry_ = false;
    auto_freeze_service_container_ = false;
}

References auto_freeze_logger_registry_, auto_freeze_service_container_, default_logger_factory_, init_callbacks_, is_initialized(), named_logger_factories_, shutdown(), shutdown_callbacks_, and state_mutex_.

Here is the call graph for this function:

shutdown()

void kcenon::common::bootstrap::SystemBootstrapper::shutdown ( )

inline

Shutdown the system.

Performs the following steps in order:

1. Validates that the system is initialized
2. Calls all shutdown callbacks in reverse registration order
3. Clears all loggers from GlobalLoggerRegistry
4. Marks the bootstrapper as not initialized

Note

This method is idempotent; calling it multiple times after the first call has no effect.

The destructor calls this automatically if needed.

Definition at line 419 of file system_bootstrapper.h.

                                         {
    std::lock_guard<std::mutex> lock(state_mutex_);
 
    if (!initialized_) {
        return;  // Already shutdown or never initialized
    }
 
    // Step 1: Execute shutdown callbacks in reverse order
    execute_shutdown_callbacks();
 
    // Step 2: Clear loggers from registry
    clear_loggers();
 
    // Step 3: Mark as not initialized
    initialized_ = false;
}

References clear_loggers(), execute_shutdown_callbacks(), initialized_, and state_mutex_.

Referenced by operator=(), reset(), and ~SystemBootstrapper().

Here is the call graph for this function:

Here is the caller graph for this function:

with_auto_freeze()

SystemBootstrapper & kcenon::common::bootstrap::SystemBootstrapper::with_auto_freeze ( bool freeze_logger_registry = true, bool freeze_service_container = true )

inline

Enable automatic freezing of registries after initialization.

When enabled, the GlobalLoggerRegistry and service_container::global() will be frozen after all initialization callbacks complete. This prevents unauthorized modifications to loggers and services after system startup.

Parameters

freeze_logger_registry	Whether to freeze GlobalLoggerRegistry (default: true)
freeze_service_container	Whether to freeze service_container (default: true)

Returns

Reference to this bootstrapper for method chaining

Note

This is a security feature to prevent audit log tampering and service hijacking after system initialization.

Freezing is a one-way operation and cannot be undone.

See also

Issue #206 for security requirements.

SystemBootstrapper()
    .with_default_logger(create_console_logger)
    .with_auto_freeze()  // Freeze after initialization
    .initialize();

Definition at line 377 of file system_bootstrapper.h.

                                   {
    auto_freeze_logger_registry_ = freeze_logger_registry;
    auto_freeze_service_container_ = freeze_service_container;
    return *this;
}

References auto_freeze_logger_registry_, and auto_freeze_service_container_.

with_default_logger()

SystemBootstrapper & kcenon::common::bootstrap::SystemBootstrapper::with_default_logger ( interfaces::LoggerFactory factory )

inline

Register a factory for the default logger.

The factory function will be invoked during initialize() to create the default logger. The logger will be registered with GlobalLoggerRegistry and accessible via get_logger().

Parameters

factory

Factory function that creates the default logger

Returns

Reference to this bootstrapper for method chaining

Note

If called multiple times, only the last factory is used.

Definition at line 341 of file system_bootstrapper.h.

                                     {
    default_logger_factory_ = std::move(factory);
    return *this;
}

References default_logger_factory_.

with_logger()

SystemBootstrapper & kcenon::common::bootstrap::SystemBootstrapper::with_logger ( const std::string & name, interfaces::LoggerFactory factory )

inline

Register a factory for a named logger.

The factory function will be invoked during initialize() to create the named logger. The logger will be registered with GlobalLoggerRegistry and accessible via get_logger(name).

Parameters

name	Logger name (case-sensitive)
factory	Factory function that creates the logger

Returns

Reference to this bootstrapper for method chaining

Note

If the same name is registered multiple times, only the last factory is used.

Definition at line 347 of file system_bootstrapper.h.

                                     {
    // Check if name already exists and update, otherwise add
    for (auto& entry : named_logger_factories_) {
        if (entry.first == name) {
            entry.second = std::move(factory);
            return *this;
        }
    }
    named_logger_factories_.emplace_back(name, std::move(factory));
    return *this;
}

References named_logger_factories_.

Member Data Documentation

auto_freeze_logger_registry_

bool kcenon::common::bootstrap::SystemBootstrapper::auto_freeze_logger_registry_ = false

private

Definition at line 292 of file system_bootstrapper.h.

Referenced by initialize(), operator=(), reset(), and with_auto_freeze().

auto_freeze_service_container_

bool kcenon::common::bootstrap::SystemBootstrapper::auto_freeze_service_container_ = false

private

Definition at line 293 of file system_bootstrapper.h.

Referenced by initialize(), operator=(), reset(), and with_auto_freeze().

default_logger_factory_

interfaces::LoggerFactory kcenon::common::bootstrap::SystemBootstrapper::default_logger_factory_

private

Definition at line 286 of file system_bootstrapper.h.

Referenced by operator=(), register_loggers(), reset(), and with_default_logger().

init_callbacks_

std::vector<std::function<void()> > kcenon::common::bootstrap::SystemBootstrapper::init_callbacks_

private

Definition at line 288 of file system_bootstrapper.h.

Referenced by execute_init_callbacks(), on_initialize(), operator=(), and reset().

initialized_

bool kcenon::common::bootstrap::SystemBootstrapper::initialized_ = false

private

Definition at line 296 of file system_bootstrapper.h.

Referenced by initialize(), is_initialized(), operator=(), shutdown(), and ~SystemBootstrapper().

named_logger_factories_

std::vector<std::pair<std::string, interfaces::LoggerFactory> > kcenon::common::bootstrap::SystemBootstrapper::named_logger_factories_

private

Definition at line 287 of file system_bootstrapper.h.

Referenced by operator=(), register_loggers(), reset(), and with_logger().

shutdown_callbacks_

std::vector<std::function<void()> > kcenon::common::bootstrap::SystemBootstrapper::shutdown_callbacks_

private

Definition at line 289 of file system_bootstrapper.h.

Referenced by execute_shutdown_callbacks(), on_shutdown(), operator=(), and reset().

state_mutex_

std::mutex kcenon::common::bootstrap::SystemBootstrapper::state_mutex_

mutableprivate

Definition at line 297 of file system_bootstrapper.h.

Referenced by initialize(), is_initialized(), reset(), and shutdown().

---

The documentation for this class was generated from the following file:

• include/kcenon/common/bootstrap/system_bootstrapper.h