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