cache

README

Cache

A simple and easy to use method for adding caching aspects to your Go code. Everything revolves around a cache Value, which is a goroutine-safe, generic container for any value type.

Features

• Cache whatever value you want in a type safe container, made possible by generics.
• Set time to live policies that make sense to you.
• Group multiple cached values together in a MultiCache.
• Cache the contents of a file and be notified of changes.
• Automate translations of file contents.

Check out the package docs for more information about how these functions work.

Documentation

Overview

Package cache provides a simple and easy to use method for adding caching aspects to your Go code. Everything revolves around a cache Value, which is a goroutine-safe, generic container for any value type.

File caching is provided with github.com/saylorsolutions/cache/file as an accompanying package. It's kept separate to prevent bloating your binary with a dependency you won't need if you don't import the package.

Creating a Value

A Value is created with a LoaderFunc (or a derivative) that determines how new values are loaded. These functions may return an error, so a call to Value.Get also returns an error.

Different behaviors can be assigned to a Value depending on how they're created.

New and NewEager

New creates a Value with the given LoaderFunc, and makes the Value lazily initialized. If eager initialization is needed, then NewEager is provided for that purpose.

These functions cannot be initialized with a nil LoaderFunc, and will panic if one is passed.

NewWithTTL

NewWithTTL is similar to New, and is useful for cases where the time to live is determined by the process loading the cached value. It accepts a LoaderTTLFunc that returns the time to live duration.

This function cannot be initialized with a nil LoaderTTLFunc, and will panic if one is passed.

Internals

A Value stores a pointer to your cached value type, so it can easily determine if it's set or not. A Value has other, optional attributes that may help it fit with your caching needs.

Time to Live

By default, a cached value will not expire unless a call to Value.Invalidate is received. However, to meet this need a Value may have a time to live duration set with Value.SetTTL. This allows a Value to automatically re-load itself when a call to Value.Get is received after the time to live duration has elapsed.

With a time to live duration set, a call to Value.Get will not refresh this time to live timer. That behavior may be enabled with Value.EnableGetTTLRefresh.

If you need to respond to a call to Value.Invalidate (but not timed expiration), then a handler function can be registered with Value.OnInvalidate.

If you no longer want a Value to have a time to live, then use Value.RemoveTTL.

Caching multiple values

You may have a need to store many of the same values. The MultiCache is provided for this use-case.

The MultiCache behaves similarly to the Value type, except that each underlying Value in a MultiCache is assigned a user-specified, comparable key. A MultiCache can contain more MultiCache's if a sort of hierarchy is desired.

To eagerly load values into a MultiCache, use MultiCache.Preheat with a set of keys.

Note that setting a TTL on a MultiCache sets that policy for all newly added Values.

Also, MultiCache doesn't provide a means of setting the underlying persistence where cached values are sourced. This is the role of the MultiLoaderFunc.

Index

• type LoaderFunc
• type LoaderTTLFunc
• type MultiCache
  • func NewMulti[K comparable, V any](loader MultiLoaderFunc[K, V]) *MultiCache[K, V]
  • func (m *MultiCache[K, V]) Get(key K) (V, error)
  • func (m *MultiCache[K, V]) Invalidate(key K)
  • func (m *MultiCache[K, V]) MustGet(key K) V
  • func (m *MultiCache[K, V]) OnInvalidate(key K, invalidateFunc OnInvalidateFunc)
  • func (m *MultiCache[K, V]) Preheat(keys []K) error
  • func (m *MultiCache[K, V]) SetTTLPolicy(ttl time.Duration)
• type MultiLoaderFunc
• type OnInvalidateFunc
• type Value
  • func New[T any](loader LoaderFunc[T]) *Value[T]
  • func NewEager[T any](loader LoaderFunc[T]) (*Value[T], error)
  • func NewWithTTL[T any](loader LoaderTTLFunc[T]) *Value[T]
  • func (c *Value[T]) EnableGetTTLRefresh()
  • func (c *Value[T]) Get() (T, error)
  • func (c *Value[T]) Invalidate()
  • func (c *Value[T]) MustGet() T
  • func (c *Value[T]) OnInvalidate(fn OnInvalidateFunc)
  • func (c *Value[T]) RemoveTTL()
  • func (c *Value[T]) SetTTL(ttl time.Duration)

Types

type LoaderFunc

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

LoaderFunc is a function that loads data of type T.

type LoaderTTLFunc

type LoaderTTLFunc[T any] func() (T, time.Duration, error)

LoaderTTLFunc is a function that returns both a value and the time that the value should be valid. If a LoaderTTLFunc returns a time to live <= 0, then an error will be returned from Value.Get indicating this.

type MultiCache

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

MultiCache provides the ability to cache multiple values of type V by some comparable key K. An example use-case would be caching database entities by primary key.

func NewMulti

func NewMulti[K comparable, V any](loader MultiLoaderFunc[K, V]) *MultiCache[K, V]

