Common System

Language: English | 한국어

Table of Contents

• Overview
• Key Features
• Quick Start
• Requirements
• Installation
• Architecture
• Core Concepts
• API Overview
• Examples
• Performance
• Ecosystem Integration
• Contributing
• License

---

Overview

A foundational C++20 header-only library providing essential interfaces and design patterns for building modular, loosely-coupled system architectures. Designed as the cornerstone of the ecosystem, it enables seamless integration between system modules while maintaining zero runtime overhead through template-based abstractions and interface-driven design.

Key Value Propositions:

• Zero-overhead abstractions: Template-based interfaces with compile-time resolution
• Well-tested: 80%+ test coverage, zero sanitizer warnings, full CI/CD
• Header-only design: No library linking, no dependencies, instant integration
• C++20 Module support: Optional module-based build for faster compilation
• Ecosystem foundation: Powers thread_system, network_system, database_system, and more

v1.0.0 — Stable API release. All public headers are frozen under SemVer guarantees. Breaking changes will only occur in future major versions (v2.0+).

API Stability

Starting with v1.0.0, common_system provides the following guarantees:

• No breaking changes to public headers within the same major version
• No removal of public functions, classes, or type aliases without a major version bump
• Stable CMake targets: common_system::common_system, kcenon::common_system, kcenon::common
• Stable #include paths: All headers under kcenon/common/ are part of the public API
• Result<T> as primary error handling: Public APIs return Result<T> instead of throwing exceptions. The unwrap() method intentionally throws when called on an error result (Rust-style panic semantics)

See VERSIONING.md for the full versioning policy and release process.

---

Key Features

Category	Feature	Description	Status
Patterns	Result	Rust-inspired monadic error handling (and_then, map, or_else)	Stable
Patterns	Circuit Breaker	Resilience pattern with CLOSED/OPEN/HALF_OPEN states	Stable
Patterns	Event Bus	Thread-safe synchronous pub/sub	Stable
Interfaces	IExecutor / IJob	Universal task execution abstraction	Stable
Interfaces	ILogger / IMetricCollector	Monitoring and logging interfaces	Stable
DI	Service Container	Thread-safe DI with singleton/transient/scoped lifetimes	Stable
Config	Config Loader / Watcher	Configuration management with file watching	Stable
Config	CLI Parser	Command-line argument parsing	Stable
Utils	Circular Buffer / Object Pool	High-performance utility data structures	Stable
Concepts	C++20 Concepts	Resultable, Unwrappable, callable, container, etc.	Stable

---

Quick Start

#include <kcenon/common/patterns/result.h>

using namespace kcenon::common;

Result<Config> load_config(const std::string& path) {
    if (!std::filesystem::exists(path)) {
        return make_error<Config>(
            error_codes::NOT_FOUND,
            "Configuration file not found",
            "config_loader"
        );
    }
    auto config = parse_json_file(path);
    return ok(config);
}

// Usage with monadic operations
auto result = load_config("app.conf")
    .and_then(validate_config)
    .map(apply_defaults);

Full Getting Started Guide

---

Requirements

Dependency	Version	Required	Description
C++20 Compiler	GCC 11+ / Clang 14+ / MSVC 2022+ / Apple Clang 14+	Yes	C++20 features (concepts)
CMake	3.28+	Yes	Build system

Compiler Requirements

common_system enforces minimum compiler versions at CMake configure time via KcenonCompilerRequirements.cmake. Downstream systems can include this module for consistent enforcement.

Build Mode	GCC	Clang	MSVC	Apple Clang
Header-only (default)	11+	14+	2022 (19.30+)	14+
C++20 Modules (optional)	14+	16+	2022 17.4 (19.34+)	Not supported

Ecosystem-Wide Compiler Requirements

When using multiple systems together, use the highest requirement from your dependency chain:

Usage Scenario	GCC	Clang	MSVC	Apple Clang	Notes
common_system only	11+	14+	2022+	14+	Baseline
+ thread_system	13+	17+	2022+	14+	Higher requirements
+ logger_system	11+	14+	2022+	14+	Optional thread_system
+ container_system	11+	14+	2022+	14+	Uses common_system
+ monitoring_system	13+	17+	2022+	14+	Requires thread_system
+ database_system	13+	17+	2022+	14+	Full ecosystem
+ network_system	13+	17+	2022+	14+	Requires thread_system

Note: If using any system that depends on thread_system, you need GCC 13+ or Clang 17+. All systems can include KcenonCompilerRequirements.cmake from common_system for automated version enforcement at configure time.

Dependency Flow

