genericcache

Documentation

Index

• type Cache
  • func New[K Key, V any](capacity int, numShards int, initValueFn InitValueFn[K, V], ...) *Cache[K, V]
  • func (c *Cache[K, V]) Close()
  • func (c *Cache[K, V]) Evict(key K)
  • func (c *Cache[K, V]) EvictAll(predicate func(K) bool) []K
  • func (c *Cache[K, V]) FindOrCreate(ctx context.Context, key K) (ValueRef[K, V], error)
  • func (c *Cache[K, V]) Init(capacity int, numShards int, initValueFn InitValueFn[K, V], ...)
  • func (c *Cache[K, V]) Metrics() Metrics
• type InitValueFn
• type Key
• type Metrics
• type ReleaseValueFn
• type ValueRef
  • func (ref ValueRef[K, V]) Unref()
  • func (ref ValueRef[K, V]) Value() *V

Types

type Cache

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

Cache implements a generic cache that associates arbitrary keys with values. It uses multiple shards to reduce contention and uses the CLOCK-Pro algorithm.

Values are initialized on demand and are automatically released when they are evicted.

func New

func New[K Key, V any](
	capacity int, numShards int, initValueFn InitValueFn[K, V], releaseValueFn ReleaseValueFn[V],
) *Cache[K, V]

New creates a Cache with the given capacity and number of shards.

initValue is used to initialize a new value when it is added to the cache. releaseValueFn is used to close a V when it is no longer needed.

func (*Cache[K, V]) Close

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

Close the cache, releasing all live values. There must not be any outstanding references on any of the values.

func (*Cache[K, V]) Evict

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

Evict any entry associated with the given key. If there is a corresponding value in the cache, it is cleaned up before the function returns. There must not be any outstanding references on the value.

func (*Cache[K, V]) EvictAll

func (c *Cache[K, V]) EvictAll(predicate func(K) bool) []K

EvictAll evicts all entries in the cache with a key that satisfies the given predicate. Any corresponding values are released before the function returns. There must not be any outstanding references on the values, and no keys that satisfy the predicate should be inserted while the method is running.

It should be used sparingly as it is an O(n) operation. Returns the list of keys that were evicted (note that some may have been "ghost" entries without an associated value in the cache).

func (*Cache[K, V]) FindOrCreate

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

FindOrCreate retrieves an existing value or creates a new value for the given key. The result can be accessed via ValueRef.Value(). The caller must call ValueRef.Close() when it no longer needs the value.

func (*Cache[K, V]) Init

func (c *Cache[K, V]) Init(
	capacity int, numShards int, initValueFn InitValueFn[K, V], releaseValueFn ReleaseValueFn[V],
)

Init can be used instead of New when the cache is embedded in another struct.

func (*Cache[K, V]) Metrics

func (c *Cache[K, V]) Metrics() Metrics

Metrics retrieves metrics for the cache.

type InitValueFn

type InitValueFn[K Key, V any] func(context.Context, K, ValueRef[K, V]) error

InitValueFn is called to initialize a new value that is being added to the cache.

The function passes a ValueRef instead of *V only for special cases where we need to store the ValueRef in a closure (to Unref() it after a later FindOrCreate() call).

It is guaranteed that there will be no concurrent calls to InitValueFn() with the same key.

type Key

type Key interface {
	comparable

	// Shard maps the key to a shard index between 0 and numShards-1.
	Shard(numShards int) int
}

Key must be implemented by the key type used with a Cache.

type Metrics

type Metrics struct {
	// The number of bytes inuse by the cache. This includes the internal metadata
	// and storage for the V values present in the cache. Note that if V values
	// point to other objects, it is the caller's responsibility to account for
	// those as necessary.
	Size int64
	// The count of objects in the cache.
	Count int64
	// The number of cache hits.
	Hits int64
	// The number of cache misses.
	Misses int64
}

Metrics holds metrics for the cache.

type ReleaseValueFn

type ReleaseValueFn[V any] func(*V)

ReleaseValueFn is called to release a value that is no longer used (specifically: it was evicted from the cache AND there are no outstanding ValueRefs on it).

type ValueRef

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

ValueRef is returned by FindOrCreate. It holds a reference on a value; the value will be kept "alive" even if the cache decides to evict the value to make room for another one. The ValueRef is identical to the one passed to InitValueFn for this value.

func (ValueRef[K, V]) Unref

func (ref ValueRef[K, V]) Unref()

Unref releases the reference. This must be called or the underlying value will never be cleaned up.

func (ValueRef[K, V]) Value

func (ref ValueRef[K, V]) Value() *V

Value returns the value. This method and the returned value can only be used until ref.Close() is called.