cache

README

go-cache

A TTL cache designed to be used as a base for your own customizations, or used straight out of the box

Documentation

Index

• func Compare(i1, i2 any) bool
• type Cache
  • func New[K comparable, V any]() Cache[K, V]
• type Comparable
• type Hook
• type LookupCache
  • func NewLookup[OK, AK comparable, V any](cfg LookupCfg[OK, AK, V]) LookupCache[OK, AK, V]
• type LookupCfg
• type LookupMap
  • func (l *LookupMap[OK, AK]) Delete(id string, key AK)
  • func (l *LookupMap[OK, AK]) Get(id string, key AK) (OK, bool)
  • func (l *LookupMap[OK, AK]) Has(id string, key AK) bool
  • func (l *LookupMap[OK, AK]) RegisterLookup(id string)
  • func (l *LookupMap[OK, AK]) Set(id string, key AK, origKey OK)
• type TTLCache
  • func (c *TTLCache[K, V]) CAS(key K, cmp V, swp V) bool
  • func (c *TTLCache[K, V]) CASUnsafe(key K, cmp V, swp V) bool
  • func (c *TTLCache[K, V]) Clear()
  • func (c *TTLCache[K, V]) ClearUnsafe()
  • func (c *TTLCache[K, V]) Get(key K) (V, bool)
  • func (c *TTLCache[K, V]) GetUnsafe(key K) (V, bool)
  • func (c *TTLCache[K, V]) Has(key K) bool
  • func (c *TTLCache[K, V]) HasUnsafe(key K) bool
  • func (c *TTLCache[K, V]) Init()
  • func (c *TTLCache[K, V]) Invalidate(key K) bool
  • func (c *TTLCache[K, V]) InvalidateUnsafe(key K) bool
  • func (c *TTLCache[K, V]) Lock()
  • func (c *TTLCache[K, V]) Put(key K, value V) bool
  • func (c *TTLCache[K, V]) PutUnsafe(key K, value V) bool
  • func (c *TTLCache[K, V]) Set(key K, value V)
  • func (c *TTLCache[K, V]) SetEvictionCallback(hook Hook[K, V])
  • func (c *TTLCache[K, V]) SetInvalidateCallback(hook Hook[K, V])
  • func (c *TTLCache[K, V]) SetTTL(ttl time.Duration, update bool)
  • func (c *TTLCache[K, V]) SetUnsafe(key K, value V)
  • func (c *TTLCache[K, V]) Size() int
  • func (c *TTLCache[K, V]) SizeUnsafe() int
  • func (c *TTLCache[K, V]) Start(freq time.Duration) (ok bool)
  • func (c *TTLCache[K, V]) Stop() (ok bool)
  • func (c *TTLCache[K, V]) Swap(key K, swp V) V
  • func (c *TTLCache[K, V]) SwapUnsafe(key K, swp V) V
  • func (c *TTLCache[K, V]) Unlock()

Functions

func Compare

func Compare(i1, i2 any) bool

Compare returns whether 2 values are equal using the Comparable interface, or failing that falls back to use reflect.DeepEqual().

Types

type Cache

type Cache[Key comparable, Value any] interface {
	// Start will start the cache background eviction routine with given sweep frequency.
	// If already running or a freq <= 0 provided, this is a no-op. This will block until
	// the eviction routine has started
	Start(freq time.Duration) bool

	// Stop will stop cache background eviction routine. If not running this is a no-op. This
	// will block until the eviction routine has stopped
	Stop() bool

	// SetEvictionCallback sets the eviction callback to the provided hook
	SetEvictionCallback(hook Hook[Key, Value])

	// SetInvalidateCallback sets the invalidate callback to the provided hook
	SetInvalidateCallback(hook Hook[Key, Value])

	// SetTTL sets the cache item TTL. Update can be specified to force updates of existing items in
	// the cache, this will simply add the change in TTL to their current expiry time
	SetTTL(ttl time.Duration, update bool)

	// Get fetches the value with key from the cache, extending its TTL
	Get(key Key) (value Value, ok bool)

	// Put attempts to place the value at key in the cache, doing nothing if
	// a value with this key already exists. Returned bool is success state
	Put(key Key, value Value) bool

	// Set places the value at key in the cache. This will overwrite any
	// existing value, and call the update callback so. Existing values
	// will have their TTL extended upon update
	Set(key Key, value Value)

	// CAS will attempt to perform a CAS operation on 'key', using provided
	// comparison and swap values. Returned bool is success.
	CAS(key Key, cmp, swp Value) bool

	// Swap will attempt to perform a swap on 'key', replacing the value there
	// and returning the existing value. If no value exists for key, this will
	// set the value and return the zero value for V.
	Swap(key Key, swp Value) Value

	// Has checks the cache for a value with key, this will not update TTL
	Has(key Key) bool

	// Invalidate deletes a value from the cache, calling the invalidate callback
	Invalidate(key Key) bool

	// Clear empties the cache, calling the invalidate callback
	Clear()

	// Size returns the current size of the cache
	Size() int
}

