Documentation
¶
Overview ¶
Package lru provides a generic thread-safe LRU cache with optional Bloom pre-filtering, size-based eviction, and cost-aware eviction sampling.
Index ¶
- type Cache
- func (c *Cache[K, V]) CacheHits() int64
- func (c *Cache[K, V]) CacheMisses() int64
- func (c *Cache[K, V]) Clear()
- func (c *Cache[K, V]) Get(key K) (V, bool)
- func (c *Cache[K, V]) GetMulti(keys []K) (found map[K]V, missing []K)
- func (c *Cache[K, V]) Len() int
- func (c *Cache[K, V]) Put(key K, value V)
- func (c *Cache[K, V]) PutMulti(items map[K]V)
- func (c *Cache[K, V]) PutMultiOwned(items map[K]V)
- func (c *Cache[K, V]) Stats() Stats
- type Option
- func WithBloomFilter[K comparable, V any](keyToBytes func(K) []byte, expectedN uint) Option[K, V]
- func WithCloneFunc[K comparable, V any](clone func(V) V) Option[K, V]
- func WithCostEviction[K comparable, V any](sampleSize int, costFunc func(accessCount, sizeBytes int64) float64) Option[K, V]
- func WithMaxBytes[K comparable, V any](maxBytes int64, sizeFunc func(V) int64) Option[K, V]
- func WithMaxEntries[K comparable, V any](n int) Option[K, V]
- type Stats
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 thread-safe generic LRU cache. It supports optional Bloom pre-filtering, size-based eviction, cost-aware eviction sampling, and value cloning on insertion.
func New ¶
func New[K comparable, V any](opts ...Option[K, V]) *Cache[K, V]
New creates a new LRU cache. At least one capacity limit (WithMaxEntries or WithMaxBytes) must be provided; otherwise New panics.
func (*Cache[K, V]) CacheMisses ¶
CacheMisses returns the total cache miss count (atomic, lock-free).
func (*Cache[K, V]) Clear ¶
func (c *Cache[K, V]) Clear()
Clear removes all entries and resets the Bloom filter.
func (*Cache[K, V]) Get ¶
Get retrieves a value from the cache. If a Bloom filter is configured, definite misses are short-circuited without lock acquisition.
func (*Cache[K, V]) GetMulti ¶
func (c *Cache[K, V]) GetMulti(keys []K) (found map[K]V, missing []K)
GetMulti retrieves multiple values from the cache. Returns a map of found key-value pairs and a slice of missing keys.
func (*Cache[K, V]) Put ¶
func (c *Cache[K, V]) Put(key K, value V)
Put adds or updates a key-value pair in the cache. If the value exceeds the maximum cache size, it is silently skipped.
func (*Cache[K, V]) PutMulti ¶
func (c *Cache[K, V]) PutMulti(items map[K]V)
PutMulti adds multiple key-value pairs to the cache. Uses a single lock acquisition for the entire batch.
func (*Cache[K, V]) PutMultiOwned ¶
func (c *Cache[K, V]) PutMultiOwned(items map[K]V)
PutMultiOwned adds multiple key-value pairs without cloning. The caller guarantees the values are exclusively owned and safe to store directly. This avoids the clone cost when values have already been detached from shared memory.
type Option ¶
type Option[K comparable, V any] func(*Cache[K, V])
Option configures a Cache.
func WithBloomFilter ¶
func WithBloomFilter[K comparable, V any](keyToBytes func(K) []byte, expectedN uint) Option[K, V]
WithBloomFilter enables a Bloom pre-filter for Get and GetMulti. keyToBytes converts a key to its byte representation. expectedN is the expected number of elements for Bloom filter sizing.
func WithCloneFunc ¶
func WithCloneFunc[K comparable, V any](clone func(V) V) Option[K, V]
WithCloneFunc sets a function to clone values before insertion. Useful to detach values from shared memory arenas.
func WithCostEviction ¶
func WithCostEviction[K comparable, V any](sampleSize int, costFunc func(accessCount, sizeBytes int64) float64) Option[K, V]
WithCostEviction enables sampling-based eviction with a cost function. Higher cost = less desirable to evict. sampleSize entries are sampled from the LRU tail; the one with lowest cost is evicted.
func WithMaxBytes ¶
func WithMaxBytes[K comparable, V any](maxBytes int64, sizeFunc func(V) int64) Option[K, V]
WithMaxBytes sets the maximum total size in bytes and a function to compute the size of each value. Enables size-based eviction.
func WithMaxEntries ¶
func WithMaxEntries[K comparable, V any](n int) Option[K, V]
WithMaxEntries sets the maximum number of entries (count-based eviction).
type Stats ¶
type Stats struct {
Hits int64
Misses int64
BloomFiltered int64 // Lookups short-circuited by the Bloom pre-filter.
Entries int
CurrentSize int64
MaxEntries int // 0 when count-based limit is not set.
MaxSize int64 // 0 when size-based limit is not set.
}
Stats holds cache performance metrics.
Source Files