cache

Documentation

Overview

Package cache provides an in-memory LRU bounded by total byte size, item count, and entry age. Age eviction is passive: expired entries are removed on access (Get) and during bounded incremental sweeps on Put. No background goroutines are used.

This package is internal to cfsread and not intended for direct use outside the module.

Index

• type Config
• type EvictionReason
• type Key
• type LRU
  • func New(cfg Config) *LRU
  • func (c *LRU) Bytes() int64
  • func (c *LRU) Get(key Key) ([]byte, bool)
  • func (c *LRU) Invalidate(key Key)
  • func (c *LRU) InvalidatePrefix(fsName string)
  • func (c *LRU) Len() int
  • func (c *LRU) Put(key Key, value []byte)

Types

type Config

type Config struct {
	// MaxBytes is the maximum total decompressed bytes across all entries.
	// When exceeded, the least-recently-used entry is evicted.
	MaxBytes int64
	// MaxItems caps the number of cached entries.
	MaxItems int
	// MaxAge is the maximum idle duration before an entry becomes eligible
	// for eviction. Expired entries are reclaimed lazily during Get and Put.
	MaxAge time.Duration
	// Now returns the current time. nil defaults to time.Now. Override in
	// tests for deterministic time advancement with synctest.
	Now func() time.Time
	// OnEvict is called (under the LRU mutex) whenever an entry is removed
	// for any reason except overwrite. nil means no callback.
	OnEvict func(reason EvictionReason)
}

Config controls the behaviour of the LRU cache. Zero-value fields mean that dimension is unlimited.

type EvictionReason

type EvictionReason int

EvictionReason indicates why an entry was removed from the cache.

const (
	// EvictionSize indicates an entry was removed to stay under MaxBytes.
	EvictionSize EvictionReason = iota
	// EvictionCount indicates an entry was removed to stay under MaxItems.
	EvictionCount
	// EvictionIdle indicates an entry exceeded MaxAge.
	EvictionIdle
	// EvictionManual indicates an entry was explicitly invalidated.
	EvictionManual
)

type Key

type Key struct {
	FSName string
	Path   string
}

Key identifies a cached entry by filesystem name and path.

type LRU

type LRU struct {
	// contains filtered or unexported fields
}

LRU is an in-memory least-recently-used cache bounded by byte size, item count, and idle entry age.

func New

func New(cfg Config) *LRU

New creates a new LRU cache using the supplied configuration. The internal map is preallocated with capacity matching MaxItems (or 64 if unlimited).

func (*LRU) Bytes

func (c *LRU) Bytes() int64

Bytes returns the total byte size of all cached values.

func (*LRU) Get

func (c *LRU) Get(key Key) ([]byte, bool)

Get retrieves the value for key. Returns the cached byte slice and true on hit, or nil, false on miss. Zero allocation on cache hit — the returned slice is shared with the cache and must not be mutated. If the entry has exceeded MaxAge, it is evicted and a miss is returned.

func (*LRU) Invalidate

func (c *LRU) Invalidate(key Key)

Invalidate removes a single entry by key. Fires OnEvict(EvictionManual) if the entry exists. Does nothing if the key is not present.

func (*LRU) InvalidatePrefix

func (c *LRU) InvalidatePrefix(fsName string)

InvalidatePrefix removes all entries whose Key.FSName matches fsName. Fires OnEvict(EvictionManual) for each removed entry.

func (*LRU) Len

func (c *LRU) Len() int

Len returns the number of entries in the cache.

func (*LRU) Put

func (c *LRU) Put(key Key, value []byte)

Put inserts or replaces a value in the cache, then evicts as needed. If the key already exists, the old entry is silently replaced without triggering OnEvict. After insertion, the cache evicts in this order:

1. Lazy sweep of expired entries (if MaxAge is set)
2. Count-based eviction of the least-recently-used tail
3. Byte-size-based eviction of the least-recently-used tail