Storage tiers

bouine uses a two-tier storage architecture: a fast in-memory hot tier and an optional disk-backed warm tier.

Hot tier (RAM)#

The primary cache store. Every cache hit is served from here.

storage:
  hot_max_bytes: 2GiB

How SIEVE works#

SIEVE maintains a FIFO queue with a single “visited” bit per entry. On eviction, it scans from the tail, evicts the first unvisited entry, and marks visited entries as unvisited. This gives recently-accessed objects a second chance without the overhead of LRU pointer updates.

Eviction algorithms: sieve and cachaner#

storage:
  hot_max_bytes: 2GiB
  eviction_algorithm: cachaner   # or "sieve" (default)

cachaner (v0.4.2+) extends SIEVE’s 1-bit visited field with a 3-bit saturating frequency counter, giving hot objects up to 7 second chances across sweep passes (vs SIEVE’s 1) before eviction. The hit path is unchanged — the counter is only touched on the slow path and during eviction, so the zero-allocation hit path is identical.

Per-tier overrides: hot_eviction_algorithm and warm_eviction_algorithm accept the same values (sieve/cachaner).

Monitoring#

When bouine_hot_store_bytes / hot_max_bytes > 0.9 for an extended period, consider increasing hot_max_bytes or reviewing whether low-value objects are consuming cache space.

Warm tier (disk)#

An optional mmap-backed tier for objects evicted from the hot tier. Enables much larger effective cache sizes without proportional RAM costs.

storage:
  warm_dir: /var/lib/bouine
  warm_max_bytes: 50GiB

When to enable#

• Your working set exceeds available RAM.
• You want to reduce origin load during cold starts (warm tier persists across restarts).
• You can tolerate slightly higher tail latency for warm-tier reads vs. hot-tier reads.

Kubernetes volume#

The Helm chart provisions a PersistentVolumeClaim per StatefulSet replica:

warmVolume:
  enabled: true
  size: 50Gi
  storageClass: ""   # uses cluster default

Behavior#

• Objects evicted from the hot tier are written to warm-tier segments.
• On a hot-tier miss, the warm tier is checked before going to origin.
• Warm-tier reads promote the object back to the hot tier.
• Segment files are compacted periodically to reclaim space from deleted entries.

Sizing guidelines#

Cluster mode impact#

Configuration not reloadable#

Storage settings (hot_max_bytes, warm_dir, warm_max_bytes) require a restart to take effect.