codeberg.org/gruf/go-cache/v3@v3.5.7/cache.go (about)

     1  package cache
     2  
     3  import (
     4  	"time"
     5  
     6  	"codeberg.org/gruf/go-cache/v3/simple"
     7  	"codeberg.org/gruf/go-cache/v3/ttl"
     8  )
     9  
    10  // TTLCache 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 ttl.Cache{}.
    11  type TTLCache[Key comparable, Value any] interface {
    12  	// 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.
    13  	Start(freq time.Duration) bool
    14  
    15  	// Stop will stop cache background eviction routine. If not running this is a no-op. This will block until the eviction routine has stopped.
    16  	Stop() bool
    17  
    18  	// 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.
    19  	SetTTL(ttl time.Duration, update bool)
    20  
    21  	// implements base cache.
    22  	Cache[Key, Value]
    23  }
    24  
    25  // Cache represents a 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 simple.Cache{}.
    26  type Cache[Key comparable, Value any] interface {
    27  	// SetEvictionCallback sets the eviction callback to the provided hook.
    28  	SetEvictionCallback(hook func(Key, Value))
    29  
    30  	// SetInvalidateCallback sets the invalidate callback to the provided hook.
    31  	SetInvalidateCallback(hook func(Key, Value))
    32  
    33  	// Get fetches the value with key from the cache, extending its TTL.
    34  	Get(key Key) (value Value, ok bool)
    35  
    36  	// Add 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. Calls invalidate callback on success.
    37  	Add(key Key, value Value) bool
    38  
    39  	// Set places the value at key in the cache. This will overwrite any existing value. Existing values will have their TTL extended upon update. Always calls invalidate callback.
    40  	Set(key Key, value Value)
    41  
    42  	// CAS will attempt to perform a CAS operation on 'key', using provided old and new values, and comparator function. Returned bool is success.
    43  	CAS(key Key, old, new Value, cmp func(Value, Value) bool) bool
    44  
    45  	// 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.
    46  	Swap(key Key, swp Value) Value
    47  
    48  	// Has checks the cache for a value with key, this will not update TTL.
    49  	Has(key Key) bool
    50  
    51  	// Invalidate deletes a value from the cache, calling the invalidate callback.
    52  	Invalidate(key Key) bool
    53  
    54  	// InvalidateAll is equivalent to multiple Invalidate calls.
    55  	InvalidateAll(keys ...Key) bool
    56  
    57  	// Clear empties the cache, calling the invalidate callback on each entry.
    58  	Clear()
    59  
    60  	// Len returns the current length of the cache.
    61  	Len() int
    62  
    63  	// Cap returns the maximum capacity of the cache.
    64  	Cap() int
    65  }
    66  
    67  // New returns a new initialized Cache with given initial length, maximum capacity.
    68  func New[K comparable, V any](len, cap int) Cache[K, V] {
    69  	return simple.New[K, V](len, cap)
    70  }
    71  
    72  // NewTTL returns a new initialized TTLCache with given initial length, maximum capacity and TTL duration.
    73  func NewTTL[K comparable, V any](len, cap int, _ttl time.Duration) TTLCache[K, V] {
    74  	return ttl.New[K, V](len, cap, _ttl)
    75  }