cache

type ChainConfig struct {
	// OnPromoteError, if non-nil, is called when a value served from a FAR
	// tier could not be written into a nearer one.
	//
	// A failed promotion is not a failed read: the caller already has the
	// value, and failing the call would turn a degraded cache into a degraded
	// service. But it is also not nothing — a near tier that rejects every
	// promotion is a tier that will never be used again, and with this hook nil
	// that is completely invisible. Wire it.
	OnPromoteError func(key string, err error)
	// Clock is what LoadLeased waits on between two reads while another
	// process holds a key's lease. nil means clock.System. Nothing else in
	// the chain reads time: every tier keeps its own clock.
	Clock clock.Timed
	// LeasePoll is how often LoadLeased reads the chain again while another
	// process holds a key's lease. 0 means 25ms, the file locker's own poll;
	// negative is refused.
	LeasePoll time.Duration
}

type MemoryConfig struct {
	// MaxEntries caps the live entry count; the least-recently-used entry is
	// evicted above it. It MUST be positive.
	MaxEntries int
	// DefaultTTL applies to every entry whose own TTL is zero. Zero means the
	// default is "no deadline", so entries leave only by eviction, by Delete,
	// or by tag invalidation. Negative is refused.
	DefaultTTL time.Duration
	// Clock is the time source, injectable so TTL is testable. nil means
	// clock.System. Only the reading half of the port is required — a cache
	// reads time (ADR 0039); LoadLeased alone waits, on Clock when it can wait
	// (clock.System, a clock.ManualClock) and on clock.System otherwise. A
	// clock.CoarseClock makes a TTL'd hit's clock read an atomic load, and
	// every expiry late by up to its resolution.
	Clock clock.Clock
	// Stripes splits the store into independent stripes, each with its own
	// lock, its own share of MaxEntries and MaxBytes and its own tag index, so
	// goroutines working on keys of different stripes never wait for one
	// another. 0 means 1, one store as before; above MaxEntries (or a positive
	// MaxBytes) it is held there, and above 1024 at 1024. Negative is refused.
	Stripes int
	// MaxBytes bounds the summed weight of the live values, as measured by the
	// weigher handed to [NewWeighedMemory]; entries are evicted above it as
	// above MaxEntries, both bounds applying. 0 means no byte bound. An entry
	// heavier than one stripe's share of it is refused with
	// CACHE_ENTRY_REJECTED at Set. Negative is refused, and so is a positive
	// MaxBytes given to [NewMemory], which has no weigher to measure it with.
	MaxBytes int64
	// Policy is the eviction policy: least recently used (the zero), or
	// S3-FIFO, which keeps a hot set through a scan.
	Policy kcache.Policy
	// LeasePoll is how often LoadLeased reads the store again while another
	// process holds a key's lease. 0 means 25ms, the file locker's own poll;
	// negative is refused.
	LeasePoll time.Duration
}