package valkey

  1. Overview
  2. Docs
package valkey
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module Valkey.CacheSource

Bounded in-process cache for client-side caching.

Each entry is keyed by a string (the Valkey key bytes) and holds a Resp3.t value (the typed response). Eviction is LRU by recency-of-access; the cache stays under a byte budget by evicting the tail of the LRU list until the budget is satisfied.

Concurrency: every public operation is internally synchronised by an Eio.Mutex.t. Safe to call from multiple Eio fibers concurrently — fibers serialise on the mutex.

This module is the storage primitive only. The connection-side tracking handshake, invalidator fiber, and race-safe GET path that sit on top of it land in subsequent steps. See docs/client-side-caching.md.

Sourcetype t
Sourceval create : byte_budget:int -> t

create ~byte_budget builds an empty cache. Eviction kicks in when the total accounted size of all entries exceeds byte_budget.

Sourceval get : t -> string -> Resp3.t option

get t key returns the cached value if present, else None. A successful lookup updates the entry's recency, moving it to the head of the LRU list.

Sourceval put : ?ttl_ms:int -> t -> string -> Resp3.t -> unit

put ?ttl_ms t key value inserts (key, value), replacing any prior entry for key. If after insertion the total size would exceed the byte budget, LRU entries are evicted from the tail until the budget is satisfied.

If ttl_ms is given, the entry carries a wall-clock expiry (same epoch as Unix.gettimeofday). Expired entries are evicted lazily on the next get that hits them. If ttl_ms is omitted, the entry has no expiry and lives until evicted or replaced.

If the size of value alone (per size_of) is strictly larger than the byte budget, the entry is not inserted and any prior entry for key is left untouched.

Sourceval evict : t -> string -> unit

evict t key removes the entry if present. No-op if absent.

Sourceval clear : t -> unit

clear t removes all entries. Used by the reconnect-flush invariant: when a tracked connection drops, the server forgets its per-client tracking state and we cannot trust any cached entry until the new connection re-tracks.

Sourceval size : t -> int

size t is the total accounted bytes currently held by the cache. Bounded above by byte_budget.

Sourceval count : t -> int

count t is the number of entries currently in the cache.

Sourceval size_of : Resp3.t -> int

size_of value is the byte accounting for value used by put. Exposed so tests and callers can predict eviction behaviour. Approximate — see docs/client-side-caching.md for the exact formula.

Sourcetype metrics = {
  1. hits : int;
  2. misses : int;
  3. evicts_budget : int;
    (*

    Evictions triggered by byte-budget pressure.

    *)
  4. evicts_ttl : int;
    (*

    Evictions triggered by lazy TTL expiry.

    *)
  5. invalidations : int;
    (*

    Entries removed via evict or invalidator fiber.

    *)
  6. puts : int;
    (*

    Total put calls (including rejected-oversize).

    *)
}

Monotonic counters for cache activity. puts increments on every put call (including ones rejected because the value exceeded the byte budget — the caller still asked).

Sourceval metrics : t -> metrics

metrics t returns a snapshot of the counters. Non-locking — atomic reads only.

Sourceval reset_metrics : t -> unit

reset_metrics t zeros every counter. Useful for benchmarks or test harnesses that want a clean window.