kcenon::common Namespace Reference

Core interfaces. More...

Namespaces
namespace	adapters
namespace	bootstrap
namespace	concepts
	C++20 concepts for compile-time type validation.
namespace	config
namespace	detail
namespace	di
namespace	error
namespace	error_codes
namespace	events
namespace	helpers
namespace	interfaces
namespace	logging
namespace	patterns
namespace	resilience
namespace	utils

Classes
class	common_error_category
	Error category for common/shared error codes. More...
struct	database_null
	Represents NULL values in database results. More...
struct	enum_traits
	Primary template for enum traits (must be specialized for each enum) More...
struct	enum_traits< interfaces::health_check_type >
	Specialization of enum_traits for health_check_type. More...
struct	enum_traits< interfaces::health_status >
	Specialization of enum_traits for health_status. More...
struct	enum_traits< interfaces::log_level >
	Specialization of enum_traits for log_level. More...
struct	enum_traits< interfaces::metric_type >
	Specialization of enum_traits for metric_type. More...
class	error_category
	Abstract base class for error code categories. More...
struct	error_info
	Standard error information used by Result<T>. More...
struct	event
	Generic event structure for the event bus. More...
class	exception_mapper
	Maps standard exception types to appropriate error codes. More...
struct	module_version
	Version information for common_system module. More...
class	Option
class	Optional
	Optional type similar to std::optional with Rust-like API. More...
class	Result
	Result type for error handling with member function support. More...
class	simple_event_bus
	Simple synchronous event bus for testing when monitoring is disabled. More...
struct	source_location
	C++17-compatible source_location implementation using compiler builtins. More...
class	typed_error_code
	A type-safe error code that carries its category. More...
struct	version_info
	Version information for Common System. More...

Concepts
concept	EnumSerializable
	Concept to check if an enum has valid traits defined.

Typedefs
using	database_value = std::variant<database_null, std::string, std::int64_t, double, bool>
	Variant type for database column values.
using	database_row = std::map<std::string, database_value>
	Map of column names to values representing a database row.
using	database_result = std::vector<database_row>
	Vector of rows representing a complete query result set.
using	subscription_id = uint64_t
	Type alias for subscription ID.
using	event_bus = simple_event_bus
template<typename T >
using	event_handler = std::function<void(const T&)>
using	kcenon::common::VoidResult = Result<std::monostate>
	Specialized Result for void operations.

Enumerations
enum class	event_priority { low = 0 , normal = 1 , high = 2 }
enum class	result_state {   uninitialized , ok , error , uninitialized ,   ok , error }
	Result state enum for tracking initialization. More...
enum class	kcenon::common::result_state {   uninitialized , ok , error , uninitialized ,   ok , error }
	Result state enum for tracking initialization. More...

Functions
typed_error_code	make_typed_error_code (common_error_category::codes code) noexcept
	Creates a typed_error_code from common_error_category::codes enum.
template<typename Category >
typed_error_code	make_typed_error_code (int code) noexcept
	Creates a typed_error_code from a code value and category.
bool	is_success (const typed_error_code &ec) noexcept
	Checks if a typed_error_code represents success (no error).
bool	is_error (const typed_error_code &ec) noexcept
	Checks if a typed_error_code represents an error.
simple_event_bus &	get_event_bus ()
	Access the global event bus instance.
bool	verify_event_bus_abi (int expected_version)
	Verify ABI compatibility between modules.
template<typename T >
Optional< T >	kcenon::common::Some (T value)
	Create an Optional with value.
template<typename T >
Optional< T >	kcenon::common::None ()
	Create an empty Optional.
template<typename T >
Result< T >	kcenon::common::ok (T value)
	Create a successful result.
VoidResult	kcenon::common::ok ()
	Create a successful void result.
template<typename T >
Result< T >	kcenon::common::make_error (int code, const std::string &message, const std::string &module="")
	Create an error result with code and message.
template<typename T >
Result< T >	kcenon::common::make_error (int code, const std::string &message, const std::string &module, const std::string &details)
	Create an error result with details.
