Documentation
¶
Index ¶
- Constants
- type Cache
- func (c *Cache[K, V]) Delete(key K)
- func (c *Cache[K, V]) DeleteAll()
- func (c *Cache[K, V]) DeleteExpired()
- func (c *Cache[K, V]) Get(key K, opts ...Option[K, V]) *Item[K, V]
- func (c *Cache[K, V]) Items() map[K]*Item[K, V]
- func (c *Cache[K, V]) Keys() []K
- func (c *Cache[K, V]) Len() int
- func (c *Cache[K, V]) Metrics() Metrics
- func (c *Cache[K, V]) OnEviction(fn func(context.Context, EvictionReason, *Item[K, V])) func()
- func (c *Cache[K, V]) OnInsertion(fn func(context.Context, *Item[K, V])) func()
- func (c *Cache[K, V]) Set(key K, value V, ttl time.Duration) *Item[K, V]
- func (c *Cache[K, V]) Start()
- func (c *Cache[K, V]) Stop()
- func (c *Cache[K, V]) Touch(key K)
- type EvictionReason
- type Item
- type Loader
- type LoaderFunc
- type Metrics
- type Option
- type SuppressedLoader
- type Timer
Constants ¶
const ( // NoTTL indicates that an item should never expire. NoTTL time.Duration = -1 // DefaultTTL indicates that the default TTL // value should be used. DefaultTTL time.Duration = 0 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache[K comparable, V any] struct { // contains filtered or unexported fields }
Cache is a synchronised map of items that are automatically removed when they expire or the capacity is reached.
func New ¶
func New[K comparable, V any](opts ...Option[K, V]) *Cache[K, V]
New creates a new instance of cache.
func (*Cache[K, V]) Delete ¶
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 (*Cache[K, V]) DeleteAll ¶
func (c *Cache[K, V]) DeleteAll()
DeleteAll deletes all items from the cache.
func (*Cache[K, V]) DeleteExpired ¶
func (c *Cache[K, V]) DeleteExpired()
DeleteExpired deletes all expired items from the cache.
func (*Cache[K, V]) Get ¶
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 (*Cache[K, V]) Items ¶
Items returns a copy of all items in the cache. It does not update any expiration timestamps.
func (*Cache[K, V]) Keys ¶
func (c *Cache[K, V]) Keys() []K
Keys returns all keys currently present in the cache.
func (*Cache[K, V]) OnEviction ¶
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 (*Cache[K, V]) OnInsertion ¶
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 (*Cache[K, V]) Set ¶
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.
func (*Cache[K, V]) Start ¶
func (c *Cache[K, V]) Start()
Start starts an automatic cleanup process that periodically deletes expired items. It blocks until Stop is called.
type EvictionReason ¶
type EvictionReason int
EvictionReason is used to specify why a certain item was evicted/deleted.
const ( EvictionReasonDeleted EvictionReason = iota + 1 EvictionReasonCapacityReached EvictionReasonExpired )
Available eviction reasons.
type Item ¶
type Item[K comparable, V any] struct { // contains filtered or unexported fields }
Item holds all the information that is associated with a single cache value.
func (*Item[K, V]) IsExpired ¶
IsExpired returns a bool value that indicates whether the item is expired.
type Loader ¶
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] }
Loader is an interface that handles missing data loading.
type LoaderFunc ¶
type LoaderFunc[K comparable, V any] func(*Cache[K, V], K) *Item[K, V]
LoaderFunc type is an adapter that allows the use of ordinary functions as data loaders.
func (LoaderFunc[K, V]) Load ¶
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.
type Metrics ¶
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 tracked as well.
Misses uint64
// Evictions specifies how many items were removed from the
// cache.
Evictions uint64
}
Metrics contains common cache metrics calculated over the course of the cache's lifetime.
type Option ¶
type Option[K comparable, V any] interface { // contains filtered or unexported methods }
Option sets a specific cache option.
func WithCapacity ¶
func WithCapacity[K comparable, V any](c uint64) Option[K, V]
WithCapacity sets the maximum capacity of the cache. It has no effect when passing into Get().
func WithDisableTouchOnHit ¶
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 passing into Get(), it overrides the default value of the cache.
func WithLoader ¶
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 epheral loader that is used instead of the cache's default one.
type SuppressedLoader ¶
type SuppressedLoader[K comparable, V any] struct { Loader[K, V] // contains filtered or unexported fields }
SuppressedLoader wraps another Loader and suppresses duplicate calls to its Load method.
func (*SuppressedLoader[K, V]) Load ¶
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.
type Timer ¶
type Timer struct {
// contains filtered or unexported fields
}
Timer represents a single event. When the Timer expires, the given task will be executed.
func (*Timer) GetExpiration ¶
func (*Timer) Stop ¶
Stop prevents the Timer from firing. It returns true if the call stops the timer, false if the timer has already expired or been stopped.
If the timer t has already expired and the t.task has been started in its own goroutine; Stop does not wait for t.task to complete before returning. If the caller needs to know whether t.task is completed, it must coordinate with t.task explicitly.
Source Files