feat: add Snapshot() for non-destructive FIFO copy

[maxence2997]

Summary

Adds Snapshot() to both RingBuffer[T] and RingQueue[T] — a non-destructive FIFO copy that fills the gap between Peek() (one item) and Drain() (all items, mutating). Foundational primitive for replay / inspect / filter-without-consuming use cases.

Related issues

Closes #9.

Changes

• refactor: extract RingBuffer segments helper — pull wrap-detection out of Drain/Clear into an unexported segments() helper. Behavior-preserving; BenchmarkRingBuffer_Drain shows no regression (~1290 ns/op vs ~1296 ns/op baseline). Drain's per-segment copy → clear interleaving preserves cacheline locality.
• feat: add RingBuffer Snapshot — non-destructive FIFO copy using segments(). Tests I1–I7 cover empty, non-wrap FIFO, wrap-around FIFO, non-mutation, caller / buffer isolation, full-capacity round-trip.
• feat: add RingQueue Snapshot — lock + delegate to RingBuffer.Snapshot(). No user code ever runs under q.mu. Tests G1–G5 cover empty, FIFO, non-mutation, concurrent enqueue + snapshot (race-clean, monotonicity invariant), and snapshot-after-close.
• test: add Snapshot benchmarks — three benchmarks: BenchmarkRingBuffer_Snapshot (non-wrap), BenchmarkRingBuffer_Snapshot_Wrap (split region), BenchmarkRingQueue_Snapshot. All 1 alloc/op; wrap and non-wrap within noise, confirming the wrap path stays on bulk copy.
• doc: changelog Snapshot entry — Unreleased section.
• style: rename bench const cap — cap shadowed the builtin; renamed to bufCap.
• fix: preserve Clear no-op on empty buffer — restored the if rb.size == 0 { return } guard that the refactor inadvertently dropped, matching pre-refactor contract.
• doc: clarify Snapshot shallow copy and lock cost — note that independence is shallow for pointer/pointer-containing T; document RingQueue.Snapshot's O(N) lock-hold cost.
• sync: register Snapshot in bench docs tables — added rows for the new benchmarks to cmd/benchsync/defaultTargets so make bench-sync keeps docs/ringbuffer.md and docs/ringqueue.md current.

Out of scope (deferred — see #9 for rationale): AppendTo, ForEach, At, MaxAge, Resize.

Checklist

Required

• make check passes (fmt → lint → test)
• Each commit represents exactly one logical change
• Commit messages follow the format in commit-message-instructions.md
• No unrelated code reformatting in this PR

Conditional

• New public API: includes GoDoc comments
• Performance-sensitive change: benchmark included (make bench before/after); Drain refactor shows no regression, Snapshot benches added

[Copilot]

Pull request overview

This PR adds a new non-destructive bulk-read primitive, Snapshot(), to both core data structures (RingBuffer[T] and the concurrent RingQueue[T]) to complement Peek() and Drain() while preserving FIFO order and buffer contents.

Changes:

• Added Snapshot() to RingBuffer[T] and RingQueue[T], including API docs and comprehensive tests/benchmarks.
• Refactored RingBuffer bulk operations by extracting a wrap-aware segments() helper used by Drain()/Clear()/Snapshot().
• Updated benchmark sync targets, benchmark docs tables, and the changelog to reflect the new operation.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
ringbuffer.go	Refactors drain/clear via segments() and introduces RingBuffer.Snapshot().
ringbuffer_test.go	Adds Snapshot test matrix (I1–I7) and Snapshot benchmarks.
ringqueue.go	Adds RingQueue.Snapshot() with mutex-held copy semantics.
ringqueue_test.go	Adds Snapshot tests (G1–G5) and a queue Snapshot benchmark.
cmd/benchsync/main.go	Registers Snapshot benchmarks in default benchsync targets.
cmd/benchsync/main_test.go	Updates golden output to include Snapshot benchmarks.
docs/ringbuffer.md	Updates benchmark table and notes to include Snapshot performance.
docs/ringqueue.md	Updates benchmark table to include Snapshot.
CHANGELOG.md	Adds Unreleased changelog entry for Snapshot APIs.
.gitignore	Ignores .mx/.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated no new comments.