l1

Documentation

Overview

Package l1 defines the Adapter interface for the in-process (L1) memory cache layer.

The core cache package stores and retrieves internal cache entries keyed by prefixed string keys through this interface. You can swap in bounded caches like Ristretto, Theine, or Otter by providing your own Adapter implementation.

The default adapter shipped with the library is the sync.Map-backed adapter in the adapters/l1/syncmap package.

Concurrency

All Adapter implementations must be safe for concurrent use from multiple goroutines.

Index

• type Adapter

Types

type Adapter

type Adapter interface {
	// Get retrieves the entry stored under key.
	// Returns (nil, false) on a cache miss — never an error.
	Get(key string) (any, bool)

	// Set stores value under key, unconditionally overwriting any
	// existing entry.
	//
	// cost is an advisory hint representing the entry's relative weight
	// (e.g., serialized byte size). Bounded caches use this to make
	// eviction decisions. Unbounded implementations (like [sync.Map]) may
	// ignore it. The value comes from [cache.EntryOptions.Size].
	Set(key string, value any, cost int64)

	// Delete removes the entry for key. Must not panic or return an
	// error if the key does not exist.
	Delete(key string)

	// LoadAndDelete atomically retrieves and removes the entry for key.
	// If the key was present, returns (value, true). Otherwise (nil, false).
	//
	// The cache uses this during the Expire operation to atomically
	// read the current entry before re-inserting a logically-expired copy.
	LoadAndDelete(key string) (any, bool)

	// Range calls fn sequentially for every entry in the cache.
	// If fn returns false, iteration stops.
	//
	// The iteration order is not guaranteed.
	// fn must not call other methods on the Adapter; doing so may deadlock.
	Range(fn func(key string, value any) bool)

	// CompareAndSwap atomically replaces the value for key only if the
	// current value is identical (==) to old. Returns true if the swap
	// was performed.
	//
	// This is used by Expire to update an entry in-place without racing
	// with a concurrent Set from another goroutine.
	CompareAndSwap(key string, old, new any) bool

	// Clear removes all entries from the cache.
	Clear()

	// Close releases any resources held by the adapter (background
	// goroutines, metric buffers, etc.). Implementations that have
	// nothing to clean up should return nil.
	//
	// Close is called by the cache's own Close method.
	Close() error
}

Adapter is the contract for the in-process (L1) memory cache.

The core cache stores and retrieves internal cache entries through this interface. The keys are prefixed strings generated by the cache; the values are opaque pointers that the adapter should store and return without modification.

Implementing a custom Adapter

At a minimum, implement [Adapter.Get], [Adapter.Set], [Adapter.Delete], and [Adapter.Clear]. The remaining methods enable optimisations the cache relies on:

• [Adapter.LoadAndDelete] is used during the Expire flow.
• [Adapter.CompareAndSwap] prevents a concurrent Set from being overwritten by an Expire that started earlier.
• [Adapter.Range] is used by Clear and tag-based invalidation.
• [Adapter.Close] is called when the cache is shut down.

All implementations must be safe for concurrent use.