Skip to content

docs: add NUMA topology and work-stealing guide#536

Merged
kcenon merged 1 commit into
mainfrom
docs/issue-531-document-numa-topology-and-work-stealing
Feb 8, 2026
Merged

docs: add NUMA topology and work-stealing guide#536
kcenon merged 1 commit into
mainfrom
docs/issue-531-document-numa-topology-and-work-stealing

Conversation

@kcenon

@kcenon kcenon commented Feb 8, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Summary

  • Add comprehensive NUMA topology and work-stealing subsystem documentation (docs/NUMA_GUIDE.md)
  • Covers NUMA overview, topology detection, NUMA thread pool, work stealing, configuration, metrics, examples, performance tuning, anti-patterns, and troubleshooting
  • All 6 acceptance criteria from issue [Task] docs: Document NUMA topology and work-stealing subsystem #531 addressed

Closes #531

Changes

  • New file: docs/NUMA_GUIDE.md (815 lines)
    • Architecture overview with component interaction diagram
    • Platform-specific topology detection (Linux sysfs, macOS/Windows fallback)
    • numa_thread_pool API reference with 3 constructor variants
    • 6 victim selection policies: random, round_robin, adaptive, numa_aware, locality_aware, hierarchical
    • 5 factory configuration presets with full parameter tables
    • Work stealing statistics and monitoring guide
    • Work affinity tracking and cooperation matrix explanation
    • 4 backoff strategies with timing calculations
    • Complete code examples using modern job_builder API
    • Performance tuning guidelines with profiling workflow
    • Anti-patterns with corrections
    • Troubleshooting section with common issues

Test Plan

  • All code examples use correct API signatures verified against source headers
  • Default values and thresholds match enhanced_work_stealing_config.h
  • Factory preset configurations match source implementations
  • Cross-references to related docs (ARCHITECTURE.md, AUTOSCALER_GUIDE.md) are valid

@kcenon
docs: add NUMA topology and work-stealing guide (#531)
04f6776 
Comprehensive documentation for the NUMA subsystem covering:
- NUMA concepts with architecture diagrams
- Topology detection (Linux sysfs, macOS/Windows fallback)
- numa_thread_pool API (extends thread_pool)
- Work stealing with 6 victim selection policies
- enhanced_work_stealing_config with 5 factory presets
- Metrics and observability (atomic stats, computed metrics)
- Usage examples for basic, custom, hierarchical, and monitoring
- Performance tuning guidelines (policies, penalties, batching)
- Anti-patterns and troubleshooting
@kcenon kcenon mentioned this pull request Feb 8, 2026
Closed
6 tasks
@github-actions

github-actions Bot commented Feb 8, 2026

Copy link
Copy Markdown
Contributor

📊 Performance Benchmark Results

Performance Benchmark Report

No benchmark data available.

ℹ️ No baseline reference available

This is the first benchmark run or baseline file is missing.

@kcenon

kcenon commented Feb 8, 2026

Copy link
Copy Markdown
Owner Author

Test Plan Verification Results

All 4 test plan items verified against source code. No bugs found.

1. Code Examples API Signatures — PASS

Verified all code examples across 10 sections against 9 source headers:

  • numa_topology API: 9 methods checked ✅
  • numa_node struct: 3 fields exact match ✅
  • numa_thread_pool constructors: 3 variants correct ✅
  • numa_thread_pool NUMA API: 8 methods checked ✅
  • numa_work_stealer API: constructor + 3 methods correct ✅
  • work_stealing_stats_snapshot API: 4 computed methods correct ✅
  • enhanced_steal_policy enum: 6 values correct ✅
  • steal_backoff_strategy enum: 4 values correct ✅
  • job_builder fluent API: .name().work().build() pattern correct ✅
  • Anti-patterns: 5 examples use correct field names/types ✅

2. Default Values and Thresholds — PASS (17/17)

All 17 defaults in the Configuration Reference table match enhanced_work_stealing_config.h:

  • enabled=false, policy=adaptive, numa_aware=false, numa_penalty_factor=2.0
  • prefer_same_node=true, min_steal_batch=1, max_steal_batch=4
  • adaptive_batch_size=true, max_steal_attempts=3, max_consecutive_failures=10
  • backoff_strategy=exponential, initial_backoff=50µs, max_backoff=1000µs
  • backoff_multiplier=2.0, track_locality=false, locality_history_size=16
  • collect_statistics=false

3. Factory Preset Configurations — PASS (5/5)

Preset Summary Table Detail Comments Source
default_config() ✅ ✅ :168-171
numa_optimized() ✅ ✅ :177-187
locality_optimized() ✅ ✅ :193-202
batch_optimized() ✅ ✅ :208-217
hierarchical_numa() ✅ ✅ :223-234

4. Cross-References — PASS (14/14)

  • Related documentation links: 5/5 resolve (ARCHITECTURE.md, AUTOSCALER_GUIDE.md, POLICY_QUEUE_GUIDE.md, API_REFERENCE.md, BENCHMARKS.md)
  • Source file header links: 9/9 resolve (all ../include/kcenon/thread/... paths valid)

Conclusion

All test plan items pass. The documentation accurately reflects the source code with zero discrepancies.

@kcenon kcenon merged commit 797418a into main Feb 8, 2026
26 checks passed
@kcenon kcenon deleted the docs/issue-531-document-numa-topology-and-work-stealing branch February 8, 2026 15:42
kcenon added a commit that referenced this pull request Apr 13, 2026
@kcenon
docs: add NUMA topology and work-stealing guide (#531) (#536)
cedd96e 
Comprehensive documentation for the NUMA subsystem covering:
- NUMA concepts with architecture diagrams
- Topology detection (Linux sysfs, macOS/Windows fallback)
- numa_thread_pool API (extends thread_pool)
- Work stealing with 6 victim selection policies
- enhanced_work_stealing_config with 5 factory presets
- Metrics and observability (atomic stats, computed metrics)
- Usage examples for basic, custom, hierarchical, and monitoring
- Performance tuning guidelines (policies, penalties, batching)
- Anti-patterns and troubleshooting
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Task] docs: Document NUMA topology and work-stealing subsystem

1 participant

@kcenon