https://github.com/kcenon/common_system
🔧 Modern C++17 header-only library providing common interfaces and design patterns for modular system architecture
https://github.com/kcenon/common_system
architecture cpp17 dependency-injection design-patterns error-handling executor-pattern header-only interface modular-architecture result-type
Last synced: 4 months ago
JSON representation
🔧 Modern C++17 header-only library providing common interfaces and design patterns for modular system architecture
- Host: GitHub
- URL: https://github.com/kcenon/common_system
- Owner: kcenon
- License: bsd-3-clause
- Created: 2025-09-25T09:25:25.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-09-25T11:27:42.000Z (4 months ago)
- Last Synced: 2025-09-25T11:31:22.971Z (4 months ago)
- Topics: architecture, cpp17, dependency-injection, design-patterns, error-handling, executor-pattern, header-only, interface, modular-architecture, result-type
- Language: C++
- Homepage: https://github.com/kcenon/common_system/wiki
- Size: 79.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/kcenon/common_system/actions/workflows/build-ubuntu-gcc.yaml)
[](https://github.com/kcenon/common_system/actions/workflows/build-ubuntu-clang.yaml)
[](https://github.com/kcenon/common_system/actions/workflows/build-windows-msys2.yaml)
[](https://github.com/kcenon/common_system/actions/workflows/build-windows-vs.yaml)
[](https://github.com/kcenon/common_system/blob/main/LICENSE)
# Common System Project
## Project Overview
The Common System Project is a foundational C++17 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.
> **🏗️ Modular Architecture**: Pure header-only design with zero dependencies, providing universal interfaces for executor patterns, error handling, and event-driven communication.
> **✅ Latest Updates**: Complete separation from individual modules, comprehensive Result pattern implementation, IExecutor interface standardization, and centralized build configuration. All interfaces production-ready with full ecosystem compatibility.
## 🔗 Project Ecosystem & Inter-Dependencies
This common system serves as the foundational layer that all other system modules build upon, providing standardized interfaces and patterns:
### Core Purpose
- **Interface Standardization**: Universal abstractions for cross-module communication
- **Pattern Library**: Reusable design patterns for error handling and event-driven architecture
- **Build Configuration**: Centralized feature flags and build options for all modules
- **Zero Coupling**: Pure interfaces with no implementation dependencies
### Dependent Projects
- **[thread_system](https://github.com/kcenon/thread_system)**: Core threading framework
- Uses: IExecutor interface for task abstraction
- Provides: Thread pool implementations of IExecutor
- Integration: Adapter pattern for seamless executor usage
- **[network_system](https://github.com/kcenon/network_system)**: Asynchronous network library
- Uses: IExecutor for async operation scheduling
- Benefits: Threading backend independence
- Integration: Executor adapters for network operations
- **[logger_system](https://github.com/kcenon/logger_system)**: High-performance logging
- Uses: Result for error handling
- Benefits: Exception-free error propagation
- Integration: Optional event bus for log routing
- **[monitoring_system](https://github.com/kcenon/monitoring_system)**: Metrics and monitoring
- Provides: Event bus implementation
- Uses: Common event types and interfaces
- Integration: Central hub for system events
- **[container_system](https://github.com/kcenon/container_system)**: Data serialization
- Uses: Result for operation results
- Benefits: Type-safe error handling
- Integration: Common error codes
- **[database_system](https://github.com/kcenon/database_system)**: Database abstraction
- Uses: Result for query results
- Benefits: Consistent error handling
- Integration: Async operations via IExecutor
### Dependency Architecture
```
┌──────────────────┐
│ common_system │ ◄── Foundation Layer
│ (interfaces) │
└────────┬─────────┘
│ provides interfaces
┌─────────────────────┼─────────────────────┐
│ │ │
┌──────▼───────┐ ┌────────▼────────┐ ┌───────▼────────┐
│thread_system │ │network_system │ │monitoring_sys. │
│(implements │ │(uses IExecutor) │ │(event bus) │
│ IExecutor) │ └─────────────────┘ └────────────────┘
└──────────────┘ │ │
│ │ │
└─────────────────────┼─────────────────────┘
│ all use
┌────────▼─────────┐
│ Result pattern│
│ Error handling │
└──────────────────┘
```
### Integration Benefits
- **Universal interfaces**: Single source of truth for cross-module contracts
- **Zero-overhead abstractions**: Template-based design with compile-time resolution
- **Incremental adoption**: Use only the patterns and interfaces you need
- **Future-proof design**: Ready for C++23 std::expected migration
- **Ecosystem consistency**: Unified error handling and event patterns
> 📖 **[Complete Architecture Guide](docs/ARCHITECTURE.md)**: Comprehensive documentation of interface contracts, integration patterns, and best practices.
## Project Purpose & Mission
This project addresses the fundamental challenge in large-scale C++ development: **achieving true modularity without sacrificing performance**. Traditional approaches often lead to tight coupling, inconsistent interfaces, and fragmented error handling. Our mission is to provide:
- **Eliminate tight coupling** through pure interface definitions and dependency inversion
- **Standardize patterns** with consistent error handling and event-driven communication
- **Enable testing** through interface-based design and mockable abstractions
- **Simplify integration** with header-only distribution and zero dependencies
- **Future-proof architecture** with modern C++ patterns ready for upcoming standards
## Core Advantages & Benefits
### 🚀 **Performance Excellence**
- **Zero-overhead abstractions**: Template-based interfaces with compile-time resolution
- **Header-only design**: No library linking, better optimization opportunities
- **Cache-friendly patterns**: Minimal indirection and optimal memory layout
- **Compile-time optimization**: Full inlining potential for hot paths
### 🛡️ **Production-Grade Reliability**
- **Type-safe interfaces**: Strong typing prevents runtime errors
- **Result pattern**: Explicit error handling without exceptions
- **RAII compliance**: Resource management through standard patterns
- **Thread-safe design**: All interfaces safe for concurrent use
### 🔧 **Developer Productivity**
- **Self-documenting interfaces**: Clear contracts with comprehensive documentation
- **Minimal boilerplate**: Clean API design reduces code overhead
- **Mockable abstractions**: Easy testing through interface injection
- **IDE-friendly**: Full IntelliSense and autocomplete support
### 🌐 **Universal Compatibility**
- **C++17 baseline**: Works with all modern compilers
- **Cross-platform**: Windows, Linux, macOS without modification
- **Build system agnostic**: CMake, Bazel, Make - all supported
- **Package manager ready**: vcpkg, Conan integration available
### 📈 **Enterprise-Ready Features**
- **Interface versioning**: Backward compatibility through careful design
- **Centralized configuration**: Unified build flags across all modules
- **Comprehensive testing**: Full test coverage with GTest integration
- **Production examples**: Real-world usage patterns included
## Getting Started
### System Requirements
- **Compiler**: C++17 compatible (GCC 7+, Clang 5+, MSVC 2017+)
- **Build System**: CMake 3.16 or higher
- **Optional**: vcpkg or Conan for dependency management
- **Platform**: Windows, Linux, macOS (all architectures)
### Quick Installation
#### Option 1: Header-Only Usage (Simplest)
```bash
git clone https://github.com/kcenon/common_system.git
# Include headers directly - no build required!
```
```cpp
// In your code
#include
#include
```
#### Option 2: CMake Integration
```cmake
# Using FetchContent (recommended)
include(FetchContent)
FetchContent_Declare(
common_system
GIT_REPOSITORY https://github.com/kcenon/common_system.git
GIT_TAG main
)
FetchContent_MakeAvailable(common_system)
target_link_libraries(your_target PRIVATE kcenon::common)
```
#### Option 3: System-wide Installation
```bash
git clone https://github.com/kcenon/common_system.git
cd common_system
./build.sh --release --install-prefix=/usr/local
sudo cmake --build build --target install
```
### Building from Source
```bash
# Clone repository
git clone https://github.com/kcenon/common_system.git
cd common_system
# Build with tests and examples
./build.sh --release --tests --examples
# Run tests
./test.sh
# Clean build artifacts
./clean.sh
```
### Windows Build
```batch
REM Using Visual Studio 2022
build.bat --vs2022 --release
REM Run tests
test.bat --release
REM Clean artifacts
clean.bat
```
## Core Components
### IExecutor Interface
Universal task execution abstraction for any threading backend:
```cpp
#include
class MyService {
std::shared_ptr executor_;
public:
void process_async(const Data& data) {
auto future = executor_->submit([data]() {
// Process data asynchronously
return process(data);
});
// Continue with other work...
}
};
```
### Result Pattern
Type-safe error handling without exceptions:
```cpp
#include
common::Result load_config(const std::string& path) {
if (!std::filesystem::exists(path)) {
return common::error(
common::error_codes::NOT_FOUND,
"Configuration file not found",
"config_loader"
);
}
try {
auto config = parse_json_file(path);
return common::ok(config);
} catch (const std::exception& e) {
return common::error(
common::error_codes::INVALID_ARGUMENT,
e.what(),
"config_loader"
);
}
}
// Usage with monadic operations
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();
});
```
### Event Bus Integration
When used with monitoring_system:
```cpp
#include
// Publish events
auto bus = common::get_event_bus();
bus->publish(common::events::module_started_event("my_service"));
// Subscribe to events
bus->subscribe([](const auto& event) {
std::cerr << "Error in " << event.module_name
<< ": " << event.error_message << std::endl;
});
```
## Integration Examples
### With thread_system
```cpp
#include
#include
// Create thread pool
auto thread_pool = std::make_shared(4);
// Adapt to common interface
auto executor = kcenon::thread::adapters::make_common_executor(thread_pool);
// Use with any IExecutor-based API
process_with_executor(executor);
```
### With network_system
```cpp
#include
// Use common executor with network system
void setup_network(std::shared_ptr executor) {
auto adapted_pool = network_system::integration::make_thread_pool_adapter(executor);
network_system::server server(adapted_pool);
// Network operations now use the common executor
}
```
## Testing
The project includes comprehensive unit tests:
```bash
# Run all tests
./test.sh
# Run with coverage
./test.sh --coverage
# Run specific tests
./test.sh --filter "Result*"
# Benchmark tests
./test.sh --benchmark
```
## Documentation
- [API Reference](docs/API.md)
- [Architecture Guide](docs/ARCHITECTURE.md)
- [Integration Guide](docs/INTEGRATION.md)
- [Error Handling Guide](docs/ERRORS.md)
- [Migration Guide](docs/MIGRATION.md)
## Performance Benchmarks
| Operation | Time (ns) | Allocations |
|-----------|-----------|-------------|
| Result creation | 2.3 | 0 |
| Result error check | 0.8 | 0 |
| IExecutor submit | 45.2 | 1 |
| Event publish | 12.4 | 0 |
*Benchmarked on Intel i7-9700K @ 3.6GHz with GCC 11.2 -O3*
## Contributing
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
### Development Workflow
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
### Code Style
- Follow the existing code style (clang-format configuration provided)
- Write comprehensive unit tests for new features
- Update documentation as needed
- Ensure all tests pass before submitting PR
## Roadmap
- [x] IExecutor interface standardization
- [x] Result pattern implementation
- [x] Event bus forwarding
- [x] Centralized build configuration
- [ ] C++20 concepts for interface constraints
- [ ] Coroutine support for async patterns
- [ ] std::expected migration (C++23)
- [ ] Additional design patterns (Observer, Command)
- [ ] Package manager official support
## Support
- **Issues**: [GitHub Issues](https://github.com/kcenon/common_system/issues)
- **Discussions**: [GitHub Discussions](https://github.com/kcenon/common_system/discussions)
- **Email**: kcenon@naver.com
## License
This project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- Inspired by Rust's Result type and error handling
- Interface design influenced by Java's ExecutorService
- Event bus pattern from reactive programming frameworks
- Build system patterns from modern C++ best practices
## Citation
If you use this project in your research or commercial projects, please cite:
```bibtex
@software{common_system,
author = {Dongcheol Shin},
title = {Common System: Foundational Interfaces for Modular C++ Architecture},
year = {2024},
url = {https://github.com/kcenon/common_system}
}
```
---
Building Better C++ Systems Together
Made with ❤️ by the C++ Community