diff --git a/ANALYSIS_README.md b/ANALYSIS_README.md deleted file mode 100644 index 76aace218e..0000000000 --- a/ANALYSIS_README.md +++ /dev/null @@ -1,275 +0,0 @@ -# Thread System Analysis - Getting Started - -Welcome! This directory contains comprehensive analysis of the Thread System architecture and capabilities. - -## Key Documentation - -### Start Here -1. **[README.md](README.md)** — System overview, quick start, features, performance, and production quality - - Executive overview and quick start guide - - Core features and architecture summary - - Performance benchmarks - - Production readiness assessment - - **Perfect for**: Getting oriented quickly, understanding what's available - -### Deep Dive - API & Architecture -2. **[docs/advanced/API_REFERENCE.md](docs/advanced/API_REFERENCE.md)** — Complete API documentation - - Complete feature inventory - - Main classes and interfaces - - Public APIs and interface contracts - - Error handling patterns - - Integration points - - **Perfect for**: Learning what the system offers, finding components to reuse - -3. **[docs/advanced/ARCHITECTURE.md](docs/advanced/ARCHITECTURE.md)** — System design and internals - - System architecture overview - - Component hierarchy - - Threading and job execution flow - - Queue implementation strategies - - Design decisions and rationale - - **Perfect for**: Visual understanding, learning data flows, understanding design decisions - -### Additional Resources -4. **[docs/advanced/USER_GUIDE.md](docs/advanced/USER_GUIDE.md)** — Usage patterns and tutorials -5. **[docs/advanced/PERFORMANCE.md](docs/advanced/PERFORMANCE.md)** — Performance characteristics and benchmarks -6. **[docs/advanced/HAZARD_POINTER_DESIGN.md](docs/advanced/HAZARD_POINTER_DESIGN.md)** — Lock-free memory reclamation design -7. **[docs/advanced/JOB_CANCELLATION.md](docs/advanced/JOB_CANCELLATION.md)** — Cancellation token implementation -8. **[docs/advanced/QUEUE_SELECTION_GUIDE.md](docs/advanced/QUEUE_SELECTION_GUIDE.md)** — Queue type selection criteria - ---- - -## Quick Navigation - -### If you want to... - -**Understand the system quickly** → Read [README.md](README.md) -- 10-15 minute read -- High-level overview and quick start -- Key features summary -- Production quality metrics - -**Learn what components are available** → Read [docs/advanced/API_REFERENCE.md](docs/advanced/API_REFERENCE.md) -- Main classes and interfaces -- Threading patterns -- Synchronization primitives -- Public APIs - -**Understand how things work internally** → Read [docs/advanced/ARCHITECTURE.md](docs/advanced/ARCHITECTURE.md) -- Architecture overview -- Data flow diagrams -- Design pattern illustrations - -**Find specific APIs** → Use [docs/advanced/API_REFERENCE.md](docs/advanced/API_REFERENCE.md) -- executor_interface -- scheduler_interface -- service_registry -- result pattern -- error_code enumeration - -**See performance data** → See [docs/advanced/PERFORMANCE.md](docs/advanced/PERFORMANCE.md) -- Throughput benchmarks -- Memory efficiency -- Scalability characteristics -- Performance validation - -**Learn about integration** → See [docs/advanced/INTEGRATION.md](docs/advanced/INTEGRATION.md) -- Module dependency graph -- Integration points -- Platform support -- How other systems can leverage thread_system - -**Understand error handling** → See [docs/advanced/ERROR_SYSTEM_MIGRATION_GUIDE.md](docs/advanced/ERROR_SYSTEM_MIGRATION_GUIDE.md) -- result pattern -- Error codes -- Migration from legacy error handling - -**Learn cancellation** → See [docs/advanced/JOB_CANCELLATION.md](docs/advanced/JOB_CANCELLATION.md) -- Cancellation token -- Linked tokens -- Propagation mechanism -- Weak pointer safety - -**Understand memory safety** → See [docs/advanced/HAZARD_POINTER_DESIGN.md](docs/advanced/HAZARD_POINTER_DESIGN.md) -- Hazard pointers -- RAII wrappers -- Thread safety mechanisms -- Memory reclamation flow - ---- - -## Key Statistics - -### Code Size -- **Core system**: ~2,700 lines -- **Zero external dependencies** in core - -### Components Provided -- **4 queue implementations** (mutex, lock-free, adaptive, bounded) -- **2 thread pool implementations** (standard, typed) -- **5+ synchronization primitives** (locks, CV, atomic, flags) -- **100+ error codes** (categorized) -- **6 design patterns** (pool, queue, RAII, result, registry, strategy) - -### Performance -- **Lock-free queue**: 4x faster (71 μs vs 291 μs) -- **Adaptive queue**: 7.7x improvement under contention -- **Type pool**: 1.24M jobs/s (6 workers) -- **Standard pool**: 1.16M jobs/s (10 workers) - -### Production Ready -- **ThreadSanitizer**: Clean -- **AddressSanitizer**: Clean -- **Code coverage**: 95%+ -- **CI/CD success**: 95%+ - ---- - -## Component Highlights - -### Most Reusable -1. **thread_pool** - Standard worker pool (High reusability) -2. **service_registry** - Global DI container (High reusability) -3. **cancellation_token** - Cooperative shutdown (High reusability) -4. **result** - Type-safe error handling (High reusability) - -### Most Specialized -1. **hazard_pointer** - Lock-free memory reclamation (Medium reusability) -2. **typed_thread_pool** - Type-routed scheduling (High reusability) -3. **lockfree_job_queue** - High-contention queuing (Medium reusability) - -### Foundational -1. **thread_base** - Worker thread foundation -2. **job** - Work unit abstraction -3. **job_queue** - Basic FIFO queue -4. **sync_primitives** - Synchronization wrappers - ---- - -## Integration Pathways - -### Path 1: Simple Thread Pool Usage -``` -Your System → job interface → thread_pool → results -``` - -### Path 2: Priority-Based Scheduling -``` -Your System → typed_job → typed_thread_pool → results -``` - -### Path 3: High-Contention Queuing -``` -Your System → job → lockfree_job_queue → results -``` - -### Path 4: Service-Oriented Architecture -``` -Your System ← service_registry → (logger, monitoring, services) -``` - -### Path 5: Error-Aware Operations -``` -Your System → operation → result → map/and_then → error handling -``` - ---- - -## File Map - -### In This Repository Root -``` -ANALYSIS_README.md ← YOU ARE HERE -README.md ← System overview and quick start -README.kr.md ← Korean translation -``` - -### In `/docs/advanced/` -``` -ARCHITECTURE.md - System architecture and internals -API_REFERENCE.md - Complete API documentation -USER_GUIDE.md - Usage guide with examples -PERFORMANCE.md - Performance characteristics and benchmarks -HAZARD_POINTER_DESIGN.md - Lock-free memory reclamation design -JOB_CANCELLATION.md - Cancellation token implementation -QUEUE_SELECTION_GUIDE.md - Queue type selection criteria -INTEGRATION.md - Integration with other systems -``` - -### In `/examples/` -10+ example programs demonstrating: -- Thread pool usage -- Typed thread pool routing -- Lock-free queue operations -- Cancellation tokens -- Service registry -- Memory pooling -- Hazard pointers -- Adaptive queues - ---- - -## Recommended Reading Order - -**For First-Time Readers**: -1. README.md (10 min read) -2. docs/advanced/ARCHITECTURE.md (10 min read) -3. docs/advanced/API_REFERENCE.md (20 min read) - -**For Integration Planning**: -1. docs/advanced/INTEGRATION.md -2. docs/advanced/ARCHITECTURE.md — relevant sections for your use case -3. Review examples in `/examples/` directory - -**For Deep Understanding**: -1. docs/advanced/API_REFERENCE.md (complete, 30 min read) -2. docs/advanced/USER_GUIDE.md (complete, 20 min read) -3. Examine source code in `/include/` and `/src/` - ---- - -## Key Takeaways - -1. **Modular & Minimal**: ~2,700 lines, zero external deps (core) -2. **Well-Tested**: All safety validations passed -3. **High Performance**: Multiple queue strategies, adaptive algorithms -4. **Thread-Safe**: Designed with concurrency first -5. **Memory-Safe**: Smart pointers, RAII, hazard pointers -6. **Extensible**: Clear extension points for customization -7. **Well-Documented**: Comprehensive guides and examples -8. **Reusable**: Many components can be leveraged independently - ---- - -## Questions? - -### "What's the best queue for my scenario?" -→ See [docs/advanced/QUEUE_SELECTION_GUIDE.md](docs/advanced/QUEUE_SELECTION_GUIDE.md) -→ Or [docs/advanced/API_REFERENCE.md](docs/advanced/API_REFERENCE.md) — Queue section - -### "How do I integrate with my system?" -→ See [docs/advanced/INTEGRATION.md](docs/advanced/INTEGRATION.md) - -### "What APIs are available?" -→ See [docs/advanced/API_REFERENCE.md](docs/advanced/API_REFERENCE.md) - -### "Can I use this component standalone?" -→ See [README.md](README.md) — Component Highlights - -### "What are the performance characteristics?" -→ See [docs/advanced/PERFORMANCE.md](docs/advanced/PERFORMANCE.md) - -### "How does cancellation work?" -→ See [docs/advanced/JOB_CANCELLATION.md](docs/advanced/JOB_CANCELLATION.md) - -### "What about error handling?" -→ See [docs/advanced/ERROR_SYSTEM_MIGRATION_GUIDE.md](docs/advanced/ERROR_SYSTEM_MIGRATION_GUIDE.md) - ---- - -**Last Updated**: February 8, 2026 -**Documentation**: See `docs/` directory for comprehensive guides -**Status**: Ready for review and integration planning - diff --git a/CHANGELOG.md b/CHANGELOG.md index 8d0e645ffd..fd7b8caf59 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- `VERSIONING.md` documenting the SemVer policy, version SSOT, and release process ([#698](https://github.com/kcenon/thread_system/issues/698)) + +### Changed + +- Expand `README.kr.md` to mirror the full English `README.md` heading structure ([#698](https://github.com/kcenon/thread_system/issues/698)) + +### Removed + +- Stray root files `ANALYSIS_README.md` and `README_KO_UPDATE_NOTES.md` ([#698](https://github.com/kcenon/thread_system/issues/698)) + ## [1.0.0] - 2026-04-15 ### Added diff --git a/README.kr.md b/README.kr.md index a10ef60ea5..7f22d82262 100644 --- a/README.kr.md +++ b/README.kr.md @@ -1,8 +1,9 @@ [![CI](https://github.com/kcenon/thread_system/actions/workflows/ci.yml/badge.svg)](https://github.com/kcenon/thread_system/actions/workflows/ci.yml) [![Code Coverage](https://github.com/kcenon/thread_system/actions/workflows/coverage.yml/badge.svg)](https://github.com/kcenon/thread_system/actions/workflows/coverage.yml) -[![Static Analysis](https://github.com/kcenon/thread_system/actions/workflows/static-analysis.yml/badge.svg)](https://github.com/kcenon/thread_system/actions/workflows/static-analysis.yml) -[![Doxygen](https://github.com/kcenon/thread_system/actions/workflows/build-Doxygen.yaml/badge.svg)](https://github.com/kcenon/thread_system/actions/workflows/build-Doxygen.yaml) [![codecov](https://codecov.io/gh/kcenon/thread_system/branch/main/graph/badge.svg)](https://codecov.io/gh/kcenon/thread_system) +[![Coverage Status](https://img.shields.io/codecov/c/github/kcenon/thread_system/main?label=line%20coverage&logo=codecov)](https://codecov.io/gh/kcenon/thread_system) +[![Static Analysis](https://github.com/kcenon/thread_system/actions/workflows/static-analysis.yml/badge.svg)](https://github.com/kcenon/thread_system/actions/workflows/static-analysis.yml) +[![Documentation](https://github.com/kcenon/thread_system/actions/workflows/build-Doxygen.yaml/badge.svg)](https://github.com/kcenon/thread_system/actions/workflows/build-Doxygen.yaml) [![License](https://img.shields.io/github/license/kcenon/thread_system)](https://github.com/kcenon/thread_system/blob/main/LICENSE) # Thread System @@ -11,81 +12,88 @@ 동시성 프로그래밍의 민주화를 위해 설계된 현대적인 C++20 멀티스레딩 프레임워크입니다. -## 목차 - -- [개요](#개요) -- [주요 기능](#주요-기능) -- [요구사항](#요구사항) -- [빠른 시작](#빠른-시작) -- [설치](#설치) -- [아키텍처](#아키텍처) -- [핵심 개념](#핵심-개념) -- [API 개요](#api-개요) -- [예제](#예제) -- [성능](#성능) -- [생태계 통합](#생태계-통합) -- [기여하기](#기여하기) -- [라이선스](#라이선스) +## Table of Contents + +- [Overview](#overview) +- [Quick Start](#quick-start) +- [Core Features](#core-features) +- [Performance Highlights](#performance-highlights) +- [Architecture Overview](#architecture-overview) +- [Documentation](#documentation) +- [Ecosystem Integration](#ecosystem-integration) +- [C++20 Module Support](#c20-module-support) +- [CMake Integration](#cmake-integration) +- [Examples](#examples) +- [Production Quality](#production-quality) +- [Platform Support](#platform-support) +- [Contributing](#contributing) +- [License](#license) --- -## 개요 +## Overview Thread System은 고성능 thread-safe 애플리케이션 구축을 위한 직관적인 추상화와 견고한 구현을 제공하는 포괄적인 멀티스레딩 프레임워크입니다. -**핵심 가치**: -- **검증된 품질**: 95%+ CI/CD 성공률, ThreadSanitizer 경고 제로, 72% 코드 커버리지 -- **고성능**: 초당 1.16M 작업 처리, lock-free 큐 4배 성능 향상, 적응형 최적화 +**핵심 가치(Key Value Propositions)**: +- **검증된 품질**: 95%+ CI/CD 성공률, ThreadSanitizer 경고 제로, 49% 코드 커버리지 +- **고성능**: 초당 1.16M 작업 처리(baseline), lock-free 큐 4배 성능 향상, 적응형 최적화 - **개발자 친화적**: 직관적 API, 포괄적 문서, 풍부한 예제 - **유연한 아키텍처**: 선택적 logger/monitoring 통합이 가능한 모듈식 설계 -- **크로스 플랫폼**: Linux, macOS, Windows 지원 (다중 컴파일러) +- **크로스 플랫폼**: 다중 컴파일러를 지원하는 Linux, macOS, Windows -**최신 업데이트**: -- Queue API 간소화: 8개 구현 → 2개 공개 타입 (adaptive_job_queue, job_queue) -- Hazard Pointer 구현 완료 - 프로덕션 안전한 lock-free 큐 -- Lock-free 큐로 4배 성능 향상 (71 us vs 291 us) -- 향상된 동기화 프리미티브 및 취소 토큰 -- 모든 CI/CD 파이프라인 정상 (ThreadSanitizer 및 AddressSanitizer 클린) +**최신 업데이트(Latest Updates)**: +- ✅ Queue API 간소화: 8개 구현 → 2개 공개 타입 (adaptive_job_queue, job_queue) +- ✅ Hazard Pointer 구현 완료 - lock-free 큐가 프로덕션에 안전 +- ✅ Lock-free 큐로 4배 성능 향상 (71 μs vs 291 μs) +- ✅ 향상된 동기화 프리미티브 및 취소 토큰 +- ✅ 모든 CI/CD 파이프라인 정상 (ThreadSanitizer 및 AddressSanitizer 클린) --- -## 주요 기능 - -| 기능 | 설명 | 상태 | -|------|------|------| -| **표준 스레드 풀** | 적응형 큐를 지원하는 다중 워커 풀 | 안정 | -| **타입드 스레드 풀** | 타입 인식 라우팅을 갖춘 우선순위 기반 스케줄링 | 안정 | -| **적응형 큐** | mutex/lock-free 모드 자동 전환 | 안정 | -| **Hazard Pointer** | Lock-free 구조를 위한 안전한 메모리 회수 | 안정 | -| **취소 토큰** | 계층적 지원을 갖춘 협력적 취소 | 안정 | -| **서비스 레지스트리** | 경량 의존성 주입 컨테이너 | 안정 | -| **동기화 프리미티브** | 타임아웃 및 술어를 갖춘 향상된 래퍼 | 안정 | -| **워커 정책** | 세밀한 제어 (스케줄링, 유휴 동작, CPU 친화성) | 안정 | -| **DAG 스케줄러** | 의존성 그래프 기반 작업 실행 | 실험적 | -| **C++20 모듈** | 헤더 기반 인터페이스 대안 | 실험적 | +## Quick Start ---- +### Requirements -## 요구사항 +- **C++20 컴파일러**: GCC 13+ / Clang 17+ / MSVC 2022+ +- **CMake 3.20+** +- **[common_system](https://github.com/kcenon/common_system)**: 필수 의존성 (thread_system과 나란히 클론해야 함) -### 컴파일러 매트릭스 +> **⚠️ 하위 영향(Downstream Impact)**: thread_system에 의존하는 시스템(monitoring_system, database_system, network_system)은 이 컴파일러 요구사항을 상속합니다. 전체 생태계를 빌드할 때 컴파일러가 GCC 13+/Clang 17+를 충족하는지 확인하세요. -| 컴파일러 | 최소 버전 | 권장 버전 | 비고 | -|----------|----------|----------|------| -| GCC | 13+ | 14+ | `std::format` 필수 | -| Clang | 17+ | 18+ | `std::format` 필수 | -| MSVC | 2022+ | 2022 17.4+ | C++20 모듈 지원 | +### Installation -### 빌드 도구 +```bash +# Clone repositories (common_system is required) +git clone https://github.com/kcenon/common_system.git +git clone https://github.com/kcenon/thread_system.git +cd thread_system -- **CMake** 3.20+ (모듈 사용 시 3.28+) -- **[common_system](https://github.com/kcenon/common_system)**: 필수 의존성 (thread_system과 나란히 클론 필요) +# Install dependencies +./scripts/dependency.sh # Linux/macOS +./scripts/dependency.bat # Windows -> **하위 영향**: thread_system에 의존하는 시스템 (monitoring_system, database_system, network_system)은 이 컴파일러 요구사항을 상속합니다. 전체 생태계를 빌드할 때 컴파일러가 GCC 13+/Clang 17+를 충족하는지 확인하세요. +# Build +./scripts/build.sh # Linux/macOS +./scripts/build.bat # Windows ---- +# Run examples +./build/bin/thread_pool_sample +``` + +### Installation via vcpkg + +```bash +vcpkg install kcenon-thread-system +``` + +`CMakeLists.txt`에서: +```cmake +find_package(thread_system CONFIG REQUIRED) +target_link_libraries(your_target PRIVATE kcenon::thread_system) +``` -## 빠른 시작 +### Basic Usage ```cpp #include @@ -94,116 +102,284 @@ Thread System은 고성능 thread-safe 애플리케이션 구축을 위한 직 using namespace kcenon::thread; int main() { - // 스레드 풀 생성 + // Create thread pool auto pool = std::make_shared("MyPool"); - // 워커 추가 + // Add workers std::vector> workers; for (size_t i = 0; i < std::thread::hardware_concurrency(); ++i) { workers.push_back(std::make_unique()); } pool->enqueue_batch(std::move(workers)); - // 처리 시작 + // Start processing pool->start(); - // 작업 제출 (편의 API) + // Submit jobs (convenience API) for (int i = 0; i < 1000; ++i) { pool->submit_task([i]() { std::cout << "Processing job " << i << "\n"; }); } - // 정상 종료 - pool->shutdown_pool(false); // 완료 대기 + // Clean shutdown + pool->shutdown_pool(false); // Wait for completion return 0; } ``` -**[전체 시작 가이드 ->](docs/guides/QUICK_START.md)** +**📖 [전체 시작 가이드 →](docs/guides/QUICK_START.md)** --- -## 설치 +## Core Features -### 소스에서 빌드 +### Thread Pool System +- **표준 스레드 풀(Standard Thread Pool)**: 적응형 큐를 지원하는 다중 워커 풀 +- **타입드 스레드 풀(Typed Thread Pool)**: 타입 인식 라우팅을 갖춘 우선순위 기반 스케줄링 +- **동적 워커 관리(Dynamic Worker Management)**: 런타임에 워커 추가/제거 +- **이중 API(Dual API)**: Result 기반(상세 오류)과 편의 API(간단) -```bash -# 리포지토리 클론 (common_system 필수) -git clone https://github.com/kcenon/common_system.git -git clone https://github.com/kcenon/thread_system.git -cd thread_system +### Queue Implementations (Simplified to 2 Public Types) +Kent Beck의 Simple Design 원칙에 따라 이제 2개의 공개 큐 타입만 제공합니다: +- **Adaptive Queue** (권장): mutex와 lock-free 모드 사이를 자동 전환하는 자동 최적화 큐 +- **Standard Queue**: 블로킹 대기와 정확한 크기 추적을 갖춘 Mutex 기반 FIFO(선택적 크기 제한 지원) +- **Queue Factory**: 컴파일 타임 선택을 통한 요구사항 기반 큐 생성 +- **Capability Introspection**: 큐 특성(exact_size, lock_free 등)에 대한 런타임 조회 -# 의존성 설치 -./scripts/dependency.sh # Linux/macOS -./scripts/dependency.bat # Windows +> **참고**: `bounded_job_queue`는 이제 선택적 `max_size` 파라미터를 갖춘 `job_queue`로 통합되었습니다. +> 내부 구현(`lockfree_job_queue`, `concurrent_queue`)은 `detail::` 네임스페이스에 있습니다. -# 빌드 -./scripts/build.sh # Linux/macOS -./scripts/build.bat # Windows +### Advanced Features +- **Hazard Pointers**: Lock-free 구조를 위한 안전한 메모리 회수 +- **Cancellation Tokens**: 계층적 지원을 갖춘 협력적 취소 +- **Service Registry**: 경량 의존성 주입 컨테이너 +- **Synchronization Primitives**: 타임아웃과 술어(predicate)를 갖춘 향상된 래퍼 +- **Worker Policies**: 세밀한 제어(스케줄링, 유휴 동작, CPU 친화성) -# 예제 실행 -./build/bin/thread_pool_sample +### Error Handling +- `thread::result`와 `thread::result_void`는 `common::Result`를 래핑하되 thread 전용 헬퍼를 유지합니다(`include/kcenon/thread/core/error_handling.h` 참조). +- thread_system 리포지토리 내부에서 작업할 때는 `result.has_error()` / `result.get_error()`를 사용하고, 모듈 경계를 넘을 때는 `detail::to_common_error(...)`를 통해 `common::error_info`로 변환합니다. +- 공유 문서를 갱신할 때는, 다른 시스템이 `.error()`에 의존하더라도 thread 전용 래퍼는 하위 호환성을 위해 의도적으로 `.get_error()`를 노출한다는 점을 명시하세요. + +**📚 [상세 기능 →](docs/FEATURES.md)** + +--- + +## Performance Highlights + +**플랫폼**: Apple M1 @ 3.2GHz, 16GB RAM, macOS Sonoma + +| 메트릭 | 값 | 구성 | +|--------|-------|---------------| +| **프로덕션 처리량** | 1.16M jobs/s | 10 워커, 실제 워크로드 | +| **타입드 풀** | 1.24M jobs/s | 6 워커, 6.9% 향상 | +| **Lock-free 큐** | 71 μs/op | Mutex 대비 4배 향상 | +| **작업 지연 (P50)** | 77 ns | 마이크로초 이하 | +| **메모리 기준선** | <1 MB | 8 워커 | +| **스케일링 효율** | 96% | 8 워커까지 | + +### Queue Performance Comparison + +| 큐 타입 | 지연 | 적합 대상 | +|-----------|---------|----------| +| Mutex Queue | 96 ns | 낮은 경합 (1-2 스레드) | +| Adaptive (auto) | 96-320 ns | 가변 워크로드 | +| Lock-free | 320 ns | 높은 경합 (8+ 스레드), 37% 향상 | + +### Worker Scaling + +| 워커 수 | 속도 향상 | 효율 | 등급 | +|---------|---------|------------|--------| +| 2 | 2.0x | 99% | 🥇 Excellent | +| 4 | 3.9x | 97.5% | 🥇 Excellent | +| 8 | 7.7x | 96% | 🥈 Very Good | +| 16 | 15.0x | 94% | 🥈 Very Good | + +**⚡ [전체 벤치마크 →](docs/BENCHMARKS.md)** + +--- + +## Architecture Overview + +### Modular Design + +``` +┌─────────────────────────────────────────┐ +│ Thread System Core │ +│ ┌───────────────────────────────────┐ │ +│ │ Thread Pool & Workers │ │ +│ │ - Standard Pool │ │ +│ │ - Typed Pool (Priority) │ │ +│ │ - Dynamic Worker Management │ │ +│ └───────────────────────────────────┘ │ +│ ┌───────────────────────────────────┐ │ +│ │ Queue Implementations │ │ +│ │ - Adaptive Queue (recommended) │ │ +│ │ - Standard Queue (blocking wait) │ │ +│ │ - Internal: lock-free MPMC │ │ +│ └───────────────────────────────────┘ │ +│ ┌───────────────────────────────────┐ │ +│ │ Advanced Features │ │ +│ │ - Hazard Pointers │ │ +│ │ - Cancellation Tokens │ │ +│ │ - Service Registry │ │ +│ │ - Worker Policies │ │ +│ └───────────────────────────────────┘ │ +└─────────────────────────────────────────┘ + +Optional Integration Projects (Separate Repos): +┌──────────────────┐ ┌──────────────────┐ +│ Logger System │ │ Monitoring System│ +│ - Async logging │ │ - Real-time │ +│ - Multi-target │ │ metrics │ +│ - High-perf │ │ - Observability │ +└──────────────────┘ └──────────────────┘ ``` -### vcpkg를 통한 설치 +### Key Components + +- **thread_base**: 라이프사이클 관리를 갖춘 추상 스레드 클래스 +- **thread_pool**: 적응형 큐를 갖춘 다중 워커 풀 +- **typed_thread_pool**: 타입 인식 라우팅을 갖춘 우선순위 스케줄링 +- **adaptive_job_queue**: 자동 최적화 큐 (권장 기본값) +- **job_queue**: 블로킹 대기 지원을 갖춘 Mutex 기반 큐 +- **hazard_pointer**: Lock-free 구조를 위한 안전한 메모리 회수 +- **cancellation_token**: 협력적 취소 메커니즘 + +**🏗️ [아키텍처 가이드 →](docs/advanced/ARCHITECTURE.md)** + +--- + +## Documentation + +### Getting Started +- 📖 [Quick Start Guide](docs/guides/QUICK_START.md) - 5분 만에 시작하기 +- 🔧 [Build Guide](docs/guides/BUILD_GUIDE.md) - 상세 빌드 지침 +- 🚀 [User Guide](docs/advanced/USER_GUIDE.md) - 포괄적인 사용 가이드 + +### Core Documentation +- 📚 [Features](docs/FEATURES.md) - 상세 기능 설명 +- ⚡ [Benchmarks](docs/BENCHMARKS.md) - 포괄적인 성능 데이터 +- 📋 [API Reference](docs/advanced/API_REFERENCE.md) - 완전한 API 문서 +- 🏛️ [Architecture](docs/advanced/ARCHITECTURE.md) - 시스템 설계 및 내부 구조 + +### Advanced Topics +- 🔬 [Performance Baseline](docs/performance/BASELINE.md) - 기준선 메트릭 및 회귀 감지 +- 🛡️ [Production Quality](docs/PRODUCTION_QUALITY.md) - CI/CD, 테스트, 품질 메트릭 +- 🧩 [C++20 Concepts](docs/advanced/CPP20_CONCEPTS.md) - 스레드 연산을 위한 타입 안전 제약 +- 📁 [Project Structure](docs/PROJECT_STRUCTURE.md) - 상세 코드베이스 구성 +- ⚠️ [Known Issues](docs/advanced/KNOWN_ISSUES.md) - 현재 제약 및 우회 방법 +- 📗 [Queue Selection Guide](docs/advanced/QUEUE_SELECTION_GUIDE.md) - 올바른 큐 선택 +- 🔄 [Queue Backward Compatibility](docs/QUEUE_BACKWARD_COMPATIBILITY.md) - 마이그레이션 및 호환성 + +### Development +- 🤝 [Contributing](docs/contributing/CONTRIBUTING.md) - 기여 방법 +- 🔍 [Troubleshooting](docs/guides/TROUBLESHOOTING.md) - 일반적인 문제 및 해결 +- ❓ [FAQ](docs/guides/FAQ.md) - 자주 묻는 질문 +- 🔄 [Migration Guide](docs/advanced/MIGRATION.md) - 이전 버전에서 업그레이드 + +### API Documentation (Doxygen) ```bash -vcpkg install kcenon-thread-system +cmake -S . -B build -DCMAKE_BUILD_TYPE=Release +cmake --build build --target docs +# Open documents/html/index.html ``` -`CMakeLists.txt`에서: -```cmake -find_package(thread_system CONFIG REQUIRED) -target_link_libraries(your_target PRIVATE kcenon::thread_system) -``` +--- -### FetchContent를 통한 설치 +## Ecosystem Integration -```cmake -include(FetchContent) -FetchContent_Declare( - thread_system - GIT_REPOSITORY https://github.com/kcenon/thread_system.git - GIT_TAG v1.0.0 # 특정 릴리스 태그에 고정; main 사용 금지 -) -FetchContent_MakeAvailable(thread_system) +### Ecosystem Dependency Map -target_link_libraries(your_target PRIVATE thread_system) +```mermaid +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 B fill:#f9f,stroke:#333,stroke-width:3px ``` -### 서브디렉토리 연동 +> **생태계 참조(Ecosystem reference)**: +> [common_system](https://github.com/kcenon/common_system) — Tier 0: IExecutor 인터페이스 및 Result<T> 패턴 +> [logger_system](https://github.com/kcenon/logger_system) — Tier 2: 비동기 로깅 (선택적 소비자) +> [monitoring_system](https://github.com/kcenon/monitoring_system) — Tier 3: 메트릭 수집 (소비자) +> [network_system](https://github.com/kcenon/network_system) — Tier 4: 전송 계층 (소비자) -```cmake -add_subdirectory(thread_system) +### Project Ecosystem -target_link_libraries(your_target PRIVATE - thread_base - thread_pool - utilities -) +이 프로젝트는 모듈식 생태계의 일부입니다: + +``` +thread_system (core interfaces) + ↑ ↑ +logger_system monitoring_system + ↑ ↑ + └── integrated_thread_system ──┘ ``` -### C++20 모듈 지원 +### Optional Components + +- **[logger_system](https://github.com/kcenon/logger_system)**: 고성능 비동기 로깅 +- **[monitoring_system](https://github.com/kcenon/monitoring_system)**: 실시간 메트릭 및 모니터링 +- **[integrated_thread_system](https://github.com/kcenon/integrated_thread_system)**: 완전한 통합 예제 + +### Integration Benefits + +- **플러그 앤 플레이(Plug-and-play)**: 필요한 컴포넌트만 사용 +- **인터페이스 기반(Interface-driven)**: 깔끔한 추상화로 쉬운 교체 가능 +- **성능 최적화(Performance-optimized)**: 각 시스템이 고유 도메인에 최적화 +- **통합 생태계(Unified ecosystem)**: 일관된 API 설계 + +**🌐 [생태계 통합 가이드 →](docs/ECOSYSTEM.md)** + +--- + +## C++20 Module Support + +Thread System은 헤더 기반 인터페이스의 대안으로 C++20 모듈 지원을 제공합니다. + +### Requirements for Modules +- **CMake 3.28+** +- **Clang 16+, GCC 14+, 또는 MSVC 2022 17.4+** +- 모듈을 지원하는 **common_system** + +### Building with Modules ```bash cmake -B build -DTHREAD_BUILD_MODULES=ON cmake --build build ``` +### Using Modules + ```cpp +// Instead of includes: +// #include + +// Use module import: import kcenon.thread; int main() { using namespace kcenon::thread; + auto pool = std::make_shared("MyPool"); pool->start(); // ... } ``` +### Module Structure + | 모듈 | 내용 | -|------|------| +|--------|----------| | `kcenon.thread` | 기본 모듈 (모든 파티션 임포트) | | `kcenon.thread:core` | 스레드 풀, 워커, 작업, 취소 | | `kcenon.thread:queue` | 큐 구현 (job_queue, adaptive_job_queue) | @@ -212,230 +388,157 @@ int main() { --- -## 아키텍처 - -### 모듈식 설계 - -``` -+-----------------------------------------+ -| Thread System Core | -| +-----------------------------------+ | -| | Thread Pool & Workers | | -| | - Standard Pool | | -| | - Typed Pool (Priority) | | -| | - Dynamic Worker Management | | -| +-----------------------------------+ | -| +-----------------------------------+ | -| | Queue Implementations | | -| | - Adaptive Queue (recommended) | | -| | - Standard Queue (blocking wait) | | -| | - Internal: lock-free MPMC | | -| +-----------------------------------+ | -| +-----------------------------------+ | -| | Advanced Features | | -| | - Hazard Pointers | | -| | - Cancellation Tokens | | -| | - Service Registry | | -| | - Worker Policies | | -| +-----------------------------------+ | -+-----------------------------------------+ - -선택적 통합 프로젝트 (별도 리포지토리): -+------------------+ +------------------+ -| Logger System | | Monitoring System| -| - Async logging | | - Real-time | -| - Multi-target | | metrics | -| - High-perf | | - Observability | -+------------------+ +------------------+ -``` - -### 주요 컴포넌트 - -| 컴포넌트 | 설명 | -|----------|------| -| `thread_base` | 라이프사이클 관리를 갖춘 추상 스레드 클래스 | -| `thread_pool` | 적응형 큐를 갖춘 다중 워커 풀 | -| `typed_thread_pool` | 타입 인식 라우팅을 갖춘 우선순위 스케줄링 | -| `adaptive_job_queue` | 자동 최적화 큐 (권장 기본값) | -| `job_queue` | 블로킹 대기 지원을 갖춘 Mutex 기반 큐 | -| `hazard_pointer` | Lock-free 구조를 위한 안전한 메모리 회수 | -| `cancellation_token` | 협력적 취소 메커니즘 | - -**[아키텍처 가이드 ->](docs/advanced/ARCHITECTURE.md)** - ---- - -## 핵심 개념 +## CMake Integration -### 스레드 풀 라이프사이클 +### Basic Integration -스레드 풀은 명확한 라이프사이클을 따릅니다: +```cmake +# Using as subdirectory +add_subdirectory(thread_system) +target_link_libraries(your_target PRIVATE + thread_base + thread_pool + utilities +) ``` -생성 -> 워커 등록 (enqueue_batch) -> 시작 (start) -> 작업 제출 (submit_task) -> 종료 (shutdown_pool) -``` - -`shutdown_pool(false)`는 진행 중인 작업이 완료될 때까지 대기하며, `shutdown_pool(true)`는 즉시 종료합니다. - -### 큐 전략 - -Kent Beck의 Simple Design 원칙에 따라 2개의 공개 큐 타입만 제공합니다: -- **adaptive_job_queue** (권장): 경합 수준에 따라 mutex와 lock-free 모드를 자동 전환합니다. -- **job_queue**: 블로킹 대기와 정확한 크기 추적을 지원하는 Mutex 기반 FIFO입니다. 선택적 `max_size` 파라미터로 경계를 설정할 수 있습니다. +### With FetchContent -> `bounded_job_queue`는 선택적 `max_size` 파라미터를 갖춘 `job_queue`로 통합되었습니다. -> 내부 구현 (`lockfree_job_queue`, `concurrent_queue`)은 `detail::` 네임스페이스에 있습니다. - -### Hazard Pointer +```cmake +include(FetchContent) +FetchContent_Declare( + thread_system + GIT_REPOSITORY https://github.com/kcenon/thread_system.git + GIT_TAG v1.0.0 # Pin to a specific release tag; do NOT use main +) +FetchContent_MakeAvailable(thread_system) -Lock-free 데이터 구조에서 안전한 메모리 회수를 위한 메커니즘입니다. 스레드별 hazard 배열(4슬롯)을 사용하여 다른 스레드가 참조 중인 메모리가 해제되지 않도록 보장합니다. +target_link_libraries(your_target PRIVATE thread_system) +``` -### 취소 토큰 +### With vcpkg -계층적 취소를 지원하는 협력적 취소 메커니즘입니다. 부모 토큰이 취소되면 모든 자식 토큰도 함께 취소됩니다. +이 패키지는 kcenon vcpkg 레지스트리에서 `kcenon-thread-system`으로 제공됩니다: -### 오류 처리 +```json +{ + "dependencies": [ + "kcenon-thread-system" + ] +} +``` -- `thread::result` 및 `thread::result_void`는 `common::Result`를 래핑하되 thread 전용 헬퍼를 유지합니다. -- thread_system 내부에서는 `result.has_error()` / `result.get_error()`를 사용합니다. -- 모듈 경계를 넘을 때는 `detail::to_common_error(...)`로 `common::error_info`로 변환합니다. +> **참고**: 이 패키지는 thread_system과 나란히 클론해야 하는 +> [kcenon-common-system](https://github.com/kcenon/common_system)을 필요로 합니다. +> common_system에 대한 vcpkg 통합은 kcenon vcpkg 레지스트리가 구축되면 제공될 예정입니다. + +선택적 기능(Optional features): +- `testing`: 단위 테스트를 위한 gtest 및 benchmark 포함 +- `logging`: spdlog 통합 활성화 +- `development`: 모든 testing 및 logging 의존성 + +```json +{ + "dependencies": [ + { + "name": "kcenon-thread-system", + "features": ["testing", "logging"] + } + ] +} +``` --- -## API 개요 - -| API | 헤더 | 설명 | -|-----|------|------| -| `thread_pool` | `core/thread_pool.h` | 다중 워커 스레드 풀 | -| `typed_thread_pool` | `impl/typed_pool/typed_thread_pool.h` | 우선순위 기반 스케줄링 | -| `adaptive_job_queue` | `queue/adaptive_job_queue.h` | 자동 최적화 큐 | -| `job_queue` | `core/job_queue.h` | Mutex 기반 FIFO 큐 | -| `queue_factory` | `queue/queue_factory.h` | 요구사항 기반 큐 생성 | -| `hazard_pointer` | `core/hazard_pointer.h` | Lock-free 메모리 회수 | -| `cancellation_token` | `core/cancellation_token.h` | 협력적 취소 | -| `service_registry` | `core/service_registry.h` | 의존성 주입 | -| `thread_pool_builder` | `core/thread_pool_builder.h` | 빌더 패턴 풀 생성 | -| `dag_scheduler` | `dag/dag_scheduler.h` | DAG 기반 작업 스케줄링 | +## Examples -**[API 레퍼런스 ->](docs/advanced/API_REFERENCE.md)** +### Sample Applications ---- +- **[thread_pool_sample](examples/thread_pool_sample)**: 적응형 큐를 사용한 기본 스레드 풀 사용법 +- **[typed_thread_pool_sample](examples/typed_thread_pool_sample)**: 우선순위 기반 작업 스케줄링 +- **[adaptive_queue_sample](examples/adaptive_queue_sample)**: 큐 성능 비교 +- **[queue_factory_sample](examples/queue_factory_sample)**: 요구사항 기반 큐 생성 +- **[queue_capabilities_sample](examples/queue_capabilities_sample)**: 런타임 기능 인트로스펙션 +- **[hazard_pointer_sample](examples/hazard_pointer_sample)**: Lock-free 메모리 회수 +- **[integration_example](examples/integration_example)**: logger/monitoring과의 완전한 통합 -## 예제 - -| 예제 | 난이도 | 설명 | -|------|--------|------| -| [thread_pool_sample](examples/thread_pool_sample) | 초급 | 적응형 큐를 사용한 기본 스레드 풀 | -| [typed_thread_pool_sample](examples/typed_thread_pool_sample) | 중급 | 우선순위 기반 작업 스케줄링 | -| [adaptive_queue_sample](examples/adaptive_queue_sample) | 중급 | 큐 성능 비교 | -| [queue_factory_sample](examples/queue_factory_sample) | 중급 | 요구사항 기반 큐 생성 | -| [queue_capabilities_sample](examples/queue_capabilities_sample) | 중급 | 런타임 기능 인트로스펙션 | -| [hazard_pointer_sample](examples/hazard_pointer_sample) | 고급 | Lock-free 메모리 회수 | -| [integration_example](examples/integration_example) | 고급 | logger/monitoring 전체 통합 | - -### 예제 실행 +### Running Examples ```bash -# 모든 예제 빌드 +# Build all examples cmake -B build cmake --build build -# 특정 예제 실행 +# Run specific example ./build/bin/thread_pool_sample ./build/bin/typed_thread_pool_sample ``` --- -## 성능 +## Production Quality -**플랫폼**: Apple M1 @ 3.2GHz, 16GB RAM, macOS Sonoma +### Quality Metrics -### 처리량 메트릭 +- ✅ **95%+ CI/CD 성공률** (모든 플랫폼) +- ✅ **49% 코드 커버리지** (포괄적인 테스트 스위트) +- ✅ **ThreadSanitizer 경고 제로** (프로덕션 코드) +- ✅ **AddressSanitizer 누수 제로** - 100% RAII 준수 +- ✅ **다중 플랫폼 지원**: Linux, macOS, Windows +- ✅ **다중 컴파일러**: GCC 11+, Clang 14+, MSVC 2022+ -| 메트릭 | 값 | 구성 | -|--------|------|------| -| **프로덕션 처리량** | 1.16M jobs/s | 10 워커, 실제 워크로드 | -| **타입드 풀** | 1.24M jobs/s | 6 워커, 6.9% 향상 | -| **Lock-free 큐** | 71 us/op | Mutex 대비 4배 향상 | -| **작업 지연 (P50)** | 77 ns | 마이크로초 이하 | -| **메모리 기준선** | <1 MB | 8 워커 | -| **스케일링 효율** | 96% | 8 워커까지 | +### Thread Safety -### 큐 성능 비교 +다음을 다루는 **70+ 스레드 안전성 테스트**: +- 단일 생산자/소비자 +- 다중 생산자/다중 소비자 (MPMC) +- 적응형 큐 모드 전환 +- 엣지 케이스 (shutdown, overflow, underflow) -| 큐 타입 | 지연 | 적합 대상 | -|---------|------|----------| -| Mutex 큐 | 96 ns | 낮은 경합 (1-2 스레드) | -| 적응형 (자동) | 96-320 ns | 가변 워크로드 | -| Lock-free | 320 ns | 높은 경합 (8+ 스레드), 37% 향상 | +**ThreadSanitizer 결과**: ✅ CLEAN +- 데이터 레이스 제로 +- 데드락 제로 +- 안전한 메모리 접근 패턴 -### 워커 스케일링 +### Resource Management -| 워커 수 | 속도 향상 | 효율 | 등급 | -|---------|----------|------|------| -| 2 | 2.0x | 99% | 우수 | -| 4 | 3.9x | 97.5% | 우수 | -| 8 | 7.7x | 96% | 매우 좋음 | -| 16 | 15.0x | 94% | 매우 좋음 | - -### 품질 메트릭 - -- 95%+ CI/CD 성공률 (모든 플랫폼) -- 72% 코드 커버리지 (포괄적 테스트 스위트) -- ThreadSanitizer 경고 제로 (프로덕션 코드) -- AddressSanitizer 누수 제로 (100% RAII 준수) -- 70+ 스레드 안전성 테스트 +**RAII 준수: Grade A** +- 100% 스마트 포인터 사용 +- 수동 메모리 관리 없음 +- 예외 안전 정리(cleanup) +- 메모리 누수 제로 (AddressSanitizer 검증) -**[전체 벤치마크 ->](docs/BENCHMARKS.md)** +**🛡️ [프로덕션 품질 상세 →](docs/PRODUCTION_QUALITY.md)** --- -## 생태계 통합 - -### 프로젝트 생태계 - -이 프로젝트는 모듈식 생태계의 일부입니다: - -``` -thread_system (핵심 인터페이스) - ^ ^ -logger_system monitoring_system - ^ ^ - +-- integrated_thread_system --+ -``` - -### 선택적 컴포넌트 +## Platform Support -| 프로젝트 | 설명 | 의존성 | -|----------|------|--------| -| [common_system](https://github.com/kcenon/common_system) | C++20 유틸리티 기반 | 필수 | -| [logger_system](https://github.com/kcenon/logger_system) | 고성능 비동기 로깅 | 선택 | -| [monitoring_system](https://github.com/kcenon/monitoring_system) | 실시간 메트릭 및 모니터링 | 선택 | +### Supported Platforms -### 통합 이점 - -- **플러그 앤 플레이**: 필요한 컴포넌트만 사용 -- **인터페이스 기반**: 쉬운 교체를 위한 깔끔한 추상화 -- **성능 최적화**: 각 시스템이 고유 도메인에 최적화 -- **통합 생태계**: 일관된 API 설계 +| 플랫폼 | 컴파일러 | 상태 | +|----------|-----------|--------| +| **Linux** | GCC 11+, Clang 14+ | ✅ 완전 지원 | +| **macOS** | Apple Clang 14+, GCC 11+ | ✅ 완전 지원 | +| **Windows** | MSVC 2022+ | ✅ 완전 지원 | -### 플랫폼 지원 +### Architecture Support -| 플랫폼 | 컴파일러 | 상태 | -|--------|----------|------| -| **Linux** | GCC 11+, Clang 14+ | 완전 지원 | -| **macOS** | Apple Clang 14+, GCC 11+ | 완전 지원 | -| **Windows** | MSVC 2022+ | 완전 지원 | +| 아키텍처 | 상태 | +|--------------|--------| +| x86-64 | ✅ 완전 지원 | +| ARM64 (Apple Silicon, Graviton) | ✅ 완전 지원 | +| ARMv7 | ⚠️ 미검증 | +| RISC-V | ⚠️ 미검증 | --- -## 기여하기 +## Contributing 기여를 환영합니다! 자세한 내용은 [기여 가이드](docs/contributing/CONTRIBUTING.md)를 참조하세요. -### 개발 워크플로우 +### Development Workflow 1. 리포지토리 포크 2. 기능 브랜치 생성 (`git checkout -b feature/amazing-feature`) @@ -445,22 +548,38 @@ logger_system monitoring_system 6. 브랜치 푸시 (`git push origin feature/amazing-feature`) 7. Pull Request 열기 -### 코드 표준 +### Code Standards - 현대 C++ 모범 사례 준수 - RAII 및 스마트 포인터 사용 -- 포괄적 단위 테스트 작성 +- 포괄적인 단위 테스트 작성 - 일관된 포맷팅 유지 (clang-format) - 문서 업데이트 --- -## 라이선스 +## Support + +- **Issues**: [GitHub Issues](https://github.com/kcenon/thread_system/issues) +- **Discussions**: [GitHub Discussions](https://github.com/kcenon/thread_system/discussions) +- **Email**: kcenon@naver.com + +--- + +## License 이 프로젝트는 BSD 3-Clause 라이선스에 따라 배포됩니다 - 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요. --- +## Acknowledgments + +- 현대 동시성 프로그래밍 패턴과 모범 사례에서 영감을 받았습니다 +- 최대 성능과 안전성을 위해 C++20 기능(GCC 11+, Clang 14+, MSVC 2022+)으로 구축되었습니다 +- 관리자: kcenon@naver.com + +--- +

