cache

package module
v2.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 28, 2022 License: MIT Imports: 5 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Cache

type Cache[Key, Value comparable] 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, V comparable]() Cache[K, V]

New returns a new initialized Cache.

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 Iface

type Iface struct {
	Type  unsafe.Pointer
	Value unsafe.Pointer
}

Iface represents the underlying fat pointer structure the runtime holds for an interface. This allows using an interface as a value type in a cache (which normally) doesn't implement the comparable interface.

func ToIface

func ToIface(i interface{}) *Iface

ToIface converts an interface to Iface representation.

func (*Iface) Interface

func (i *Iface) Interface() interface{}

Interface returns the interface this Iface represents.

func (*Iface) Nil

func (i *Iface) Nil() bool

Nil will return if this Iface represents a nil value.

type LookupCache

type LookupCache[OGKey, AltKey, Value comparable] 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, V comparable](cfg LookupCfg[OK, AK, V]) LookupCache[OK, AK, V]

NewLookup returns a new initialized LookupCache.

type LookupCfg

type LookupCfg[OGKey, AltKey, Value comparable] 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, Value comparable] 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, this 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) bool

func (*TTLCache[K, V]) Stop

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL