cache

Documentation

Overview

Package cache implements an in-memory cache for arbitrary objects.

This package was originally adapted from https://github.com/google/exposure-notifications-server, but it has evolved beyond that specific use case.

At the time of this writing, there is no standard, general-purpose TTL-based caching library for Go. There are multiple LRU-based caches, but those do not satisfy the requirements for a TTL-based cache. If a standard package were to emerge in the future, we should consider switching.

This package assumes the system time has minimal skew. In case of major clock skew or system clock reset, cache expirations could occur out of order.

Index

• type Cache
  • func New[T any](expireAfter time.Duration) *Cache[T]
  • func (c *Cache[T]) Clear()
  • func (c *Cache[T]) Lookup(name string) (T, bool)
  • func (c *Cache[T]) Set(name string, object T)
  • func (c *Cache[T]) Size() int
  • func (c *Cache[T]) Stop()
  • func (c *Cache[T]) WriteThruLookup(name string, fn Func[T]) (T, error)
• type Func

Types

type Cache

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

Cache represents a generic cacher. All items in the cache must be of the same type T, and all items in the cache share the same expiration duration (expiration is not configurable per-item).

For performance, it's strongly recommended that you store pointers to objects instead of actual objects.

func New

func New[T any](expireAfter time.Duration) *Cache[T]

New creates a new in memory cache. Panics if expireAfter is 0 or negative.

func (*Cache[T]) Clear

func (c *Cache[T]) Clear()

Clear removes all items from the cache, regardless of their expiration. Note this is different from Stop() which deletes all cached items and prevents new items from being added.

func (*Cache[T]) Lookup

func (c *Cache[T]) Lookup(name string) (T, bool)

Lookup checks the cache for a non-expired object by the supplied key name. The bool return informs the caller if there was a cache hit or not. A return of nil, true means that nil is in the cache. Where nil, false indicates a cache miss or that the value is expired and should be refreshed.

func (*Cache[T]) Set

func (c *Cache[T]) Set(name string, object T)

Set saves the current value of an object in the cache, with the supplied durintion until the object expires.

func (*Cache[T]) Size

func (c *Cache[T]) Size() int

Size returns the current number of items in the cache.

func (*Cache[T]) Stop

func (c *Cache[T]) Stop()

Stop clears the cache and prevents new entries from being added and retrieved.

func (*Cache[T]) WriteThruLookup

func (c *Cache[T]) WriteThruLookup(name string, fn Func[T]) (T, error)

WriteThruLookup checks the cache for the value associated with name, and if not found or expired, invokes the provided lookup function to resolve the value.

type Func

type Func[T any] func() (T, error)

Func is a generic-based function that returns T, or an error if creating T failed. This function is used as part of the WriteThruCache call.