From 2a3f185410928897e5ab605bcb6976b2f529eb2f Mon Sep 17 00:00:00 2001 From: kcenon Date: Sat, 30 May 2026 22:45:16 +0900 Subject: [PATCH 1/2] chore(docs): add VERSIONING.md describing SemVer policy --- VERSIONING.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 VERSIONING.md 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/) From 529423251f6a76ead326a43fd0cace3841e80042 Mon Sep 17 00:00:00 2001 From: kcenon Date: Sat, 30 May 2026 22:45:16 +0900 Subject: [PATCH 2/2] chore(docs): expand Korean README and remove stray root notes Rewrite README.kr.md to mirror the full English README.md heading structure (same heading order and levels) via faithful Korean translation, raising coverage well above the 70% target. Remove the stray root files ANALYSIS_README.md and README_KO_UPDATE_NOTES.md, and record all changes in CHANGELOG.md under [Unreleased]. --- ANALYSIS_README.md | 275 --------------- CHANGELOG.md | 12 + README.kr.md | 685 ++++++++++++++++++++++---------------- README_KO_UPDATE_NOTES.md | 122 ------- 4 files changed, 414 insertions(+), 680 deletions(-) delete mode 100644 ANALYSIS_README.md delete mode 100644 README_KO_UPDATE_NOTES.md 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