Retracted: these held pkg/ and internal/, now a module per pkg/v1 family and github.com/kitsunium/sdk/internal (ADR 0171): go get github.com/kitsunium/sdk@latest && go mod tidy
README
¶
cache
Generic concurrency-safe LRU + TTL cache Cache[K,V] — a kernel primitive
(stdlib-only, no domain vocabulary; reuses the kernel clock for testable TTL).
c := cache.NewCache[string, int](cache.Config[string, int]{MaxEntries: 1024, DefaultTTL: time.Minute})
c.Set("k", 7)
v, ok := c.Fetch("k") // 7, true (Fetch, not Get — a hit promotes LRU)
Public facade: pkg/v1/data/cache. ADR 0027. See CLAUDE.md.
Documentation
¶
Overview ¶
Package cache provides a generic, concurrency-safe LRU + TTL cache (Cache[K,V]) — a kernel primitive (stdlib-only, no domain vocabulary). It reuses the kernel clock so TTL expiry is testable. Fetch on a hit is allocation-free (map lookup + intrusive-list splice); Set allocates one entry per new key. Reads and writes are serialised by a single mutex. Fetch is named Fetch (not Get) because a hit mutates state (LRU promotion + counters).
Package cache — the New constructor configuration.
Package cache — the intrusive doubly-linked LRU node.
Package cache — the key/value pair carried out of the locked section so the OnEvict observer never runs while the cache mutex is held.
Package cache — the read-only counters snapshot.
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 a generic LRU+TTL cache safe for concurrent use. The zero value is NOT usable — construct with NewCache.
func NewCache ¶
func NewCache[K comparable, V any](cfg Config[K, V]) *Cache[K, V]
NewCache builds a Cache from cfg. A nil cfg.Clock defaults to clock.System.
func (*Cache[K, V]) Delete ¶
func (c *Cache[K, V]) Delete(key K)
Delete removes key if present. An explicit Delete does NOT fire OnEvict (that hook is for capacity/expiry removals only).
func (*Cache[K, V]) Fetch ¶
Fetch returns the value for key and whether it was present and unexpired. A hit promotes the entry to most-recently-used (hence Fetch, not a pure Get).
func (*Cache[K, V]) Len ¶
Len returns the current live entry count (including not-yet-reaped expired entries — expiry is lazy).
func (*Cache[K, V]) Purge ¶
func (c *Cache[K, V]) Purge()
Purge drops every entry without firing OnEvict.
func (*Cache[K, V]) Set ¶
func (c *Cache[K, V]) Set(key K, val V)
Set stores key=val with the cache's default TTL.
func (*Cache[K, V]) SetTTL ¶
SetTTL stores key=val with an explicit ttl (0 = no expiry), overriding the default for this entry only.
func (*Cache[K, V]) Stats ¶
func (c *Cache[K, V]) Stats() StatsValue
Stats returns a point-in-time copy of the hit/miss/eviction counters.
type Config ¶
type Config[K comparable, V any] struct { // MaxEntries caps the live entry count (LRU eviction above it). 0 = unbounded. MaxEntries int // DefaultTTL applies to Set entries (SetTTL overrides per-entry). 0 = no expiry. DefaultTTL time.Duration // Clock is the time source (injectable for tests). nil = clock.System. Clock clock.Clock // OnEvict, if non-nil, is called with the key+value of every entry removed by // capacity eviction or expiry (not by an explicit Delete/Set-overwrite). OnEvict func(key K, val V) }
Config parameterises a Cache. The zero value is valid: an unbounded cache with no default TTL, the system clock, and no eviction callback.
type StatsValue ¶
StatsValue is a point-in-time copy of a Cache's counters. Hits/Misses count Fetch outcomes; Evictions counts capacity + expiry removals (not explicit Deletes).
Source Files