lru

Documentation

Overview

Package lru provides a generic in-memory LRU cache with optional TTL (expiration). It uses hashicorp/golang-lru/v2 as the underlying LRU implementation and adds per-entry expiration on top.

The Cache[K, V] type is generic over key and value types. It implements cache.Cache[K, V].

Basic usage:

c, _ := lru.New[string, string](1024, lru.WithDefaultTTL(10*time.Second))
c.Set(context.Background(), "foo", "bar", 0)
val, _ := c.Get(context.Background(), "foo")

Index

• type Cache
  • func New[K comparable, V any](capacity int, opts ...Option) (*Cache[K, V], error)
  • func (c *Cache[K, V]) Clear(ctx context.Context) error
  • func (c *Cache[K, V]) Close() error
  • func (c *Cache[K, V]) Contains(key K) bool
  • func (c *Cache[K, V]) Delete(ctx context.Context, key K) error
  • func (c *Cache[K, V]) Exists(ctx context.Context, key K) (bool, error)
  • func (c *Cache[K, V]) Get(ctx context.Context, key K) (V, error)
  • func (c *Cache[K, V]) Len() int
  • func (c *Cache[K, V]) Set(ctx context.Context, key K, value V, ttl time.Duration) error
• type Option
  • func WithCleanupInterval(d time.Duration) Option
  • func WithDefaultTTL(ttl time.Duration) Option
  • func WithPrefix(prefix string) Option

Types

type Cache

type Cache[K comparable, V any] struct {
	// contains filtered or unexported fields
}

Cache is a generic in-memory LRU cache with optional per-entry TTL. It implements cache.Cache[K, V].

func New

func New[K comparable, V any](capacity int, opts ...Option) (*Cache[K, V], error)

New creates an LRU cache with the given capacity (number of entries) and options. capacity must be greater than zero.

WithDefaultTTL sets a TTL applied to entries when Set is called with ttl == 0. A zero default TTL means entries never expire unless a positive ttl is passed to Set.

WithCleanupInterval enables a background goroutine that periodically purges expired entries. Pass 0 to disable (expired entries are still removed on access).

func (*Cache[K, V]) Clear

func (c *Cache[K, V]) Clear(ctx context.Context) error

Clear removes all entries.

func (*Cache[K, V]) Close

func (c *Cache[K, V]) Close() error

Close releases resources. The cache is no longer usable after Close.

func (*Cache[K, V]) Contains

func (c *Cache[K, V]) Contains(key K) bool

Contains reports whether key exists without checking expiration.

func (*Cache[K, V]) Delete

func (c *Cache[K, V]) Delete(ctx context.Context, key K) error

Delete removes key. It is not an error if the key does not exist.

func (*Cache[K, V]) Exists

func (c *Cache[K, V]) Exists(ctx context.Context, key K) (bool, error)

Exists reports whether key is present and not expired.

func (*Cache[K, V]) Get

func (c *Cache[K, V]) Get(ctx context.Context, key K) (V, error)

Get returns the value for key, or cache.ErrNotFound if missing or expired.

func (*Cache[K, V]) Len

func (c *Cache[K, V]) Len() int

Len returns the number of entries currently stored (including expired ones that have not yet been purged).

func (*Cache[K, V]) Set

func (c *Cache[K, V]) Set(ctx context.Context, key K, value V, ttl time.Duration) error

Set stores value under key. ttl > 0 sets a per-entry TTL; ttl == 0 uses the default TTL (which may mean no expiration).

type Option

type Option func(*config)

Option configures an LRU cache.

func WithCleanupInterval

func WithCleanupInterval(d time.Duration) Option

WithCleanupInterval sets how often expired entries are purged. Pass 0 to disable background cleanup (expired entries are still removed on access).

func WithDefaultTTL

func WithDefaultTTL(ttl time.Duration) Option

WithDefaultTTL sets the default TTL used when Set is called with ttl == 0.

func WithPrefix

func WithPrefix(prefix string) Option

WithPrefix sets a key prefix.