common_system (Foundation Layer - No Dependencies)
       |
       | provides interfaces to
       |
       +-- thread_system (implements IExecutor)
       +-- logger_system (uses Result<T>)
       +-- container_system (uses Result<T>)
       +-- monitoring_system (event bus)
       +-- network_system (uses IExecutor)
       +-- database_system (uses Result<T> and IExecutor)

---

Installation

Installation via vcpkg

vcpkg install kcenon-common-system

In your CMakeLists.txt:

find_package(common_system CONFIG REQUIRED)
target_link_libraries(your_target PRIVATE kcenon::common_system)

CMake FetchContent (Recommended)

include(FetchContent)
FetchContent_Declare(
    common_system
    GIT_REPOSITORY https://github.com/kcenon/common_system.git
    GIT_TAG v1.0.0
)
FetchContent_MakeAvailable(common_system)

target_link_libraries(your_target PRIVATE kcenon::common)

Header-Only Usage (Simplest)

git clone https://github.com/kcenon/common_system.git
# Include headers directly - no build required!

#include <kcenon/common/interfaces/executor_interface.h>
#include <kcenon/common/patterns/result.h>

C++20 Modules

# Build with C++20 module support (requires CMake 3.28+, Ninja, Clang 16+/GCC 14+)
cmake -G Ninja -B build -DCOMMON_BUILD_MODULES=ON
cmake --build build

import kcenon.common;

int main() {
    auto result = kcenon::common::ok(42);
    if (result.is_ok()) {
        std::cout << result.value() << std::endl;
    }
    return 0;
}

---

Architecture

Module Structure

include/kcenon/common/
  adapters/       - Adapter pattern (adapter.h, smart_adapter.h)
  bootstrap/      - System bootstrapper
  concepts/       - C++20 concepts (Resultable, Unwrappable, callable, container, etc.)
  config/         - Feature flags, ABI version, config loader/watcher, CLI parser
  di/             - Dependency injection (service_container, unified_bootstrapper)
  error/          - Error codes and error category system
  interfaces/     - Core abstractions (IExecutor, IJob, ILogger, IDatabase, IThreadPool, etc.)
  logging/        - Log functions and macros
  patterns/       - Result<T>, event_bus
  resilience/     - Circuit breaker (CLOSED/OPEN/HALF_OPEN state machine)
  utils/          - Circular buffer, object pool, enum serialization

Ecosystem Position

                    +------------------+
                    |  common_system   | <-- Foundation Layer
                    |  (interfaces)    |
                    +--------+---------+
                             | provides interfaces
       +---------------------+---------------------+
       |                     |                     |
+------v-------+    +--------v--------+   +-------v--------+
|thread_system |    |network_system   |   |monitoring_sys. |
|(implements   |    |(uses IExecutor) |   |(event bus)     |
| IExecutor)   |    +-----------------+   +----------------+
+--------------+             |                     |
       |                     |                     |
       +---------------------+---------------------+
                             | all use
                    +--------v---------+
                    | Result<T> pattern|
                    | Error handling   |
                    +------------------+

Complete Architecture Guide

---

Core Concepts

Result Pattern

Type-safe error handling without exceptions, inspired by Rust:

auto result = load_config("app.conf")
    .and_then(validate_config)
    .map(apply_defaults)
    .or_else([](const auto& error) {
        log_error(error);
        return load_fallback_config();
    });

IExecutor Interface

Universal task execution abstraction for any threading backend:

class MyService {
    std::shared_ptr<common::interfaces::IExecutor> executor_;
public:
    void process_async(const Data& data) {
        auto future = executor_->submit([data]() { return process(data); });
    }
};

Health Monitoring

Comprehensive health check system with dependency graph:

auto& monitor = global_health_monitor();
auto db_check = health_check_builder()
    .name("database")
    .type(health_check_type::dependency)
    .timeout(std::chrono::seconds{5})
    .with_check([]() { /* check logic */ })
    .build();
monitor.register_check("database", db_check.value());
monitor.add_dependency("api", "database");

Error Code Registry

Centralized error code registry providing system-specific ranges:

System	Range	Purpose
common_system	-1 to -99	Core errors
thread_system	-100 to -199	Threading errors
logger_system	-200 to -299	Logging errors
monitoring_system	-300 to -399	Monitoring errors
container_system	-400 to -499	Container errors
database_system	-500 to -599	Database errors
network_system	-600 to -699	Network errors

Circuit Breaker

Resilience pattern for fault tolerance:

auto breaker = circuit_breaker("db_connection", {
    .failure_threshold = 5,
    .recovery_timeout = std::chrono::seconds{30}
});
auto result = breaker.execute([&]() { return db.query("SELECT 1"); });

---

API Overview

