const (
// NoTTL indicates that an item should never expire.
NoTTL time.Duration = -1
// PreviousOrDefaultTTL indicates that existing TTL of item should be used
// default TTL will be used as fallback if item doesn't exist
PreviousOrDefaultTTL time.Duration = -2
// DefaultTTL indicates that the default TTL value of the cache
// instance should be used.
DefaultTTL time.Duration = 0
)
Cache is a synchronised map of items that are automatically removed when they expire or the capacity is reached.
type Cache[K comparable, V any] struct { // contains filtered or unexported fields }
func New[K comparable, V any](opts ...Option[K, V]) *Cache[K, V]
New creates a new instance of cache.
func (c *Cache[K, V]) Delete(key K)
Delete deletes an item from the cache. If the item associated with the key is not found, the method is no-op.
func (c *Cache[K, V]) DeleteAll()
DeleteAll deletes all items from the cache.
func (c *Cache[K, V]) DeleteExpired()
DeleteExpired deletes all expired items from the cache.
func (c *Cache[K, V]) Get(key K, opts ...Option[K, V]) *Item[K, V]
Get retrieves an item from the cache by the provided key. Unless this is disabled, it also extends/touches an item's expiration timestamp on successful retrieval. If the item is not found, a nil value is returned.
func (c *Cache[K, V]) GetAndDelete(key K, opts ...Option[K, V]) (*Item[K, V], bool)
GetAndDelete retrieves an item from the cache by the provided key and then deletes it. The bool return value is true if the item was found before its deletion, false if not. If the loader is non-nil (i.e., used as an option or specified when creating the cache instance), it is executed normaly, i.e., only when the item is not found.
func (c *Cache[K, V]) GetOrSet(key K, value V, opts ...Option[K, V]) (*Item[K, V], bool)
GetOrSet retrieves an item from the cache by the provided key. If the item is not found, it is created with the provided options and then returned. The bool return value is true if the item was found, false if created during the execution of the method. If the loader is non-nil (i.e., used as an option or specified when creating the cache instance), its execution is skipped.
func (c *Cache[K, V]) Has(key K) bool
Has checks whether the key exists in the cache.
func (c *Cache[K, V]) Items() map[K]*Item[K, V]
Items returns a copy of all items in the cache. It does not update any expiration timestamps.
func (c *Cache[K, V]) Keys() []K
Keys returns all keys currently present in the cache.
func (c *Cache[K, V]) Len() int
Len returns the total number of items in the cache.
func (c *Cache[K, V]) Metrics() Metrics
Metrics returns the metrics of the cache.
func (c *Cache[K, V]) OnEviction(fn func(context.Context, EvictionReason, *Item[K, V])) func()
OnEviction adds the provided function to be executed when an item is evicted/deleted from the cache. The function is executed on a separate goroutine and does not block the flow of the cache manager. The returned function may be called to delete the subscription function from the list of eviction subscribers. When the returned function is called, it blocks until all instances of the same subscription function return. A context is used to notify the subscription function when the returned/deletion function is called.
func (c *Cache[K, V]) OnInsertion(fn func(context.Context, *Item[K, V])) func()
OnInsertion adds the provided function to be executed when a new item is inserted into the cache. The function is executed on a separate goroutine and does not block the flow of the cache manager. The returned function may be called to delete the subscription function from the list of insertion subscribers. When the returned function is called, it blocks until all instances of the same subscription function return. A context is used to notify the subscription function when the returned/deletion function is called.
func (c *Cache[K, V]) Range(fn func(item *Item[K, V]) bool)
Range calls fn for each item present in the cache. If fn returns false, Range stops the iteration.
func (c *Cache[K, V]) Set(key K, value V, ttl time.Duration) *Item[K, V]
Set creates a new item from the provided key and value, adds it to the cache and then returns it. If an item associated with the provided key already exists, the new item overwrites the existing one. NoTTL constant or -1 can be used to indicate that the item should never expire. DefaultTTL constant or 0 can be used to indicate that the item should use the default/global TTL that was specified when the cache instance was created.
func (c *Cache[K, V]) Start()
Start starts an automatic cleanup process that periodically deletes expired items. It blocks until Stop is called.
func (c *Cache[K, V]) Stop()
Stop stops the automatic cleanup process. It blocks until the cleanup process exits.
func (c *Cache[K, V]) Touch(key K)
Touch simulates an item's retrieval without actually returning it. Its main purpose is to extend an item's expiration timestamp. If the item is not found, the method is no-op.
EvictionReason is used to specify why a certain item was evicted/deleted.
type EvictionReason int
Available eviction reasons.
const (
EvictionReasonDeleted EvictionReason = iota + 1
EvictionReasonCapacityReached
EvictionReasonExpired
)
Item holds all the information that is associated with a single cache value.
type Item[K comparable, V any] struct { // contains filtered or unexported fields }
func (item *Item[K, V]) ExpiresAt() time.Time
ExpiresAt returns the expiration timestamp of the item.
func (item *Item[K, V]) IsExpired() bool
IsExpired returns a bool value that indicates whether the item is expired.
func (item *Item[K, V]) Key() K
Key returns the key of the item.
func (item *Item[K, V]) TTL() time.Duration
TTL returns the TTL value of the item.
func (item *Item[K, V]) Value() V
Value returns the value of the item.
func (item *Item[K, V]) Version() int64
Version returns the version of the item. It shows the total number of changes made to the item. If version tracking is disabled, the return value is always -1.
Loader is an interface that handles missing data loading.
type Loader[K comparable, V any] interface { // Load should execute a custom item retrieval logic and // return the item that is associated with the key. // It should return nil if the item is not found/valid. // The method is allowed to fetch data from the cache instance // or update it for future use. Load(c *Cache[K, V], key K) *Item[K, V] }
LoaderFunc type is an adapter that allows the use of ordinary functions as data loaders.
type LoaderFunc[K comparable, V any] func(*Cache[K, V], K) *Item[K, V]
func (l LoaderFunc[K, V]) Load(c *Cache[K, V], key K) *Item[K, V]
Load executes a custom item retrieval logic and returns the item that is associated with the key. It returns nil if the item is not found/valid.
Metrics contains common cache metrics calculated over the course of the cache's lifetime.
type Metrics struct {
// Insertions specifies how many items were inserted.
Insertions uint64
// Hits specifies how many items were successfully retrieved
// from the cache.
// Retrievals made with a loader function are not tracked.
Hits uint64
// Misses specifies how many items were not found in the cache.
// Retrievals made with a loader function are considered misses as
// well.
Misses uint64
// Evictions specifies how many items were removed from the
// cache.
Evictions uint64
}
Option sets a specific cache option.
type Option[K comparable, V any] interface { // contains filtered or unexported methods }
func WithCapacity[K comparable, V any](c uint64) Option[K, V]
WithCapacity sets the maximum capacity of the cache. It has no effect when used with Get().
func WithDisableTouchOnHit[K comparable, V any]() Option[K, V]
WithDisableTouchOnHit prevents the cache instance from extending/touching an item's expiration timestamp when it is being retrieved. When used with Get(), it overrides the default value of the cache.
func WithLoader[K comparable, V any](l Loader[K, V]) Option[K, V]
WithLoader sets the loader of the cache. When passing into Get(), it sets an ephemeral loader that is used instead of the cache's default one.
func WithTTL[K comparable, V any](ttl time.Duration) Option[K, V]
WithTTL sets the TTL of the cache. It has no effect when used with Get().
func WithVersion[K comparable, V any](enable bool) Option[K, V]
WithVersion activates item version tracking. If version tracking is disabled, the version is always -1. It has no effect when used with Get().
SuppressedLoader wraps another Loader and suppresses duplicate calls to its Load method.
type SuppressedLoader[K comparable, V any] struct { // contains filtered or unexported fields }
func NewSuppressedLoader[K comparable, V any](loader Loader[K, V], group *singleflight.Group) *SuppressedLoader[K, V]
NewSuppressedLoader creates a new instance of suppressed loader. If the group parameter is nil, a newly created instance of *singleflight.Group is used.
func (l *SuppressedLoader[K, V]) Load(c *Cache[K, V], key K) *Item[K, V]
Load executes a custom item retrieval logic and returns the item that is associated with the key. It returns nil if the item is not found/valid. It also ensures that only one execution of the wrapped Loader's Load method is in-flight for a given key at a time.