Made with ❤️ by 🍀☀🌕🌥 🌊

diff --git a/README_KO_UPDATE_NOTES.md b/README_KO_UPDATE_NOTES.md deleted file mode 100644 index 034b841bef..0000000000 --- a/README_KO_UPDATE_NOTES.md +++ /dev/null @@ -1,122 +0,0 @@ -# Korean README Update Notes - -**Date**: 2025-11-15 -**Status**: Pending Translation - ---- - -## Changes Required for README.kr.md - -The English README.md has been simplified from 1,329 lines to 429 lines (68% reduction). - -### New Structure - -The Korean README should follow the same simplified structure: - -1. **Overview** (80 lines) - - Brief description - - Key value propositions - - Latest updates - -2. **Quick Start** (100 lines) - - Installation steps - - Basic usage example - - Link to full getting started guide - -3. **Core Features** (60 lines) - - List key features only - - Brief one-line descriptions - - Link to detailed features doc - -4. **Performance Highlights** (50 lines) - - Top 5-6 metrics in table format - - Queue performance comparison - - Worker scaling summary - -5. **Architecture Overview** (50 lines) - - Modular design diagram - - Key components list - - Link to architecture guide - -6. **Documentation Links** (80 lines) - - Getting Started - - Core Documentation - - Advanced Topics - - Development - -7. **Ecosystem Integration** (40 lines) - - Project ecosystem diagram - - Optional components - - Integration benefits - -8. **Production Quality** (40 lines) - - Quality metrics summary - - Thread safety summary - - Link to detailed quality doc - -9. **Platform Support** (30 lines) - - Supported platforms table - - Architecture support - -10. **Contributing** (20 lines) - - Development workflow - - Code standards - -11. **Support & License** (20 lines) - - Contact information - - License - -### Content Extracted to New Korean Docs - -The following detailed content should be extracted to new Korean documentation files: - -1. **docs/FEATURES.kr.md** - Detailed feature descriptions - - Queue implementations - - Thread pool details - - Lock-free structures - - Adaptive components - -2. **docs/BENCHMARKS.kr.md** - Full performance data - - Complete benchmark tables - - Platform comparisons - - Industry standard comparisons - - Optimization insights - -3. **docs/PROJECT_STRUCTURE.kr.md** - Project structure - - Detailed directory descriptions - - File purposes - - Module dependencies - -4. **docs/PRODUCTION_QUALITY.kr.md** - Quality metrics - - CI/CD infrastructure - - Thread safety validation - - Sanitizer results - - Coverage reports - -### Translation Notes - -- Maintain technical terms in English (e.g., "thread pool", "lock-free", "MPMC") -- Keep code examples exactly as-is (no translation needed) -- Translate descriptions and explanations to Korean -- Use consistent terminology with existing Korean documentation -- Ensure all links point to correct Korean versions where available - -### Next Steps - -1. Translate new simplified README structure to Korean -2. Create Korean versions of extracted documentation: - - FEATURES.kr.md - - BENCHMARKS.kr.md - - PROJECT_STRUCTURE.kr.md - - PRODUCTION_QUALITY.kr.md -3. Update links in README.kr.md to point to Korean docs -4. Verify all cross-references are correct - ---- - -**Target Line Count**: ~450 lines (similar to English version) -**Current README.kr.md**: Needs update to match new structure - ---- - -**Maintained by**: kcenon@naver.com diff --git a/VERSIONING.md b/VERSIONING.md new file mode 100644 index 0000000000..4c76f382b0 --- /dev/null +++ b/VERSIONING.md @@ -0,0 +1,63 @@ +# Versioning Policy + +This document is the single source of truth (SSOT) for how `thread_system` is +versioned and released. + +## Overview + +`thread_system` follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0/). + +## Version Format + +Given a version number `MAJOR.MINOR.PATCH`, increment the: + +- **MAJOR** version for incompatible (breaking) public API changes +- **MINOR** version for backward-compatible new functionality +- **PATCH** version for backward-compatible bug fixes + +## Where the Version Lives + +The canonical version is declared in the top-level +[`CMakeLists.txt`](CMakeLists.txt) via the CMake `project(... VERSION X.Y.Z)` +command. This value is exposed at configure time as `PROJECT_VERSION` and is the +authoritative version for the build, packaging, and install steps. + +The same version must be reflected in: + +- [`CHANGELOG.md`](CHANGELOG.md) — a dated section per released version +- The git release tag (e.g., `v1.0.0`) +- The vcpkg manifest (`version-semver` field) + +When bumping the version, update the `project(... VERSION ...)` line first; all +other locations follow from it. + +## Release Process + +1. Update the `VERSION` in `CMakeLists.txt` (`project(thread_system VERSION X.Y.Z ...)`). +2. Move the relevant entries in [`CHANGELOG.md`](CHANGELOG.md) from + `[Unreleased]` into a new dated `[X.Y.Z]` section. +3. Update the vcpkg manifest `version-semver` field to match. +4. Create and push a git tag matching the version (`vX.Y.Z`) to trigger the + release workflow. + +## Pre-Release Versions + +Pre-release builds use a SemVer suffix: + +- `X.Y.Z-alpha.N` — alpha release +- `X.Y.Z-beta.N` — beta release +- `X.Y.Z-rc.N` — release candidate + +## Compatibility Guarantees + +- Within the same MAJOR version, the public API stays backward-compatible. +- Deprecated APIs are marked with `[[deprecated]]` and documented in + [`CHANGELOG.md`](CHANGELOG.md) before removal in a subsequent MAJOR release. +- Internal implementation details (anything under a `detail::` namespace) are + not part of the public API and may change in any release. + +## Related Documents + +- [`CMakeLists.txt`](CMakeLists.txt) — authoritative `PROJECT_VERSION` (SSOT) +- [`CHANGELOG.md`](CHANGELOG.md) — record of all notable changes, following + [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)