Language: English | 한국어

• Overview
• Quick Start
• Core Features
• Performance Highlights
• Architecture Overview
• C++20 Module Support
• Documentation
• Value Types
• Ecosystem Integration
• Platform Support
• Thread Safety
• Error Handling
• API Stability
• Contributing
• License

The Container System is a high-performance C++20 type-safe container framework designed for comprehensive data management in messaging systems and general-purpose applications. Built with a modular, interface-based architecture featuring SIMD optimizations and seamless ecosystem integration.

Key Highlights:

• Type Safety: Strongly-typed value system with compile-time checks
• High Performance: SIMD-accelerated operations (1.8M serializations/sec, 25M SIMD ops/sec)
• Well-Tested: Perfect RAII score (20/20), zero data races, comprehensive testing
• Cross-Platform: Native support for Linux, macOS, Windows with optimized build scripts
• Multiple Formats: Binary, JSON, XML, MessagePack serialization with automatic format detection

Making high-performance data serialization accessible, type-safe, and efficient for developers worldwide.

container_system provides container-specific optimizations for common_system:

• fast_parser.h: High-performance parsing optimizations for serialization formats
• Dependencies on common_system are managed via CMake FetchContent

container_system is a high-performance serializable data container library that provides:

1. Type-safe key-value storage: Store and retrieve heterogeneous data with compile-time type safety
2. Multiple serialization formats: Binary, JSON, and XML with automatic format detection
3. SIMD-optimized operations: Hardware-accelerated processing for numeric arrays and batch operations
4. Messaging system integration: Native support for building structured messages for inter-process communication

Use container_system for:

• Building type-safe message payloads for messaging systems
• High-performance data serialization (1.8M ops/sec)
• Cross-platform data interchange with format flexibility
• Applications requiring SIMD-accelerated container operations
• Systems needing thread-safe concurrent data access

Use common_system instead for:

• General utilities (logging, error handling, configuration management)
• Dependency injection infrastructure
• Abstract interfaces and design patterns
• Cross-cutting concerns (adapters, bootstrap, utilities)

common_system (Foundation)
       │
       │ depends on
       ▼
container_system (Data Serialization)
       │
       │ used by
       ▼
messaging_system, network_system, database_system

• common_system: Provides foundational infrastructure (DI, logging, error handling, interfaces)
• container_system: Specializes in high-performance data containers and serialization
• Other systems: Consume container_system for data exchange and storage

vcpkg install kcenon-container-system

In your CMakeLists.txt:

find_package(container_system CONFIG REQUIRED)
target_link_libraries(your_target PRIVATE container_system::container)

#include <container/container.h>  // Canonical include path

using namespace container_module;

int main() {
    // Create container using builder pattern
    auto container = messaging_container_builder()
        .source("trading_engine", "session_001")
        .target("risk_monitor", "main")
        .message_type("market_data")
        .add_value("symbol", "AAPL")
        .add_value("price", 175.50)
        .add_value("volume", 1000000)
        .optimize_for_speed()
        .build();

    // High-performance binary serialization
    std::string binary_data = container->serialize();  // 1.8M ops/sec

    // Human-readable JSON
    std::string json_data = container->to_json();

    // Deserialize
    auto restored = std::make_shared<value_container>(binary_data);
    auto price = restored->get_value("price");

    return 0;
}

container_system has a minimal dependency architecture - the cleanest in the ecosystem:

container_system
       │
       ▼
common_system (ONLY required ecosystem dependency)

Optional module boundary: The repository also contains an isolated grpc/ subproject that is not built by the root CMakeLists.txt. It is a separately scoped deliverable with its own gRPC/protobuf dependency path.

Why this matters:

• Faster compilation times
• Easier testing and debugging
• Clear architectural boundaries
• Reduced coupling with other modules

📖 Minimal Dependency Architecture →

SBOM artifacts treat grpc/ as a module-scoped optional deliverable. The root package dependency inventory covers vcpkg.json, and the SBOM report adds a separate section for the isolated gRPC build path when that module is relevant.

cmake -S grpc -B build-grpc
cmake --build build-grpc

container_system automatically fetches common_system using CMake FetchContent during build. No manual dependency cloning required.

# Clone container_system
git clone https://github.com/kcenon/container_system.git
cd container_system

# Build (common_system will be fetched automatically)
./scripts/build.sh           # Linux/macOS
# or
scripts\build.bat            # Windows (CMD)
.\scripts\build.ps1          # Windows (PowerShell)

# Run examples
./build/examples/basic_container_example

If you're developing both container_system and common_system simultaneously:

# Clone both repositories as siblings
git clone https://github.com/kcenon/common_system.git
git clone https://github.com/kcenon/container_system.git

cd container_system

# CMake will detect ../common_system automatically
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

The build system searches for common_system in this order:

1. Cache variable: COMMON_SYSTEM_ROOT (CMake option)
2. Environment variable: $COMMON_SYSTEM_ROOT
3. Sibling directory: ../common_system (local development)
4. Subdirectory: ./common_system (CI/CD)
5. FetchContent: Automatic download from GitHub (default)