template<typename T >
Result< T >	kcenon::common::make_error (const error_info &err)
	Create an error result from existing error_info.
template<typename T , typename F >
Result< T >	kcenon::common::try_catch (F &&func, const std::string &module="")
	Convert exception to Result with automatic error code mapping.
template<typename F >
VoidResult	kcenon::common::try_catch_void (F &&func, const std::string &module="")
	Convert exception to VoidResult with automatic error code mapping.
template<EnumSerializable Enum>
std::string	enum_to_string (Enum value)
	Convert an enum value to its string representation.
template<EnumSerializable Enum>
Result< Enum >	enum_from_string (std::string_view str)
	Convert a string to its enum value (case-insensitive)
VoidResult	kcenon::common::err (const error_info &error)
	Factory function to create error VoidResult.
VoidResult	kcenon::common::err (int code, const std::string &message, const std::string &module="")
	Factory function to create error VoidResult.

Detailed Description

Core interfaces.

Unified logging (Issue #175) Bootstrap (Issue #176) Common patterns Common utilities

Typedef Documentation

database_result

using kcenon::common::database_result = std::vector<database_row>

Vector of rows representing a complete query result set.

Definition at line 51 of file database_interface.h.

database_row

using kcenon::common::database_row = std::map<std::string, database_value>

Map of column names to values representing a database row.

Definition at line 45 of file database_interface.h.

database_value

using kcenon::common::database_value = std::variant<database_null, std::string, std::int64_t, double, bool>

Variant type for database column values.

Supports NULL, string, 64-bit integer, double, and boolean types.

Definition at line 39 of file database_interface.h.

event_bus

using kcenon::common::event_bus = simple_event_bus

Definition at line 443 of file event_bus.h.

event_handler

template<typename T >

using kcenon::common::event_handler = std::function<void(const T&)>

Definition at line 446 of file event_bus.h.

subscription_id

using kcenon::common::subscription_id = uint64_t

Type alias for subscription ID.

Definition at line 105 of file event_bus.h.

VoidResult

typedef Result< std::monostate > kcenon::common::VoidResult = Result<std::monostate>

export

Specialized Result for void operations.

Forward declaration of VoidResult typedef. Full definition in void_result.h.

Examples

executor_example.cpp.

Definition at line 70 of file core.h.

Enumeration Type Documentation

event_priority

enum class kcenon::common::event_priority

strong

Enumerator
low
normal
high

Definition at line 96 of file event_bus.h.

                              {
        low = 0,
        normal = 1,
        high = 2
    };

result_state [1/2]

enum class kcenon::common::result_state

strong

Result state enum for tracking initialization.

Enumerator
uninitialized
ok
error
uninitialized	Result has not been initialized with a value or error.
ok	Result contains a valid value.
error	Result contains an error.

Definition at line 58 of file core.h.

                        {
    uninitialized,  // Result has not been initialized with a value or error
    ok,             // Result contains a valid value
    error           // Result contains an error
};

result_state [2/2]

enum class kcenon::common::result_state

exportstrong

Result state enum for tracking initialization.

Enumerator
uninitialized
ok
error
uninitialized	Result has not been initialized with a value or error.
ok	Result contains a valid value.
error	Result contains an error.

Definition at line 87 of file core.cppm.

                        {
    uninitialized,  
    ok,             
    error           
};

Function Documentation

enum_from_string()

template<EnumSerializable Enum>

Result< Enum > kcenon::common::enum_from_string ( std::string_view str )

inlinenodiscard

Convert a string to its enum value (case-insensitive)

Template Parameters

Enum	The enum type (must satisfy EnumSerializable concept)

Parameters

str	The string to convert

Returns

Result containing the enum value or error

Definition at line 93 of file enum_serialization.h.

                                                                       {
    // Convert input to uppercase for case-insensitive comparison
    std::string upper(str.size(), '\0');
    std::transform(str.begin(), str.end(), upper.begin(),
                   [](unsigned char c) { return static_cast<char>(std::toupper(c)); });
 
    for (const auto& [e, s] : enum_traits<Enum>::values) {
        if (s == upper) {
            return Result<Enum>::ok(e);
        }
    }
 
    return Result<Enum>::err(
        error_info{1, "Invalid enum value: " + std::string(str),
                   std::string(enum_traits<Enum>::module_name)});
}

References kcenon::common::Result< T >::err(), and kcenon::common::Result< T >::ok().

Referenced by kcenon::common::interfaces::from_string(), kcenon::common::interfaces::health_check_type_from_string(), and kcenon::common::interfaces::metric_type_from_string().

Here is the call graph for this function:

Here is the caller graph for this function:

enum_to_string()

template<EnumSerializable Enum>

std::string kcenon::common::enum_to_string ( Enum value )

inlinenodiscard

Convert an enum value to its string representation.

Template Parameters

Enum	The enum type (must satisfy EnumSerializable concept)

Parameters

value

The enum value to convert

Returns

String representation, or "UNKNOWN" if not found

Definition at line 76 of file enum_serialization.h.

                                                          {
    for (const auto& [e, s] : enum_traits<Enum>::values) {
        if (e == value) {
            return std::string(s);
        }
    }
    return "UNKNOWN";
}

Referenced by kcenon::common::interfaces::to_string(), kcenon::common::interfaces::to_string(), kcenon::common::interfaces::to_string(), and kcenon::common::interfaces::to_string().

Here is the caller graph for this function:

err() [1/2]

VoidResult kcenon::common::err ( const error_info & error )

inlineexport

Factory function to create error VoidResult.

Parameters

error

The error information

Returns

VoidResult containing the error

Examples

executor_example.cpp.

Definition at line 432 of file core.cppm.

                                               {
    return VoidResult(error);
}

Referenced by mock_executor::execute(), mock_executor::execute_delayed(), main(), and make_error().

Here is the caller graph for this function:

err() [2/2]

VoidResult kcenon::common::err ( int code, const std::string & message, const std::string & module = "" )

inlineexport

Factory function to create error VoidResult.

Parameters

code	Error code
message	Error message
module	Module name (optional)

Returns

VoidResult containing the error

Definition at line 443 of file core.cppm.

                                                                                        {
    return VoidResult(error_info{code, message, module});
}

get_event_bus()

simple_event_bus & kcenon::common::get_event_bus ( )

inline

Access the global event bus instance.

Returns

Reference to the singleton event bus

Definition at line 452 of file event_bus.h.

                                             {
        return simple_event_bus::instance();
    }

References kcenon::common::simple_event_bus::instance().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

is_error()

bool kcenon::common::is_error ( const typed_error_code & ec )

inlinenoexcept

Checks if a typed_error_code represents an error.

Parameters

ec	The error code to check

Returns

true if the error code represents an error

Definition at line 428 of file error_category.h.

                                                          {
    return ec.value() != 0;
}

is_success()

bool kcenon::common::is_success ( const typed_error_code & ec )

inlinenoexcept

Checks if a typed_error_code represents success (no error).

Parameters

ec	The error code to check

Returns

true if the error code represents success

Definition at line 418 of file error_category.h.

                                                            {
    return ec.value() == 0;
}

make_error() [1/3]

template<typename T >

Result< T > kcenon::common::make_error ( const error_info & err )

inlineexport

Create an error result from existing error_info.

Definition at line 110 of file utilities.h.

                                                   {
    return Result<T>(err);
}

References err().

Here is the call graph for this function:

make_error() [2/3]

template<typename T >

Result< T > kcenon::common::make_error ( int code, const std::string & message, const std::string & module, const std::string & details )

inlineexport

Create an error result with details.

Definition at line 100 of file utilities.h.

                                                      {
    return Result<T>(error_info{code, message, module, details});
}

make_error() [3/3]

template<typename T >

Result< T > kcenon::common::make_error ( int code, const std::string & message, const std::string & module = "" )

inlineexport

Create an error result with code and message.

Parameters

code	Error code
message	Error message
module	Optional module name

Returns

Result<T> containing the error

Note

RECOMMENDED: This is the preferred way to create error results.

Example:

return make_error<int>(error_codes::INVALID_ARGUMENT, "Value must be positive");
return make_error<int>(error_codes::NOT_FOUND, "Resource not found", "database");

Parameters

code	Error code
message	Error message
module	Optional module name

Returns

Result<T> containing the error

Definition at line 91 of file utilities.h.

                                                          {
    return Result<T>(error_info{code, message, module});
}

Referenced by kcenon::common::config::cli_config_parser::apply_override(), kcenon::common::di::service_container::check_already_registered(), kcenon::common::di::service_container::check_frozen_for_registration(), kcenon::common::di::service_container::clear(), divide(), divide(), kcenon::common::config::config_watcher::do_reload(), kcenon::common::config::config_watcher::init_platform_watcher(), kcenon::common::bootstrap::SystemBootstrapper::initialize(), kcenon::common::di::service_container::invoke_factory_safe(), kcenon::common::config::config_loader::load(), kcenon::common::config::config_loader::load_from_env(), kcenon::common::config::config_loader::load_from_string(), kcenon::common::config::cli_config_parser::load_with_cli_overrides(), main(), kcenon::common::config::cli_config_parser::parse(), parse_and_compute(), kcenon::common::config::cli_config_parser::parse_key_value(), read_file(), kcenon::common::interfaces::GlobalLoggerRegistry::register_factory(), kcenon::common::di::IServiceContainer::register_instance(), kcenon::common::interfaces::GlobalLoggerRegistry::register_logger(), kcenon::common::bootstrap::SystemBootstrapper::register_loggers(), kcenon::common::di::unified_bootstrapper::register_module(), kcenon::common::di::unified_bootstrapper::register_optional_services(), kcenon::common::di::unified_bootstrapper::register_shutdown_hook(), register_user(), kcenon::common::di::IServiceContainer::resolve(), kcenon::common::di::service_container::resolve_with_detection(), kcenon::common::config::config_watcher::rollback(), kcenon::common::interfaces::GlobalLoggerRegistry::set_default_factory(), kcenon::common::interfaces::GlobalLoggerRegistry::set_default_logger(), kcenon::common::di::unified_bootstrapper::shutdown(), kcenon::common::config::config_watcher::start(), kcenon::common::di::service_container::unregister_internal(), kcenon::common::interfaces::GlobalLoggerRegistry::unregister_logger(), kcenon::common::di::unified_bootstrapper::unregister_module(), kcenon::common::di::unified_bootstrapper::unregister_shutdown_hook(), and kcenon::common::config::config_loader::validate().

Here is the caller graph for this function:

make_typed_error_code() [1/2]

typed_error_code kcenon::common::make_typed_error_code ( common_error_category::codes code )

inlinenoexcept

Creates a typed_error_code from common_error_category::codes enum.

Parameters

code	Common error code enum value

Returns

typed_error_code with common_error_category

Definition at line 396 of file error_category.h.

                                                                                        {
    return typed_error_code(static_cast<int>(code), common_error_category::instance());
}

References kcenon::common::common_error_category::instance().

Here is the call graph for this function:

make_typed_error_code() [2/2]

template<typename Category >

typed_error_code kcenon::common::make_typed_error_code ( int code )

noexcept

Creates a typed_error_code from a code value and category.

Template Parameters

Category

The error category type (must have instance() method)

Parameters

code	Error code value

Returns

typed_error_code with the specified category

Definition at line 408 of file error_category.h.

                                                          {
    return typed_error_code(code, Category::instance());
}

None()

template<typename T >

Optional< T > kcenon::common::None ( )

inlineexport

Create an empty Optional.

Definition at line 546 of file core.h.

                          {
    return Optional<T>(std::nullopt);
}

ok() [1/2]

VoidResult kcenon::common::ok ( )

inlineexport

Create a successful void result.

Factory function to create successful VoidResult.

Note

RECOMMENDED: Use for functions that don't return a value.

Example:

VoidResult save_data() {
    // ... save logic ...
    return ok();
}

Returns

VoidResult containing std::monostate (success indicator)

Examples

executor_example.cpp.

Definition at line 71 of file utilities.h.

                       {
    return VoidResult(std::monostate{});
}

Referenced by kcenon::common::interfaces::health_dependency_graph::add_dependency(), kcenon::common::interfaces::health_dependency_graph::add_node(), kcenon::common::interfaces::health_check_builder::build(), kcenon::common::interfaces::health_dependency_graph::check_with_dependencies_internal(), divide(), divide(), mock_executor::execute(), mock_executor::execute_delayed(), kcenon::common::logging::ConsoleLogger::flush(), kcenon::common::di::service_container::invoke_factory_safe(), kcenon::common::logging::ConsoleLogger::log(), kcenon::common::logging::ConsoleLogger::log(), main(), kcenon::common::config::cli_config_parser::parse_key_value(), read_file(), register_user(), kcenon::common::interfaces::health_dependency_graph::remove_dependency(), kcenon::common::interfaces::health_dependency_graph::remove_node(), kcenon::common::di::IServiceContainer::resolve(), kcenon::common::di::service_container::resolve_with_detection(), kcenon::common::logging::ConsoleLogger::set_level(), kcenon::common::interfaces::health_monitor::start(), kcenon::common::interfaces::health_monitor::stop(), kcenon::common::interfaces::health_dependency_graph::topological_sort(), try_catch(), and try_catch_void().

Here is the caller graph for this function:

ok() [2/2]

template<typename T >

Result< T > kcenon::common::ok ( T value )

inlineexport

Create a successful result.

Create a successful result with a value.

Parameters

value

The value to wrap

Returns

Result<T> containing the value

Note

RECOMMENDED: This is the preferred way to create successful results.

Example:

auto result = ok(42);
auto str_result = ok(std::string("hello"));

Parameters

value

The value to wrap

Returns

Result<T> containing the value

Note

For VoidResult (successful void result), use the ok() function exported from :result.core partition.

Definition at line 54 of file utilities.h.

                             {
    return Result<T>(std::move(value));
}

Some()

template<typename T >

Optional< T > kcenon::common::Some ( T value )

inlineexport

Create an Optional with value.

Definition at line 538 of file core.h.

                                 {
    return Optional<T>(std::move(value));
}

try_catch()

template<typename T , typename F >

Result< T > kcenon::common::try_catch ( F && func, const std::string & module = "" )

export

Convert exception to Result with automatic error code mapping.

Enhanced version that automatically assigns appropriate error codes based on exception type, providing better error diagnostics. Uses multiple catch blocks instead of RTTI for better performance.

Template Parameters

T	Return type
F	Callable type

Parameters

func	Callable to execute
module	Module name for error context

Returns

Result<T> with value or mapped error

Example:

auto result = try_catch<int>([]() {
    return parse_integer("invalid");  // throws std::invalid_argument
}, "parser");
// result contains error with code INVALID_ARGUMENT

Template Parameters

T	Return type
F	Callable type

Parameters

func	Callable to execute
module	Module name for error context

Returns

Result<T> with value or mapped error

Definition at line 173 of file utilities.h.

                                                            {
    try {
        return ok<T>(func());
    }
    // Memory allocation failure
    catch (const std::bad_alloc& e) {
        return Result<T>(error_info{error_codes::OUT_OF_MEMORY, e.what(), module, "std::bad_alloc"});
    }
    // Invalid argument (check before logic_error)
    catch (const std::invalid_argument& e) {
        return Result<T>(error_info{error_codes::INVALID_ARGUMENT, e.what(), module, "std::invalid_argument"});
    }
    // Out of range (check before logic_error)
    catch (const std::out_of_range& e) {
        return Result<T>(error_info{error_codes::INVALID_ARGUMENT, e.what(), module, "std::out_of_range"});
    }
    // System errors (check before runtime_error as it inherits from it)
    catch (const std::system_error& e) {
        return Result<T>(error_info{e.code().value(), e.what(), module,
                        std::string("std::system_error: ") + e.code().category().name()});
    }
    // Logic errors
    catch (const std::logic_error& e) {
        return Result<T>(error_info{error_codes::INTERNAL_ERROR, e.what(), module, "std::logic_error"});
    }
    // Runtime errors
    catch (const std::runtime_error& e) {
        return Result<T>(error_info{error_codes::INTERNAL_ERROR, e.what(), module, "std::runtime_error"});
    }
    // Generic std::exception
    catch (const std::exception& e) {
        return Result<T>(exception_mapper::map_generic_exception(e, module));
    }
    // Unknown exception
    catch (...) {
        return Result<T>(exception_mapper::map_unknown_exception(module));
    }
}

References kcenon::common::error_codes::INTERNAL_ERROR, kcenon::common::error_codes::INVALID_ARGUMENT, kcenon::common::exception_mapper::map_generic_exception(), kcenon::common::exception_mapper::map_unknown_exception(), ok(), and kcenon::common::error_codes::OUT_OF_MEMORY.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

try_catch_void()

template<typename F >

VoidResult kcenon::common::try_catch_void ( F && func, const std::string & module = "" )

export

Convert exception to VoidResult with automatic error code mapping.

Specialization for void return type. Uses multiple catch blocks instead of RTTI for better performance.

Template Parameters

F	Callable type

Parameters

func	Callable to execute (returns void)
module	Module name for error context

Returns

VoidResult with success or mapped error

Template Parameters

F	Callable type

Parameters

func	Callable to execute (returns void)
module	Module name for error context

Returns

VoidResult with success or mapped error

Definition at line 224 of file utilities.h.

                                                                  {
    try {
        func();
        return ok();
    }
    // Memory allocation failure
    catch (const std::bad_alloc& e) {
        return VoidResult(error_info{error_codes::OUT_OF_MEMORY, e.what(), module, "std::bad_alloc"});
    }
    // Invalid argument (check before logic_error)
    catch (const std::invalid_argument& e) {
        return VoidResult(error_info{error_codes::INVALID_ARGUMENT, e.what(), module, "std::invalid_argument"});
    }
    // Out of range (check before logic_error)
    catch (const std::out_of_range& e) {
        return VoidResult(error_info{error_codes::INVALID_ARGUMENT, e.what(), module, "std::out_of_range"});
    }
    // System errors (check before runtime_error as it inherits from it)
    catch (const std::system_error& e) {
        return VoidResult(error_info{e.code().value(), e.what(), module,
                        std::string("std::system_error: ") + e.code().category().name()});
    }
    // Logic errors
    catch (const std::logic_error& e) {
        return VoidResult(error_info{error_codes::INTERNAL_ERROR, e.what(), module, "std::logic_error"});
    }
    // Runtime errors
    catch (const std::runtime_error& e) {
        return VoidResult(error_info{error_codes::INTERNAL_ERROR, e.what(), module, "std::runtime_error"});
    }
    // Generic std::exception
    catch (const std::exception& e) {
        return VoidResult(exception_mapper::map_generic_exception(e, module));
    }
    // Unknown exception
    catch (...) {
        return VoidResult(exception_mapper::map_unknown_exception(module));
    }
}

References kcenon::common::error_codes::INTERNAL_ERROR, kcenon::common::error_codes::INVALID_ARGUMENT, kcenon::common::exception_mapper::map_generic_exception(), kcenon::common::exception_mapper::map_unknown_exception(), ok(), and kcenon::common::error_codes::OUT_OF_MEMORY.

Here is the call graph for this function:

verify_event_bus_abi()

bool kcenon::common::verify_event_bus_abi ( int expected_version )

inline

Verify ABI compatibility between modules.

Call this function during initialization to verify that all linked modules were compiled with the same event_bus configuration. This helps catch subtle bugs caused by mixing object files compiled with different settings.

Parameters

expected_version

The ABI version your module expects

Returns

true if compatible, false otherwise

Example usage:

// In your module initialization:
if (!common::verify_event_bus_abi(common::detail::event_bus_abi_version)) {
    // Handle ABI mismatch error
    throw std::runtime_error("Event bus ABI mismatch detected!");
}

Definition at line 493 of file event_bus.h.

                                                           {
        return detail::get_event_bus_abi_version() == expected_version;
    }

References kcenon::common::detail::get_event_bus_abi_version().

Here is the call graph for this function: