cachekit 0.6.0

High-performance cache primitives with pluggable eviction policies (LRU, LFU, FIFO, 2Q, Clock-PRO, S3-FIFO) and optional metrics.
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

# Clock Ring (Second-Chance)

## What It Is
The **Clock** policy maintains a circular set of slots and a moving “hand”. Each slot has a reference bit.

This is a general-purpose DS for:
- Clock / second-chance eviction
- CAR/CLOCK-Pro style variants (with extra status bits)

## Core Types
- `slots: Vec<SlotMeta>` (dense)
- `hand: usize`
- `index: HashMap<K, usize>` (key → slot)

Minimal `SlotMeta`:
- `key: K` (or empty)
- `referenced: bool`
- `occupied: bool`

## Operations

### `touch(key)`
- Find slot via index; set `referenced = true`.

### `insert(key, value)`
- If key exists: update value + `referenced = true`.
- Else: find a free slot or evict:
  - Loop: if `referenced` set → clear it and advance; else evict this slot.

### `evict_one() -> K`
- Advance hand until a victim is found; return victim key.

## Complexity
- O(1) amortized for eviction; worst-case can scan many slots if all are referenced.

## Implementation Notes
- Use a dense array of slots for locality; avoid linked lists.
- For predictable performance, consider limiting scan length or adding an epoch-based reference reset (NRU-like).