Summary

Create a comprehensive guide documenting all policy queue combinations (SyncPolicy × BoundPolicy × OverflowPolicy) with their characteristics, trade-offs, and recommended use cases.

Parent Issue

Part of: [EPIC] docs: Address documentation gaps across all ecosystem systems (kcenon/common_system#325)

Background (Why)

thread_system implements a powerful policy-based queue system with 3 orthogonal policy dimensions:

• SyncPolicy (policies/sync_policies.h): Controls synchronization (mutex-based, lock-free, etc.)
• BoundPolicy (policies/bound_policies.h): Controls queue capacity (unbounded, fixed, dynamic)
• OverflowPolicy (policies/overflow_policies.h): Controls behavior when queue is full (block, drop, resize)

The combinatorial matrix (policies/policy_queue.h) creates 9+ possible queue configurations, but there is no documentation explaining which combinations are valid, tested, or recommended for specific use cases. Users must trial-and-error their way through configurations.

Source files:

• include/kcenon/thread/policies/sync_policies.h
• include/kcenon/thread/policies/bound_policies.h
• include/kcenon/thread/policies/overflow_policies.h
• include/kcenon/thread/policies/policy_queue.h
• include/kcenon/thread/policies/policies.h

Scope (What)

Create docs/POLICY_QUEUE_GUIDE.md covering:

1. Policy System Overview

• Template-based policy composition pattern
• How policy_queue<SyncPolicy, BoundPolicy, OverflowPolicy> works
• Compile-time policy validation (if any concepts are used)

2. Individual Policies

SyncPolicy Options

BoundPolicy Options

OverflowPolicy Options

3. Recommended Combinations

4. Performance Characteristics

• Throughput comparison across combinations
• Latency profiles (P50, P99, P999)
• Memory usage per configuration
• Thread scaling behavior

5. Code Examples

// Example for each recommended combination
using low_latency_queue = policy_queue<
    lock_free_sync, fixed_bound<1024>, drop_oldest_overflow>;

using reliable_queue = policy_queue<
    mutex_sync, unbounded, block_overflow>;

6. Anti-Patterns

• Combinations to avoid and why
• Common misconfiguration pitfalls

Acceptance Criteria

• All individual policies documented with interface
• Combination matrix with validity indicators
• At least 5 recommended combinations with rationale
• Performance comparison data or estimates
• Code examples for each recommended combination
• Anti-patterns section with explanations