To force FetchContent:

cmake -S . -B build -DUNIFIED_ALLOW_FETCHCONTENT=ON

To use a specific common_system location:

cmake -S . -B build -DCOMMON_SYSTEM_ROOT=/path/to/common_system

For offline or airgapped environments, pre-populate the CMake FetchContent cache:

# Pre-fetch dependencies
cmake -S . -B build_deps -DCMAKE_BUILD_TYPE=Release

# Later, build offline using the cache
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DFETCHCONTENT_FULLY_DISCONNECTED=ON
cmake --build build

• 16 built-in types: From null to nested containers and typed arrays
• Compile-time checks: Template metaprogramming ensures type safety
• Runtime validation: Type checking during deserialization
• Zero overhead: No runtime cost for type safety

• Binary format: 1.8M ops/sec with ~10% overhead
• JSON format: 950K ops/sec, human-readable
• XML format: 720K ops/sec with schema validation
• Auto-detection: Automatic format identification

• ARM NEON: 3.2x speedup on Apple Silicon (M1/M2/M3)
• x86 AVX2: 2.5x speedup on Intel/AMD processors
• Auto-detection: Platform-specific optimization selection
• 25M ops/sec: Numeric array processing throughput

• Lock-free reads: Concurrent read operations without synchronization
• Thread-safe wrapper: Optional thread_safe_container for writes
• Linear scaling: 7.5x throughput with 8 threads
• Zero data races: ThreadSanitizer validated

• Perfect RAII: 20/20 score (Grade A+), highest in ecosystem
• Zero memory leaks: AddressSanitizer clean
• Zero data races: ThreadSanitizer validated
• 123+ tests: Comprehensive test coverage
• 85%+ coverage: Line coverage with continuous monitoring

📚 Complete Features →

Benchmarks on Apple M1 (8 cores, ARM NEON), macOS 26.1, Release build

Platform Comparison:

⚡ Full Benchmarks →

                    ┌─────────────────┐
                    │  common_system  │
                    │  (Foundation)   │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │container_system │
                    │(Data Containers)│
                    └────────┬────────┘
                             │ used by
       ┌─────────────────────┼─────────────────────┐
       │                     │                     │
       ▼                     ▼                     ▼
┌──────────────┐    ┌────────────────┐    ┌──────────────┐
│network_system│    │database_system │    │Other systems │
└──────────────┘    └────────────────┘    └──────────────┘

container_system has minimal dependencies - only common_system is required. This makes it ideal as a foundational data layer for the ecosystem.

Integration Benefits:

• Type-safe data containers: Prevents runtime errors with compile-time checks
• Performance-optimized: SIMD acceleration for high-throughput operations
• Universal serialization: Binary, JSON, XML for diverse integration needs
• Unified data model: Consistent structure across the entire ecosystem

🏗️ Architecture Guide →

Container System provides C++20 module support as an alternative to the header-based interface.

• CMake 3.28+
• Clang 16+, GCC 14+, or MSVC 2022 17.4+
• common_system with module support

cmake -B build -DCONTAINER_BUILD_MODULES=ON
cmake --build build

import kcenon.container;

int main() {
    // Use container components directly
    auto container = kcenon::container::value_container();
    container.set("key", "value");
}

Note: C++20 modules are experimental. The header-based interface remains the primary API.

• 📖 Quick Start Guide
• 🔍 Troubleshooting
• 📋 FAQ - Frequently asked questions

• 📚 Features - Complete feature documentation
• ⚡ Benchmarks - Performance analysis
• 📦 Project Structure - Code organization
• 🏆 Production Quality - Quality metrics

• 🏛️ Architecture - System design and patterns
• 📘 API Reference - Complete API documentation
• 🚀 Performance - SIMD optimization guide
• 🔗 Integration - Ecosystem integration

• 🔄 Migration - Migration from messaging_system
• 🧪 Testing - Testing guidelines

Language Support: Most documents available in English and Korean (*.kr.md)

The container system supports 16 distinct value types (indices 0–15):

Example:

using namespace container_module;

// Create values using factory
auto int_val = value_factory::create_int64("id", 12345);
auto str_val = value_factory::create_string("name", "John Doe");
auto dbl_val = value_factory::create_double("balance", 1500.75);
auto bool_val = value_factory::create_bool("active", true);

// Add to container
container->add_value(int_val);
container->add_value(str_val);
container->add_value(dbl_val);
container->add_value(bool_val);

📚 Value Types Details →

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 C fill:#f9f,stroke:#333,stroke-width:3px

Ecosystem reference: common_system — Tier 0: Result<T> error handling used throughout network_system — Tier 4: Network transport (consumer) database_system — Tier 3: Database records (consumer) pacs_system — Tier 5: DICOM serialization (consumer)

#include <messaging_system/messaging_client.h>

auto client = std::make_shared<messaging_client>("client_01");

auto message = messaging_container_builder()
    .source("client_01", "session_123")
    .target("server", "main")
    .message_type("request")
    .add_value("action", "query")
    .build();

