You are working in a Rust cache library.
Goals
- Optimize for expected workload patterns before choosing a policy.
- Keep hot paths allocation-free and predictable.
- Favor memory layout efficiency over algorithmic complexity.
- Treat concurrency as a core design choice, not a wrapper.
Design Rules
- Separate policy from storage; policies only manage metadata and ordering.
- Prefer contiguous storage and index-based indirection over pointer chasing.
- Avoid per-operation allocations; pre-allocate pools/arenas and reuse.
- Keep eviction O(1) with direct indices/handles; no scans or tree walks.
- Make concurrency strategy explicit (global lock, sharded, or mostly lock-free).
- Avoid heavy Rust ergonomics in hot loops (trait objects, iterator chains, closures).
- Keep metadata tight; split hot metadata from cold payloads when possible.
Workload & Benchmarks
- Assume scan-heavy and skewed workloads; prefer scan-resistant policies when needed.
- Evaluate with Zipfian, scan + point lookup, and mixed read/write patterns.
- Track tail latency, throughput, eviction cost, and memory overhead.
Metrics & Observability
- Include lightweight counters for hit/miss, evictions, inserts/updates.
- Gate detailed metrics behind feature flags.
Rust Pitfalls
- Minimize Arc usage in hot paths; avoid hidden clones.
- Prefer explicit loops and concrete types in performance-critical code.
Documentation Layout
- Use a consistent module doc layout: Architecture, Key Components, Core Operations, Performance Trade-offs, When to Use, Example Usage, Type Constraints, Thread Safety, Implementation Notes.
- Keep examples short, compile-ready, and focused on a single use case.
- Document public methods with concise docstrings; avoid restating the signature.
Docstring Style Guide
- Use Rustdoc (`//!` for modules, `///` for items).
- Prefer one-sentence summaries; mention invariants or complexity only when they matter.
- Avoid Args/Returns sections unless behavior is non-obvious.
- Template:
//! ## Architecture
//! ...
/// Brief summary of behavior.