benchmark 0.8.0

Nanosecond-precision benchmarking for dev, testing, and production. Zero-overhead core timing when disabled; optional std-powered collectors and zero-dependency metrics (Watch/Timer) for real service observability.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

# Developer Profiling Checklist

This checklist captures the exact steps and data to collect for performance profiling. Keep results brief and paste summaries back into `docs/BENCHMARK.md` (Allocations and Contention sections).

## 1) Prereqs
- xcode-select --install
- brew install cargo-instruments

## 2) Allocations (memory usage)
Benchmarks: `overhead`, `stats`

Commands:
```bash
cargo instruments --bench overhead --template Allocations --time-limit 10
cargo instruments --bench stats    --template Allocations --time-limit 10
```
Capture:
- allocs/iteration
- bytes/iteration

Paste into `docs/BENCHMARK.md` → “Allocations (placeholder)” table:
```
bench     allocs/iter   bytes/iter
overhead  <NUM>         <BYTES>
stats     <NUM>         <BYTES>
```
Notes: Hot paths should be ~0 allocs; explain any non-zero (e.g., formatting, map growth).

## 3) Contention (time profiler)
Benchmark: `collector_contention` (scenarios: `single_key`, `many_keys`)

Run bench & profile:
```bash
cargo bench --bench collector_contention
cargo instruments --bench collector_contention --template "Time Profiler" --time-limit 15
```
Capture:
- For threads = [1,2,4,8,16]
- Top hotspots (function -> % time)
- Scaling differences between `single_key` and `many_keys`

Paste into `docs/BENCHMARK.md` → “Contention Profile (placeholder)” matrix:
```
threads  scenario      top hotspots (function -> %time)
1        single_key    ...
2        single_key    ...
4        single_key    ...
8        single_key    ...
16       single_key    ...

1        many_keys     ...
2        many_keys     ...
4        many_keys     ...
8        many_keys     ...
16       many_keys     ...
```

## 4) Finalize docs
- Update `docs/BENCHMARK.md` placeholders with collected numbers.
- Commit with message: "docs(bench): add allocations + contention results".