NewMulti will create a new MultiCache with the given loader. A MultiCache may be composed of other MultiCache in the case where logical grouping of cached values is needed. If the loader is nil, then this function will panic.

func (*MultiCache[K, V]) Get

func (m *MultiCache[K, V]) Get(key K) (V, error)

Get will return the value in the cache.Value associated with key K. Any errors returned from cache.Value.Get will be returned from Get.

func (*MultiCache[K, V]) Invalidate

func (m *MultiCache[K, V]) Invalidate(key K)

Invalidate will invalidate the cache.Value related to key K, if it exists.

func (*MultiCache[K, V]) MustGet

func (m *MultiCache[K, V]) MustGet(key K) V

MustGet does the same thing as Get, but it will panic if an error occurs.

func (*MultiCache[K, V]) OnInvalidate

func (m *MultiCache[K, V]) OnInvalidate(key K, invalidateFunc OnInvalidateFunc)

OnInvalidate sets an OnInvalidateFunc on the Value referenced by key. If no Value is associated to the given key, then no action is taken.

func (*MultiCache[K, V]) Preheat

func (m *MultiCache[K, V]) Preheat(keys []K) error

Preheat will load the values associated with each key in keys. This will return the first error encountered and stop processing further keys.

func (*MultiCache[K, V]) SetTTLPolicy

func (m *MultiCache[K, V]) SetTTLPolicy(ttl time.Duration)

SetTTLPolicy sets the time to live policy for all internal Value values after they are retrieved. By default, a MultiCache value will not invalidate itself. A TTL policy must be set prior to retrieval or preheating for any value to invalidate itself.

Note that this policy takes precedence over any individual Value's time to live value.

This method will panic if ttl <= 0.

type MultiLoaderFunc

type MultiLoaderFunc[K comparable, V any] func(key K) (V, error)

MultiLoaderFunc is a lot like LoaderFunc, except that it accepts an input key.

type OnInvalidateFunc

type OnInvalidateFunc = func()

OnInvalidateFunc is a function that will be called when Invalidate is called.

type Value

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

Value is a struct that contains a value of type T. If the value is nil, then its LoaderFunc will be called. By default, a cached Value will not invalidate itself. A time to live must be set to enable this behavior.

See SetTTL for more details.

func New

func New[T any](loader LoaderFunc[T]) *Value[T]

New creates a new, lazily initialized Value with the given loader. If the loader is nil, then this function will panic.

func NewEager

func NewEager[T any](loader LoaderFunc[T]) (*Value[T], error)

NewEager will create an eagerly initialized Value with the given loader. If the loader is nil, then this function will panic.

func NewWithTTL

func NewWithTTL[T any](loader LoaderTTLFunc[T]) *Value[T]

NewWithTTL will create a Value where the loader determines its value's time to live. This is useful for cases similar to when the Value holds an authentication token or some other time-valid value, and its time to live is only known upon retrieval.

func (*Value[T]) EnableGetTTLRefresh

func (c *Value[T]) EnableGetTTLRefresh()

EnableGetTTLRefresh will change the Get behavior to refresh validity of a cached Value when it's called. This is useful for situations where loading should be avoided, and the Value is expected to still be valid after its initial time to live has expired.

This function has no effect if there isn't a time to live set.

func (*Value[T]) Get

func (c *Value[T]) Get() (T, error)

Get will return the cached value, if it exists, or call the LoaderFunc otherwise. Any error returned while loading the cache will be returned.

func (*Value[T]) Invalidate

func (c *Value[T]) Invalidate()

Invalidate will remove the cached value and force a reload the next time Get is called.

func (*Value[T]) MustGet

func (c *Value[T]) MustGet() T

MustGet does the same thing as Get, but it will panic if an error occurs.

func (*Value[T]) OnInvalidate

func (c *Value[T]) OnInvalidate(fn OnInvalidateFunc)

OnInvalidate allows reacting to Invalidate being called on a Value. This can be useful in cases where a change in a Value's validity is considered an event where some component of an application needs to be reinitialized. This pairs well with a context.CancelFunc.

Note that the given function is only called when Invalidate is called, not when a Value's expiration has been reached.

func (*Value[T]) RemoveTTL

func (c *Value[T]) RemoveTTL()

RemoveTTL will remove the time to live constraint on this cached Value. This will not invalidate the cache, but Invalidate can be used for that purpose.

func (*Value[T]) SetTTL

func (c *Value[T]) SetTTL(ttl time.Duration)

SetTTL sets the duration that a cached value will be considered valid. This is useful for cases where the cached value is expected to change frequently enough that it's only expected to be valid for a short time. This works with NewEager because it sets a static time.Time when the value will be considered invalid.

This method will not allow a call to Get to refresh the expiration time. If that's not desired, then use EnableGetTTLRefresh.

If a time to live is no longer needed, then use RemoveTTL. This function will panic if ttl is <= 0.