lrucache

Documentation

Overview

Package lrucache provides a LRU cache implementation with an optional key expiration time.

Index

• type ExpiringLRU
  • func New(opts Options) *ExpiringLRU
• type ExpiringLRUOf
  • func NewOf[T any](opts Options) *ExpiringLRUOf[T]
  • func (e *ExpiringLRUOf[T]) Add(ctx context.Context, key string, value T) (replaced bool)
  • func (e *ExpiringLRUOf[T]) Delete(ctx context.Context, key string)
  • func (e *ExpiringLRUOf[T]) Get(ctx context.Context, key string, fn func() (T, error)) (value T, err error)
  • func (e *ExpiringLRUOf[T]) GetCached(ctx context.Context, key string) (value T, cached bool)
• type HandlePool
  • func NewHandlePool[K comparable, V any](capacity int, opener func(key K) V, closer func(key K, value V)) *HandlePool[K, V]
  • func (pool *HandlePool[K, V]) CloseAll()
  • func (pool *HandlePool[K, V]) Delete(key K) (value V, ok bool)
  • func (pool *HandlePool[K, V]) ForEach(fn func(key K, value V))
  • func (pool *HandlePool[K, V]) Get(key K) (value V, release func())
  • func (pool *HandlePool[K, V]) Peek(key K) (value V, release func(), ok bool)
• type Options

Types

type ExpiringLRU

type ExpiringLRU = ExpiringLRUOf[any]

ExpiringLRU is a backwards compatible implementation of ExpiringLRU.

func New

func New(opts Options) *ExpiringLRU

New constructs an ExpiringLRU with the given options.

type ExpiringLRUOf

type ExpiringLRUOf[T any] struct {
	// contains filtered or unexported fields
}

ExpiringLRUOf caches values for string keys with a time based expiration and an LRU based eviciton policy.

func NewOf

func NewOf[T any](opts Options) *ExpiringLRUOf[T]

NewOf constructs an ExpiringLRU with the given options.

func (*ExpiringLRUOf[T]) Add

func (e *ExpiringLRUOf[T]) Add(ctx context.Context, key string, value T) (replaced bool)

Add adds a value to the cache.

replaced is true if the key already existed in the cache and was valid, hence the value is replaced.

func (*ExpiringLRUOf[T]) Delete

func (e *ExpiringLRUOf[T]) Delete(ctx context.Context, key string)

Delete explicitly removes a key from the cache if it exists.

func (*ExpiringLRUOf[T]) Get

func (e *ExpiringLRUOf[T]) Get(ctx context.Context, key string, fn func() (T, error)) (value T, err error)

Get returns the value for some key if it exists and is valid. If not it will call the provided function. Concurrent calls will dedupe as best as they are able. If the function returns an error, it is not cached and further calls will try again.

func (*ExpiringLRUOf[T]) GetCached

func (e *ExpiringLRUOf[T]) GetCached(ctx context.Context, key string) (value T, cached bool)

GetCached returns the value associated with key and true if it exists and hasn't expired, otherwise nil and false.

type HandlePool

type HandlePool[K comparable, V any] struct {

	// Opener is called when a key is not in the cache and must be opened.
	// Neither the HandlePool lock nor the handleElement's lock is held while
	// Opener is called.
	//
	// Opener has no built-in facility for error handling; the caller must
	// store errors if necessary in V or in an external variable.
	Opener func(key K) V

	// Closer is called when a key is removed from the cache. The HandlePool
	// lock is not held when Closer is called, but the handleElement's lock
	// is held. Closer is responsible for cleaning up any resources associated
	// with V.
	//
	// Closer has no built-in facility for error handling; the caller must
	// handle or store errors on its own if necessary. The key and value will
	// be removed from the HandlePool regardless.
	Closer func(key K, value V)
	// contains filtered or unexported fields
}

HandlePool is an LRU cache of elements associated with opening and closing functions. For example, files which must be opened before use and must be closed when expiring from the cache.

Importantly, "open" operations are expected to be fairly slow, and are allowed to happen concurrently with other "open" operations and with ongoing use of the HandlePool.

func NewHandlePool

func NewHandlePool[K comparable, V any](capacity int, opener func(key K) V, closer func(key K, value V)) *HandlePool[K, V]

NewHandlePool creates a new HandlePool with the given capacity.

func (*HandlePool[K, V]) CloseAll

func (pool *HandlePool[K, V]) CloseAll()

CloseAll removes all handles from the pool, closing those that are no longer in use. Importantly, this does not necessarily close all handles, as they may still be in use by callers. Such handles will be closed when released.

func (*HandlePool[K, V]) Delete

func (pool *HandlePool[K, V]) Delete(key K) (value V, ok bool)

Delete removes a handle from the pool, closing it if not in use. If the handle is in use, it will be closed when released. If the handle is not in the pool, Delete has no effect.

The value associated with the key is returned if it was in the pool, along with ok=true. If ok=false, the key was not in the pool and value is the zero value.

func (*HandlePool[K, V]) ForEach

func (pool *HandlePool[K, V]) ForEach(fn func(key K, value V))

ForEach calls the given function for each key-value pair in a snapshot of the cache. If a handle is still being initialized, it will not be included. Each handle's lock is held in turn while fn is called.

func (*HandlePool[K, V]) Get

func (pool *HandlePool[K, V]) Get(key K) (value V, release func())

Get returns the value associated with the key, opening it if necessary. Get will block if Opener blocks, whether because this call is opening the value another call is opening the value and hasn't finished.

The caller must call the release function when done with the value.

If a new value is opened and this would exceed the capacity of the pool, the oldest value is removed before proceeding.

func (*HandlePool[K, V]) Peek

func (pool *HandlePool[K, V]) Peek(key K) (value V, release func(), ok bool)

Peek gets the value associated with the key if it is in the cache, without opening it. If the key is not in the cache, ok will be false and release will be nil.

If ok is true, the caller must call the release function when done with the value.

Note that if the key is currently being opened, Peek will return false, as though the value were not in the pool.

type Options

type Options struct {
	// Expiration is how long an entry will be valid. It is not
	// affected by LRU or anything: after this duration, the object
	// is invalidated. A non-positive value means no expiration.
	Expiration time.Duration

	// Capacity is how many objects to keep in memory.
	Capacity int

	// Name is used to differentiate cache in monkit stat.
	Name string
}

Options controls the details of the expiration policy.