package cache

import "tailscale.com/util/cache"

Package cache contains an interface for a cache around a typed value, and various cache implementations that implement that interface.

Index ¶

• type Cache
• type FillFunc
• type Locking
• func NewLocking[K comparable, V any, C Cache[K, V]](inner C) *Locking[K, V, C]
• func (c *Locking[K, V, C]) Empty()
• func (c *Locking[K, V, C]) Forget(key K)
• func (c *Locking[K, V, C]) Get(key K, f FillFunc[V]) (V, error)
• type None
• func (None[K, V]) Empty()
• func (None[K, V]) Forget(K)
• func (c None[K, V]) Get(_ K, f FillFunc[V]) (V, error)
• type Single
• func (c *Single[K, V]) Empty()
• func (c *Single[K, V]) Forget(key K)
• func (c *Single[K, V]) Get(key K, f FillFunc[V]) (V, error)

Types ¶

type Cache ¶

type Cache[K comparable, V any] interface {
	// Get should return a previously-cached value or call the provided
	// FillFunc to obtain a new one. The provided key can be used either to
	// allow multiple cached values, or to drop the cache if the key
	// changes; either is valid.
	Get(K, FillFunc[V]) (V, error)

	// Forget should remove the given key from the cache, if it is present.
	// If it is not present, nothing should be done.
	Forget(K)

	// Empty should empty the cache such that the next call to Get should
	// call the provided FillFunc for all possible keys.
	Empty()
}

Cache is the interface for the cache types in this package.

Functions in this interface take a key parameter, but it is valid for a cache type to hold a single value associated with a key, and simply drop the cached value if provided with a different key.

It is valid for Cache implementations to be concurrency-safe or not, and each implementation should document this. If you need a concurrency-safe cache, an existing cache can be wrapped with a lock using NewLocking(inner).

K and V should be types that can be successfully passed to json.Marshal.

type FillFunc ¶

type FillFunc[T any] func() (T, time.Time, error)

FillFunc is the signature of a function for filling a cache. It should return the value to be cached, the time that the cached value is valid until, or an error.

type Locking ¶

type Locking[K comparable, V any, C Cache[K, V]] struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Locking wraps an inner Cache implementation with a mutex, making it safe for concurrent use. All methods are serialized on the same mutex.

func NewLocking ¶

func NewLocking[K comparable, V any, C Cache[K, V]](inner C) *Locking[K, V, C]

NewLocking creates a new Locking cache wrapping inner.

func (*Locking[K, V, C]) Empty ¶

func (c *Locking[K, V, C]) Empty()

Empty implements Cache.

func (*Locking[K, V, C]) Forget ¶

func (c *Locking[K, V, C]) Forget(key K)

Forget implements Cache.

func (*Locking[K, V, C]) Get ¶

func (c *Locking[K, V, C]) Get(key K, f FillFunc[V]) (V, error)

Get implements Cache.

The cache's mutex is held for the entire duration of this function, including while the FillFunc is being called. This function is not reentrant; attempting to call Get from a FillFunc will deadlock.

type None ¶

type None[K comparable, V any] struct{}

None provides no caching and always calls the provided FillFunc.

It is safe for concurrent use if the underlying FillFunc is.

func (None[K, V]) Empty ¶

func (None[K, V]) Empty()

Empty implements Cache.

func (None[K, V]) Forget ¶

func (None[K, V]) Forget(K)

Forget implements Cache.

func (None[K, V]) Get ¶

func (c None[K, V]) Get(_ K, f FillFunc[V]) (V, error)

Get always calls the provided FillFunc and returns what it does.

type Single ¶

type Single[K comparable, V any] struct {

	// ServeExpired indicates that if an error occurs when filling the
	// cache, an expired value can be returned instead of an error.
	//
	// This value should only be set when this struct is created.
	ServeExpired bool
	// contains filtered or unexported fields
}

Single is a simple in-memory cache that stores a single value until a defined time before it is re-fetched. It also supports returning a previously-expired value if refreshing the value in the cache fails.

Single is not safe for concurrent use.

func (*Single[K, V]) Empty ¶

func (c *Single[K, V]) Empty()

Empty implements Cache.

func (*Single[K, V]) Forget ¶

func (c *Single[K, V]) Forget(key K)

Forget implements Cache.

func (*Single[K, V]) Get ¶

func (c *Single[K, V]) Get(key K, f FillFunc[V]) (V, error)

Get will return the cached value, if any, or fill the cache by calling f and return the corresponding value. If f returns an error and c.ServeExpired is true, then a previous expired value can be returned with no error.

Source Files ¶

interface.go locking.go none.go single.go