Cache Replacement Policy

When the cache device is full and a new chunk needs a slot, flexBlock evicts a clean chunk. The replacement policy decides which one. The default suits most workloads; this page explains it and the alternatives.

twoq-meta (default)

The default policy, twoq-meta, is a 2Q variant that understands filesystem metadata:

• New chunks go to a probationary queue (A1in).
• Filesystem metadata, which the kernel tags on each request, goes straight to a protected main queue (Am).
• Recently evicted chunks are remembered, by identity only, in a ghost list (A1out). A chunk that comes back soon after eviction goes straight to Am.

The effect is that a large sequential scan passes through A1in and out again without evicting the working set held in Am.

lru

lru is a plain least-recently-used policy. It suits workloads with no reuse structure. Under lru, the Am and A1out metrics stay at zero by design.

Flags

Flag	Default	Meaning
--a1in-ratio <R>	0.25	Fraction of slots for the probationary A1in queue, in (0.05, 0.50].
--a1out-multiple <M>	0.5	Ghost-list size as a multiple of slots, in [0.5, 64]; twoq-meta only. Holds identities, not data.
--cache-io-mode <direct|buffered>	direct	Whether cache device I/O bypasses the page cache.
--cache-policy <lru|twoq-meta>	twoq-meta	Replacement policy.
--read-prefetch <N|off>	32	Largest window of chunks to fetch ahead of a sequential cold read, at most 64. Each is one chunk of speculative download.

sudo flexblock start /dev/nvme1n1p1 --cache-policy lru

Buffered cache I/O

If a leftover kernel device was created while cache writes were durable, start refuses a run that adds --cache-io-mode buffered (exit code 9). See Common Issues.

Sequential prefetch

When a cold read misses on a chunk just past an earlier miss, flexBlock treats it as a sequential scan. It fetches the next two chunks in the background and doubles that window each time a read or partial write reaches a prefetched chunk, up to --read-prefetch. A scan of cold data is then not paced by one object storage round trip per chunk, while a random read that spans a few chunks fetches only a few more. off disables prefetch.

Measuring the cache

What	Series
Hit rate	flexblock_cache_hits_total against flexblock_cache_misses_total
Active policy	flexblock_cache_policy_info (policy label)
Queue sizes	flexblock_cache_a1in_size, flexblock_cache_am_size, flexblock_cache_a1out_size
Ghost-list reuse	flexblock_cache_a1out_promotions_total
Prefetch	flexblock_prefetch_issued_total, flexblock_prefetch_completed_total, flexblock_prefetch_failed_total

The full list is in the Metrics Reference.

Related

• Volumes and the Cache
• Write-Back Behavior
• flexblock start