cache

Documentation

Index

• type Cache
  • func New[V any](level string) (Cache[string, V], error)
• type Default
  • func (c *Default[K, V]) Get(key K) (V, bool)
  • func (c *Default[K, V]) Set(key K, value V, cost int64) bool
  • func (c *Default[K, V]) SetWithTTL(key K, value V, cost int64, ttl time.Duration) bool

Types

type Cache

type Cache[K comparable, V any] interface {
	// Get retrieves a value from the cache
	Get(key K) (V, bool)

	// Set stores a value with cost, returning true if successful
	Set(key K, value V, cost int64) bool

	// SetWithTTL stores a value with cost and TTL, returning true if successful
	SetWithTTL(key K, value V, cost int64, ttl time.Duration) bool
}

Cache defines a generic interface compatible with Ristretto and other caches

func New

func New[V any](level string) (Cache[string, V], error)

New creates a cache for string keys based on a predefined level. It translates the level to a max-entry cap using cacheLevels.

type Default

type Default[K comparable, V any] struct {
	// contains filtered or unexported fields
}

Default is a preallocated, fixed-capacity LRU cache with lazy expiration. It is the framework's shipped implementation of the Cache interface.

Storage is allocated once at construction and never grows:

• nodes is a fixed array of max nodes; prev/next are indexes into it
• index maps each key to its node
• free holds the indexes of unused nodes

LRU order is a doubly-linked list running left to right: head (left, most-recently-used) <-> ... <-> tail (right, least-recently-used). Each node's prev points left toward head, next points right toward tail.

Why LRU: the cache never holds more than max nodes. When it is full and a new key arrives, an old one must leave. LRU removes the node unused for the longest time, betting that anything touched recently will be asked for again soon and long-idle keys will not.

Expired nodes are removed lazily on Get. When the cache is full, Set evicts the least-recently-used node (the LRU tail, rightmost) to make room.

TODO: proactive reclamation of expired nodes that are never read again (rotating cursor sweep W/K — W window nodes per sweep, every K writes, inline on writes) is not yet implemented. See doc/TODO.md "cache: rotating cursor sweep (W/K)" and brainstorm-remove-ristretto.md Q33/Q40.

func (*Default[K, V]) Get

func (c *Default[K, V]) Get(key K) (V, bool)

Get retrieves the value for key, moving it to the LRU head on a hit.

An expired node is removed lazily on read and reported as a miss.

func (*Default[K, V]) Set

func (c *Default[K, V]) Set(key K, value V, cost int64) bool

Set stores key with value and cost. Cost is accepted for interface compatibility and currently unused.

func (*Default[K, V]) SetWithTTL

func (c *Default[K, V]) SetWithTTL(key K, value V, cost int64, ttl time.Duration) bool

SetWithTTL stores key with value, cost and TTL.

A zero TTL means the node never expires. A negative TTL is a no-op and returns false. When the cache is full, the least-recently-used node is evicted to make room.