cache

Documentation

Overview

Package cache provides a generic cache data structure with support for stale values during value refreshes.

Index

• type Cache
  • func New[K comparable, V any](opts ...Opt) *Cache[K, V]
  • func (c *Cache[K, V]) Clean()
  • func (c *Cache[K, V]) Delete(k K) (V, error, KeyState)
  • func (c *Cache[K, V]) Expire(k K)
  • func (c *Cache[K, V]) Get(k K, miss func() (V, error)) (v V, err error, s KeyState)
  • func (c *Cache[K, V]) Range(fn func(K, V, error) bool)
  • func (c *Cache[K, V]) Set(k K, v V)
  • func (c *Cache[K, V]) TryGet(k K) (V, error, KeyState)
• type KeyState
  • func (s KeyState) IsHit() bool
  • func (s KeyState) IsMiss() bool
• type Opt
  • func MaxAge(age time.Duration) Opt
  • func MaxErrorAge(age time.Duration) Opt
  • func MaxStaleAge(age time.Duration) Opt

Types

type Cache

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

Cache caches comparable keys to arbitrary values. By default the cache grows without bounds and all keys persist forever. These limits can be changed with options that are passed to New.

func New

func New[K comparable, V any](opts ...Opt) *Cache[K, V]

New returns a new cache, with the optional overrides configuring cache semantics. If you do not need to configure a cache at all, the zero value cache is valid and usable.

func (*Cache[K, V]) Clean

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

Clean deletes all expired values from the cache. A value is expired if MaxAge is used and the entry is older than the max age, or if you manually expired a key. If MaxStaleAge is used and not -1, the entry must be older than MaxAge + MaxStaleAge. If MaxStaleAge is -1, Clean returns immediately.

func (*Cache[K, V]) Delete

func (c *Cache[K, V]) Delete(k K) (V, error, KeyState)

Delete deletes the value for a key and returns the prior value, if loaded (i.e. the return from TryGet).

func (*Cache[K, V]) Expire

func (c *Cache[K, V]) Expire(k K)

Expire sets a loaded value to expire immediately, meaning the next Get will be a miss. If stale values are enabled, the next Get will trigger the miss function but still allow the now-stale value to be returned.

func (*Cache[K, V]) Get

func (c *Cache[K, V]) Get(k K, miss func() (V, error)) (v V, err error, s KeyState)

Get returns the cache value for k, running the miss function in a goroutine if the key is not yet cached. If stale values are enabled, the currently cached value has an error, and there is an unexpired stale value, this returns the stale value and no error.

func (*Cache[K, V]) Range

func (c *Cache[K, V]) Range(fn func(K, V, error) bool)

Each calls fn for every cached value. If fn returns false, iteration stops.

func (*Cache[K, V]) Set

func (c *Cache[K, V]) Set(k K, v V)

Set sets a value for a key. If the key is currently loading via Get, the load is canceled and Get returns the value from Set.

func (*Cache[K, V]) TryGet

func (c *Cache[K, V]) TryGet(k K) (V, error, KeyState)

TryGet returns the value for the given key if it is cached. This returns either the currently loaded value, or if the current load has an error, the stale value if present, or the currently stored error. If nothing is cached, or what is cached is expired, this returns false.

type KeyState

type KeyState uint8

KeyState is returned from cache operations to indicate how a key existed in the map, if at all.

const (
	// Miss indicates that the key was not present in the map.
	Miss KeyState = iota
	// Hit indicates that the key was present in the map and we are using
	// the latest values for the key.
	Hit
	// Stale indicates that the key was present in the map, but either was
	// expired or had an error, and we returned a valid stale value.
	Stale
)

func (KeyState) IsHit

func (s KeyState) IsHit() bool

IsHit returns whether the key state is Hit or Stale, meaning that the value is loaded.

func (KeyState) IsMiss

func (s KeyState) IsMiss() bool

IsMiss returns if the key state is Miss.

type Opt

type Opt interface {
	// contains filtered or unexported methods
}

Opt configures a cache.

func MaxAge

func MaxAge(age time.Duration) Opt

MaxAge sets the maximum age that values are cached for. By default, entries are cached forever. Using this option with 0 disables caching entirely, which allows this "cache" to be used as a way to collapse simultaneous queries for the same key.

Using this does *not* start a goroutine that periodically cleans the cache. Instead, the values will persist but are "dead" and cannot be queried. You can forcefully clean the cache with relevant Cache methods.

You can opt in to values expiring but still being queryable with the MaxStaleAge option.

func MaxErrorAge

func MaxErrorAge(age time.Duration) Opt

MaxErrorAge sets the age to persist load errors. If not specified, the default is MaxAge.

func MaxStaleAge

func MaxStaleAge(age time.Duration) Opt

MaxStaleAge opts in to stale values and sets how long they will persist after an entry has expired (so, total age is MaxAge + MaxStaleAge). A stale value is the previous successfully cached value that is returned while the value is being refreshed (a new value is being queried). As well, the stale value is returned while the refreshed value is erroring. This option is useless without MaxAge.

A special value of -1 allows stale values to be returned indefinitely.