Component	Purpose	Header
Result<T> / VoidResult	Monadic error handling	patterns/result.h
IExecutor / IJob	Task execution interface	interfaces/executor_interface.h
ILogger	Logging abstraction	interfaces/logger_interface.h
service_container	Dependency injection	di/service_container.h
simple_event_bus	Synchronous pub/sub	patterns/event_bus.h
circuit_breaker	Resilience pattern	resilience/circuit_breaker.h
config_loader	Configuration management	config/config_loader.h
circular_buffer	Fixed-size ring buffer	utils/circular_buffer.h
object_pool	Object pooling	utils/object_pool.h

Complete API Reference

---

Examples

Example	Description	Difficulty
result_example	Result error handling patterns	Beginner
executor_example	Executor interface and thread management	Beginner
abi_version_example	ABI version checking and compatibility	Intermediate
unwrap_demo	Result unwrapping and chaining	Intermediate
multi_system_app	Multi-system integration example	Advanced

Running Examples

cmake -B build -DCOMMON_BUILD_EXAMPLES=ON
cmake --build build
./build/examples/result_example

---

Performance

Operation	Time (ns)	Allocations	Notes
Result creation	2.3	0	Stack-only operation
Result error check	0.8	0	Single bool check
IExecutor submit	45.2	1	Task queue insertion
Event publish	12.4	0	Lock-free operation

Key Performance Characteristics:

• Result is 400x faster than exceptions in error paths
• IExecutor is 53x faster than std::async for high-frequency tasks
• Zero-overhead abstractions - compiler optimizes away all abstraction layers

Quality Metrics:

• Test coverage: 80%+ (target: 85%)
• Sanitizer tests: 18/18 passing with zero warnings
• Cross-platform: Ubuntu, macOS, Windows
• Zero memory leaks: AddressSanitizer verified
• Zero data races: ThreadSanitizer verified
• RAII Grade: A - All resources managed through smart pointers

Full Benchmarks

---

Ecosystem Integration

Ecosystem Dependency Map

graph TD
    A[common_system] --> B[thread_system]
    A --> C[container_system]
    B --> D[logger_system]
    B --> E[monitoring_system]
    D --> F[database_system]
    E --> F
    F --> G[network_system]
    G --> H[pacs_system]

    style A fill:#f9f,stroke:#333,stroke-width:3px

Loading

Ecosystem reference: thread_system — Tier 1: Implements IExecutor interface container_system — Tier 1: Uses Result<T> for error handling logger_system — Tier 2: Uses ILogger, Result<T> monitoring_system — Tier 3: Uses event bus, IMonitor database_system — Tier 3: Uses Result<T>, IExecutor network_system — Tier 4: Uses IExecutor, Result<T> pacs_system — Tier 5: Full ecosystem consumer

Ecosystem CI Verification

The Ecosystem vcpkg Integration workflow validates that all 8 ecosystem ports install and build correctly as a consumer would experience them. It tests each port in bottom-up dependency order (Layer 0 through Layer 7) on Ubuntu and macOS, running on every PR that touches vcpkg ports and nightly at 03:00 UTC.

This common system serves as the foundational layer (Tier 0) that all other system modules build upon:

common_system (Tier 0 - Foundation)
       |
       +-- thread_system     (Tier 1) - Implements IExecutor
       +-- container_system  (Tier 1) - Uses Result<T>
       +-- logger_system     (Tier 2) - Uses ILogger, Result<T>
       +-- monitoring_system (Tier 3) - Uses Event Bus
       +-- database_system   (Tier 3) - Uses Result<T>, IExecutor
       +-- network_system    (Tier 4) - Uses IExecutor
       +-- pacs_system       (Tier 5) - Full ecosystem consumer

Integration Example

// Any ecosystem project can use common_system interfaces
#include <kcenon/common/patterns/result.h>
#include <kcenon/common/interfaces/executor_interface.h>

// Result<T> is the universal error handling pattern
auto result = do_something();
if (result.is_err()) {
    // Consistent error handling across all projects
    auto error = result.error();
    std::cerr << error.message << " (code: " << error.code << ")\n";
}

Documentation

Category	Document	Description
Guides	Quick Start	Get up and running in minutes
	Best Practices	Recommended usage patterns
	FAQ	Frequently asked questions
	Troubleshooting	Common issues and solutions
Advanced	Architecture	System design and principles
	Migration	Version upgrade guide
	IExecutor Migration	Executor API migration
	Runtime Binding	Core design pattern
Contributing	Contributing	How to contribute
	Error Code Guidelines	Error code management

---

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick Links

• Development Setup
• Code Style
• Pull Request Process

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: kcenon@naver.com

---

License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

---

Made with care by the kcenon team