Summary

Document the lock-free data structures used internally in container_system, specifically the RCU (Read-Copy-Update) pattern implementation and epoch-based memory reclamation.

Parent Issue

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

Background (Why)

container_system uses sophisticated lock-free algorithms for high-performance concurrent container access. These are implemented in internal/ but have no documentation, making it impossible for:

• Contributors to understand and modify the concurrency primitives
• Advanced users to understand performance characteristics
• Reviewers to verify correctness of the implementation

Source files:

• internal/rcu_value.h — Read-Copy-Update pattern for container values
• internal/epoch_manager.h — Epoch-based memory reclamation to prevent use-after-free

Scope (What)

Create docs/advanced/LOCK_FREE.md covering:

1. RCU Pattern Implementation (rcu_value.h)

• What RCU is and why it's used in container_system
• Read path: How readers access data without locks
• Write path: Copy-on-write semantics for mutations
• Grace period detection for safe memory reclamation
• API: rcu_value<T> interface — read(), update(), synchronize()

2. Epoch-Based Reclamation (epoch_manager.h)

• Problem: Safe memory reclamation in lock-free structures
• Solution: Epoch-based scheme (3-epoch rotation)
• How threads enter/exit critical sections
• When and how retired memory is reclaimed
• API: epoch_manager interface — pin(), unpin(), retire(), gc()

3. Correctness Guarantees

• Memory ordering requirements (acquire/release/seq_cst)
• ABA problem avoidance
• Progress guarantees (lock-free vs wait-free)
• Hazard scenarios and how they're handled

4. Performance Characteristics

• Read-side overhead (expected near-zero)
• Write-side overhead (copy cost + synchronization)
• Memory overhead per epoch
• Scalability with reader count

5. Integration with Container Types

• Which container operations use RCU internally
• How value reads/writes map to RCU operations
• When epoch-based reclamation triggers

6. Comparison with Alternatives

• RCU vs mutex-based: when to choose each
• RCU vs hazard pointers (if applicable)
• Trade-offs: memory usage vs latency vs throughput

Acceptance Criteria

• RCU pattern explained with diagrams
• Epoch-based reclamation algorithm documented
• Memory ordering requirements specified
• API for both classes fully documented
• Performance characteristics described
• Integration with container types explained