cache

new_lru[K, V](capacity) creates a least-recently-used cache with a positive capacity. put inserts or replaces a value; get returns an option and promotes a hit. get_or_compute calls its factory only on a miss. contains does not change recency. delete reports whether a key was present, and len counts stored entries. Recency maintenance is linear in the number of cached entries.

new_ttl[K, V](ttl) creates a cache whose entries expire after the given duration. set restarts an entry's TTL; get removes an expired entry and returns none. purge_expired removes all expired entries and returns their count. len includes expired entries until they are accessed or purged. Expiry has millisecond resolution; a TTL below one millisecond expires immediately. The default clock is monotonic. new_ttl_with_clock[K, V](ttl, now) accepts a callback returning millisecond timestamps; custom clocks should be monotonic too.

Both caches are single-threaded. Synchronize access before sharing a cache between threads. Keys must be supported V map keys.

fn new_lru[K, V](cap int) Lru[K, V]

new_lru creates an Lru holding at most cap entries.

fn new_ttl[K, V](ttl time.Duration) Ttl[K, V]

new_ttl creates a Ttl expiring entries ttl after each set.

fn new_ttl_with_clock[K, V](ttl time.Duration, now fn () i64) Ttl[K, V]

new_ttl_with_clock is new_ttl with an injectable millisecond clock, for tests and custom time sources.

fn (mut c Lru[K, V]) get(key K) ?V

get returns the value for key and promotes it to most-recently-used, or none if absent.

fn (mut c Lru[K, V]) get_or_compute(key K, f fn () V) V

get_or_compute returns the cached value, computing and storing it on a miss.

fn (mut c Lru[K, V]) put(key K, value V)

put stores value, evicting least-recently-used entries while over capacity.

fn (mut c Lru[K, V]) delete(key K) bool

delete removes key, returning false if it was absent.

fn (c &Lru[K, V]) len() int

len returns the number of cached entries.

fn (c &Lru[K, V]) contains(key K) bool

contains reports whether key is cached, without affecting recency.

fn (mut t Ttl[K, V]) set(key K, value V)

set stores value, (re)starting its ttl.

fn (mut t Ttl[K, V]) get(key K) ?V

get returns the value for key, or none if absent or expired (expired entries are removed on access).

fn (mut t Ttl[K, V]) delete(key K) bool

delete removes key, returning false if it was absent.

fn (mut t Ttl[K, V]) purge_expired() int

purge_expired removes all expired entries, returning how many were removed.

fn (t &Ttl[K, V]) len() int

len returns the number of stored entries, including not-yet-purged expired ones (use purge_expired for an exact live count).

struct Lru[K, V] {
mut:
	cap   int
	items map[K]V
	order []K // least-recently-used first; most-recently-used last
}

Lru[K, V] is a capacity-bounded least-recently-used cache: reads promote entries and inserts beyond capacity evict the stalest entry first. It is single-threaded; share it across threads behind a mutex or channel. It covers the functools.lru_cache / .NET MemoryCache use case.

struct Ttl[K, V] {
mut:
	items map[K]TtlEntry[V]
	ttl   time.Duration
	now   fn () i64
}

Ttl[K, V] is a time-to-live cache: entries disappear after ttl elapses. Expiry uses millisecond timestamps from now (a monotonic clock by default), so a fake clock can be injected for deterministic tests. Single-threaded.