Cache represents a TTL cache with customizable callbacks, it exists here to abstract away the "unsafe" methods in the case that you do not want your own implementation atop TTLCache{}.

func New

func New[K comparable, V any]() Cache[K, V]

New returns a new initialized Cache.

type Comparable

type Comparable interface {
	Equal(any) bool
}

type Hook

type Hook[Key comparable, Value any] func(key Key, value Value)

Hook defines a function hook that can be supplied as a callback.

type LookupCache

type LookupCache[OGKey, AltKey comparable, Value any] interface {
	Cache[OGKey, Value]

	// GetBy fetches a cached value by supplied lookup identifier and key
	GetBy(lookup string, key AltKey) (value Value, ok bool)

	// CASBy will attempt to perform a CAS operation on supplied lookup identifier and key
	CASBy(lookup string, key AltKey, cmp, swp Value) bool

	// SwapBy will attempt to perform a swap operation on supplied lookup identifier and key
	SwapBy(lookup string, key AltKey, swp Value) Value

	// HasBy checks if a value is cached under supplied lookup identifier and key
	HasBy(lookup string, key AltKey) bool

	// InvalidateBy invalidates a value by supplied lookup identifier and key
	InvalidateBy(lookup string, key AltKey) bool
}

LookupCache is a cache built on-top of TTLCache, providing multi-key lookups for items in the cache by means of additional lookup maps. These maps simply store additional keys => original key, with hook-ins to automatically call user supplied functions on adding an item, or on updating/deleting an item to keep the LookupMap up-to-date.

func NewLookup

func NewLookup[OK, AK comparable, V any](cfg LookupCfg[OK, AK, V]) LookupCache[OK, AK, V]

NewLookup returns a new initialized LookupCache.

type LookupCfg

type LookupCfg[OGKey, AltKey comparable, Value any] struct {
	// RegisterLookups is called on init to register lookups
	// within LookupCache's internal LookupMap
	RegisterLookups func(*LookupMap[OGKey, AltKey])

	// AddLookups is called on each addition to the cache, to
	// set any required additional key lookups for supplied item
	AddLookups func(*LookupMap[OGKey, AltKey], Value)

	// DeleteLookups is called on each eviction/invalidation of
	// an item in the cache, to remove any unused key lookups
	DeleteLookups func(*LookupMap[OGKey, AltKey], Value)
}

LookupCfg is the LookupCache configuration.

type LookupMap

type LookupMap[OK comparable, AK comparable] struct {
	// contains filtered or unexported fields
}

LookupMap is a structure that provides lookups for keys to primary keys under supplied lookup identifiers. This is essentially a wrapper around map[string](map[K1]K2).

func (*LookupMap[OK, AK]) Delete

func (l *LookupMap[OK, AK]) Delete(id string, key AK)

Delete removes a lookup from LookupMap with supplied identifier and key.

func (*LookupMap[OK, AK]) Get

func (l *LookupMap[OK, AK]) Get(id string, key AK) (OK, bool)

Get fetches an entry's primary key for lookup identifier and key.

func (*LookupMap[OK, AK]) Has

func (l *LookupMap[OK, AK]) Has(id string, key AK) bool

Has checks if there exists a lookup for supplied identifier and key.

func (*LookupMap[OK, AK]) RegisterLookup

func (l *LookupMap[OK, AK]) RegisterLookup(id string)

RegisterLookup registers a lookup identifier in the LookupMap, note this can only be doing during the cfg.RegisterLookups() hook.

func (*LookupMap[OK, AK]) Set

func (l *LookupMap[OK, AK]) Set(id string, key AK, origKey OK)

