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](sz int) Cache[K, V]
• type Comparable
• type Entry
• 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]) 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 func(K, V))
  • func (c *TTLCache[K, V]) SetInvalidateCallback(hook func(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 func(Key, Value))

	// SetInvalidateCallback sets the invalidate callback to the provided hook
	SetInvalidateCallback(hook func(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](sz int) Cache[K, V]

New returns a new initialized Cache.

type Comparable

type Comparable interface {
	Equal(any) bool
}

type Entry

type Entry[Value any] struct {
	Value  Value
	Expiry time.Time
}

Entry represents an item in the cache, with it's currently calculated Expiry time.

type TTLCache

type TTLCache[Key comparable, Value any] struct {
	// TTL is the cache item TTL.
	TTL time.Duration

	// Evict is the hook that is called when an item is
	// evicted from the cache, includes manual delete.
	Evict func(Key, Value)

	// Invalid is the hook that is called when an item's
	// data in the cache is invalidated.
	Invalid func(Key, Value)

	// Cache is the underlying hashmap used for this cache.
	Cache map[Key](*Entry[Value])
	// 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]) 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 func(K, V))

func (*TTLCache[K, V]) SetInvalidateCallback

func (c *TTLCache[K, V]) SetInvalidateCallback(hook func(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.