client->send_container(message);

#include <network_system/tcp_client.h>

auto tcp_client = network_system::TcpClient::create("localhost", 8080);

// Serialize and send
std::string data = container->serialize();
tcp_client->send(data);

// Receive and deserialize
auto received = tcp_client->receive();
auto restored = std::make_shared<value_container>(received);

#include <database_system/database_manager.h>

database_manager db;
db.connect("host=localhost dbname=app");

// Store as BLOB
std::string data = container->serialize();
db.insert_query("INSERT INTO messages (data) VALUES (?)", data);

🌐 Integration Guide →

# Configure
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release

# Build
cmake --build build -j$(nproc)

# Run tests
cd build && ctest

include(FetchContent)

# Fetch container_system (common_system will be fetched automatically)
FetchContent_Declare(
    container_system
    GIT_REPOSITORY https://github.com/kcenon/container_system.git
    GIT_TAG v0.1.0  # Pin to a specific release tag; do NOT use main
)
FetchContent_MakeAvailable(container_system)

target_link_libraries(your_target PRIVATE ContainerSystem::container)

# If you have container_system as a subdirectory
add_subdirectory(container_system)
target_link_libraries(your_target PRIVATE ContainerSystem::container)

container_system automatically handles common_system dependency:

# In your project's CMakeLists.txt
include(FetchContent)

FetchContent_Declare(
    container_system
    GIT_REPOSITORY https://github.com/kcenon/container_system.git
    GIT_TAG v0.1.0  # Pin to a specific release tag; do NOT use main
)

# common_system will be fetched automatically via UnifiedDependencies.cmake
FetchContent_MakeAvailable(container_system)

# Link against container_system
target_link_libraries(my_app PRIVATE ContainerSystem::container)

Advanced: Override common_system location:

# Use specific common_system location
set(COMMON_SYSTEM_ROOT "/path/to/custom/common_system" CACHE PATH "Path to common_system")

FetchContent_Declare(container_system ...)
FetchContent_MakeAvailable(container_system)

🔧 Build Guide →

Native Build Scripts:

• Linux/macOS: scripts/dependency.sh, scripts/build.sh
• Windows: scripts/dependency.bat, scripts/build.bat, scripts/dependency.ps1, scripts/build.ps1

Guarantee: Thread-safe without synchronization

// Multiple threads can safely read
std::vector<std::thread> readers;
for (int i = 0; i < 8; ++i) {
    readers.emplace_back([&container]() {
        auto value = container->get_value("price");
        // Safe concurrent read
    });
}

Performance: 7.5x speedup with 8 threads (linear scaling)

Use: thread_safe_container for synchronized writes

#include <container/internal/thread_safe_container.h>

auto safe_container = std::make_shared<thread_safe_container>(container);

std::vector<std::thread> workers;
for (int i = 0; i < 4; ++i) {
    workers.emplace_back([&safe_container, i]() {
        safe_container->set_value("thread_" + std::to_string(i),
                                 int32_value,
                                 std::to_string(i));
    });
}

Validation: Zero data races (ThreadSanitizer verified)

• Internal operations: C++ exceptions for performance
• External API: Result<T> for type safety

#include <container/integration/common_result_adapter.h>
using namespace container::adapters;

// Serialization with Result<T>
auto result = serialization_result_adapter::serialize(*container);
if (!result) {
    std::cerr << "Error: " << result.error().message << "\n";
    return -1;
}
auto data = result.value();

// Container operations with Result<T>
auto get_result = container_result_adapter::get_value<double>(container, "price");
if (!get_result) {
    std::cerr << "Error: " << get_result.error().message << "\n";
}

Error Codes: -400 to -499 (centralized in common_system)

Starting with v1.0.0, container_system provides the following API guarantees:

All types and functions in include/kcenon/container/ are part of the stable public API:

Headers under internal/ (e.g., memory_pool.h, simd_processor.h, thread_safe_container.h) are implementation details and may change without notice between minor versions.

• Deprecated features are marked with [[deprecated]] and documented in CHANGELOG.md
• Deprecated features remain available for at least one minor version before removal
• Migration guides are provided in docs/guides/ for all breaking changes

This project follows Semantic Versioning:

• Patch (1.0.x): Bug fixes, no API changes
• Minor (1.x.0): New features, backward-compatible
• Major (x.0.0): Breaking API changes (with migration guide)

For migration from 0.x, see docs/guides/MIGRATION.md.

The canonical include path for container_system is:

#include <container/container.h>

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

• Follow modern C++ best practices
• Use RAII and smart pointers
• Maintain formatting (clang-format provided)
• Write comprehensive tests

• 💬 GitHub Discussions
• 🐛 Issue Tracker
• 🤝 Contributing Guide
• 📧 Email: kcenon@naver.com

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

• Inspired by modern serialization frameworks and high-performance computing practices
• Built with C++20 features (GCC 11+, Clang 14+, MSVC 2022+) for maximum performance and safety
• Maintained by kcenon@naver.com

Made with ❤️ by 🍀☀🌕🌥 🌊