Documentation
¶
Overview ¶
Package cache is an in-memory, batch-first read-through cache: one in-flight load per key, stale-while-revalidate, bounded staleness and failure backoff on upstream errors, and invalidation that beats in-flight loads. The caller owns the policy.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache[K comparable, V any] struct { // contains filtered or unexported fields }
Cache is safe for concurrent use.
func (*Cache[K, V]) Close ¶
func (c *Cache[K, V]) Close()
Close stops the cache's background expiry goroutines so a discarded cache can be collected. It is idempotent; the cache keeps working after Close (expired entries are still never served, only removed later).
func (*Cache[K, V]) Get ¶
Get returns the cached or loaded values for keys; keys Load did not find are omitted. Missing keys load once across concurrent callers, detached from ctx: a caller whose ctx ends gets ctx.Err() while the load still completes and is cached. A key without a value whose load failed less than FailureBackoff ago returns that error again without loading. On error the map still holds the keys that were available.
func (*Cache[K, V]) Invalidate ¶
func (c *Cache[K, V]) Invalidate(keys ...K)
Invalidate drops keys and their recorded failures; a load or reload already in flight for them is discarded.
func (*Cache[K, V]) InvalidateAll ¶
func (c *Cache[K, V]) InvalidateAll()
InvalidateAll drops every key, as Invalidate.
func (*Cache[K, V]) Refresh ¶
Refresh reloads keys now, joining a load already in flight for them, and waits for it (the load itself is detached from ctx). The map holds each key's value afterwards: the reloaded one or, when its load failed, the value still cached, which a failed Refresh keeps; the error joins the load errors. Keys the load did not find are dropped and omitted. FailureBackoff does not delay a Refresh.
type Load ¶
type Load[K comparable, V any] func(ctx context.Context, keys []K) (map[K]V, error)
Load returns the values for keys; a key missing from the map is not found (not cached).
type Options ¶
type Options struct {
Name string // metrics/log label; caches sharing a Name share Stats
RefreshAfter time.Duration // serve the cached value and reload in the background after this
MaxStale time.Duration // past this since the last good load, a failed reload's error surfaces
LoadTimeout time.Duration // deadline of a detached load (10s)
FailureBackoff time.Duration // minimum gap between failed loads of one key (5s)
MaxEntries int // bound on cached keys (10_000)
Clock Clock // nil = real time; for tests
}
Options is a cache's policy. Name, RefreshAfter and MaxStale are required; zero mechanical knobs take the defaults in parentheses.
Source Files