Set adds a lookup to the LookupMap under supplied lookup identifier, linking supplied key to the supplied primary (original) key.

type TTLCache

type TTLCache[Key comparable, Value any] struct {
	// contains filtered or unexported fields
}

TTLCache is the underlying Cache implementation, providing both the base Cache interface and access to "unsafe" methods so that you may build your customized caches ontop of this structure.

func (*TTLCache[K, V]) CAS

func (c *TTLCache[K, V]) CAS(key K, cmp V, swp V) bool

func (*TTLCache[K, V]) CASUnsafe

func (c *TTLCache[K, V]) CASUnsafe(key K, cmp V, swp V) bool

CASUnsafe is the mutex-unprotected logic for Cache.CAS().

func (*TTLCache[K, V]) Clear

func (c *TTLCache[K, V]) Clear()

func (*TTLCache[K, V]) ClearUnsafe

func (c *TTLCache[K, V]) ClearUnsafe()

ClearUnsafe is mutex-unprotected logic for Cache.Clean().

func (*TTLCache[K, V]) Get

func (c *TTLCache[K, V]) Get(key K) (V, bool)

func (*TTLCache[K, V]) GetUnsafe

func (c *TTLCache[K, V]) GetUnsafe(key K) (V, bool)

GetUnsafe is the mutex-unprotected logic for Cache.Get().

func (*TTLCache[K, V]) Has

func (c *TTLCache[K, V]) Has(key K) bool

func (*TTLCache[K, V]) HasUnsafe

func (c *TTLCache[K, V]) HasUnsafe(key K) bool

HasUnsafe is the mutex-unprotected logic for Cache.Has().

func (*TTLCache[K, V]) Init

func (c *TTLCache[K, V]) Init()

Init performs Cache initialization. MUST be called.

func (*TTLCache[K, V]) Invalidate

func (c *TTLCache[K, V]) Invalidate(key K) bool

func (*TTLCache[K, V]) InvalidateUnsafe

func (c *TTLCache[K, V]) InvalidateUnsafe(key K) bool

InvalidateUnsafe is mutex-unprotected logic for Cache.Invalidate().

func (*TTLCache[K, V]) Lock

func (c *TTLCache[K, V]) Lock()

Lock locks the cache mutex.

func (*TTLCache[K, V]) Put

func (c *TTLCache[K, V]) Put(key K, value V) bool

func (*TTLCache[K, V]) PutUnsafe

func (c *TTLCache[K, V]) PutUnsafe(key K, value V) bool

PutUnsafe is the mutex-unprotected logic for Cache.Put().

func (*TTLCache[K, V]) Set

func (c *TTLCache[K, V]) Set(key K, value V)

func (*TTLCache[K, V]) SetEvictionCallback

func (c *TTLCache[K, V]) SetEvictionCallback(hook Hook[K, V])

func (*TTLCache[K, V]) SetInvalidateCallback

func (c *TTLCache[K, V]) SetInvalidateCallback(hook Hook[K, V])

func (*TTLCache[K, V]) SetTTL

func (c *TTLCache[K, V]) SetTTL(ttl time.Duration, update bool)

func (*TTLCache[K, V]) SetUnsafe

func (c *TTLCache[K, V]) SetUnsafe(key K, value V)

SetUnsafe is the mutex-unprotected logic for Cache.Set(), it calls externally-set functions.

func (*TTLCache[K, V]) Size

func (c *TTLCache[K, V]) Size() int

func (*TTLCache[K, V]) SizeUnsafe

func (c *TTLCache[K, V]) SizeUnsafe() int

SizeUnsafe is mutex unprotected logic for Cache.Size().

func (*TTLCache[K, V]) Start

func (c *TTLCache[K, V]) Start(freq time.Duration) (ok bool)

func (*TTLCache[K, V]) Stop

func (c *TTLCache[K, V]) Stop() (ok bool)

func (*TTLCache[K, V]) Swap

func (c *TTLCache[K, V]) Swap(key K, swp V) V

func (*TTLCache[K, V]) SwapUnsafe

func (c *TTLCache[K, V]) SwapUnsafe(key K, swp V) V

SwapUnsafe is the mutex-unprotected logic for Cache.Swap().

func (*TTLCache[K, V]) Unlock

func (c *TTLCache[K, V]) Unlock()

Unlock unlocks the cache mutex.