Documentation ¶
Overview ¶
Package imcache provides a generic in-memory cache. It supports absolute expiration, sliding expiration, max entries limit, eviction callbacks and sharding. It's safe for concurrent use by multiple goroutines.
The New function creates a new in-memory non-sharded cache instance.
The NewSharded function creates a new in-memory sharded cache instance.
Index ¶
- func Decrement[V Number](old V) Vdeprecated
- func Increment[V Number](old V) Vdeprecated
- type Cache
- func (c *Cache[K, V]) Close()
- func (c *Cache[K, V]) CompareAndSwap(key K, expected, new V, compare func(V, V) bool, exp Expiration) (swapped, present bool)
- func (c *Cache[K, V]) Get(key K) (V, bool)
- func (c *Cache[K, V]) GetAll() map[K]V
- func (c *Cache[K, V]) GetMultiple(keys ...K) map[K]V
- func (c *Cache[K, V]) GetOrSet(key K, val V, exp Expiration) (value V, present bool)
- func (c *Cache[K, V]) Len() int
- func (c *Cache[K, V]) Peek(key K) (V, bool)
- func (c *Cache[K, V]) PeekAll() map[K]V
- func (c *Cache[K, V]) PeekMultiple(keys ...K) map[K]V
- func (c *Cache[K, V]) Remove(key K) (present bool)
- func (c *Cache[K, V]) RemoveAll()
- func (c *Cache[K, V]) RemoveExpired()
- func (c *Cache[K, V]) Replace(key K, val V, exp Expiration) (present bool)
- func (c *Cache[K, V]) ReplaceKey(old, new K, exp Expiration) (present bool)
- func (c *Cache[K, V]) ReplaceWithFunc(key K, f func(current V) (new V), exp Expiration) (present bool)
- func (c *Cache[K, V]) Set(key K, val V, exp Expiration)
- type DefaultStringHasher64
- type EvictionCallback
- type EvictionPolicy
- type EvictionReason
- type Expiration
- type Hasher64
- type Numberdeprecated
- type Option
- func WithCleanerOption[K comparable, V any](interval time.Duration) Option[K, V]
- func WithDefaultExpirationOption[K comparable, V any](d time.Duration) Option[K, V]
- func WithDefaultSlidingExpirationOption[K comparable, V any](d time.Duration) Option[K, V]
- func WithEvictionCallbackOption[K comparable, V any](f EvictionCallback[K, V]) Option[K, V]
- func WithMaxEntriesLimitOption[K comparable, V any](limit int, policy EvictionPolicy) Option[K, V]
- func WithMaxEntriesOption[K comparable, V any](n int) Option[K, V]deprecated
- type Sharded
- func (s *Sharded[K, V]) Close()
- func (s *Sharded[K, V]) CompareAndSwap(key K, expected, new V, compare func(V, V) bool, exp Expiration) (swapped, present bool)
- func (s *Sharded[K, V]) Get(key K) (value V, present bool)
- func (s *Sharded[K, V]) GetAll() map[K]V
- func (s *Sharded[K, V]) GetMultiple(keys ...K) map[K]V
- func (s *Sharded[K, V]) GetOrSet(key K, val V, exp Expiration) (value V, present bool)
- func (s *Sharded[K, V]) Len() int
- func (s *Sharded[K, V]) Peek(key K) (V, bool)
- func (s *Sharded[K, V]) PeekAll() map[K]V
- func (s *Sharded[K, V]) PeekMultiple(keys ...K) map[K]V
- func (s *Sharded[K, V]) Remove(key K) (present bool)
- func (s *Sharded[K, V]) RemoveAll()
- func (s *Sharded[K, V]) RemoveExpired()
- func (s *Sharded[K, V]) Replace(key K, val V, exp Expiration) (present bool)
- func (s *Sharded[K, V]) ReplaceKey(old, new K, exp Expiration) (present bool)
- func (s *Sharded[K, V]) ReplaceWithFunc(key K, fn func(V) V, exp Expiration) (present bool)
- func (s *Sharded[K, V]) Set(key K, val V, exp Expiration)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Decrement
deprecated
added in
v0.5.0
func Decrement[V Number](old V) V
Decrement decrements the given number by one.
Deprecated: Decrement function is deprecated. It is easy to write your own function. imcache's goal is to be simple. Creating artificial types or functions that are not even needed conflicts with this goal.
func Increment
deprecated
added in
v0.5.0
func Increment[V Number](old V) V
Increment increments the given number by one.
Deprecated: Increment function is deprecated. It is easy to write your own function. imcache's goal is to be simple. Creating artificial types or functions that are not even needed conflicts with this goal.
Types ¶
type Cache ¶
type Cache[K comparable, V any] struct { // contains filtered or unexported fields }
Cache is a non-sharded in-memory cache.
By default, it has no default expiration, no default sliding expiration no entry limit and no eviction callback.
The zero value Cache is ready to use.
If you want to configure a Cache, use the New function and provide proper Option(s).
Example:
c := imcache.New[string, interface{}]( imcache.WithDefaultExpirationOption[string, interface{}](time.Second), imcache.WithCleanerOption[string, interface{}](5*time.Minute), imcache.WithMaxEntriesOption[string, interface{}](10000), imcache.WithEvictionCallbackOption[string, interface{}](LogEvictedEntry), )
func New ¶
func New[K comparable, V any](opts ...Option[K, V]) *Cache[K, V]
New returns a new Cache instance.
By default, a returned Cache has no default expiration, no default sliding expiration, no entry limit and no eviction callback.
Option(s) can be used to customize the returned Cache.
func (*Cache[K, V]) Close ¶ added in v0.10.0
func (c *Cache[K, V]) Close()
Close closes the cache. It purges all entries and stops the cleaner if it is running. After Close, all other methods are NOP returning zero values immediately.
It is safe to call Close multiple times.
It's not necessary to call Close if the cache is no longer referenced and there is no cleaner running. Garbage collector will collect the cache.
func (*Cache[K, V]) CompareAndSwap ¶ added in v1.1.0
func (c *Cache[K, V]) CompareAndSwap(key K, expected, new V, compare func(V, V) bool, exp Expiration) (swapped, present bool)
CompareAndSwap replaces the value for the given key if the current value is equal to the expected value.
Equality is defined by the given compare function.
If it encounters an expired entry, the expired entry is evicted.
func (*Cache[K, V]) Get ¶
Get returns the value for the given key.
If it encounters an expired entry, the expired entry is evicted.
func (*Cache[K, V]) GetAll ¶ added in v0.3.0
func (c *Cache[K, V]) GetAll() map[K]V
GetAll returns a copy of all entries in the cache.
If it encounters an expired entry, the expired entry is evicted.
func (*Cache[K, V]) GetMultiple ¶ added in v1.1.0
func (c *Cache[K, V]) GetMultiple(keys ...K) map[K]V
GetMultiple returns the values for the given keys. If the Cache is not closed, then the returned map is always a non-nil one.
If it encounters an expired entry, the expired entry is evicted.
func (*Cache[K, V]) GetOrSet ¶ added in v0.4.0
func (c *Cache[K, V]) GetOrSet(key K, val V, exp Expiration) (value V, present bool)
GetOrSet returns the value for the given key and true if it exists, otherwise it sets the value for the given key and returns the set value and false.
If it encounters an expired entry, the expired entry is evicted.
func (*Cache[K, V]) Peek ¶ added in v1.2.0
Peek returns the value for the given key without actively evicting the entry if it is expired and updating the entry's sliding expiration.
If the max entries limit is set, it doesn't update the entry's position in the eviction queue.
func (*Cache[K, V]) PeekAll ¶ added in v1.2.0
func (c *Cache[K, V]) PeekAll() map[K]V
PeekAll returns a copy of all entries in the cache without actively evicting the encountered entry if it is expired and updating the entry's sliding expiration.
If the max entries limit is set, it doesn't update the encountered entry's position in the eviction queue.
func (*Cache[K, V]) PeekMultiple ¶ added in v1.2.0
func (c *Cache[K, V]) PeekMultiple(keys ...K) map[K]V
PeekMultiple returns the values for the given keys without actively evicting the encountered entry if it is expired and updating the entry's sliding expiration. If the Cache is not closed, then the returned map is always a non-nil one.
If the max entries limit is set, it doesn't update the encountered entry's position in the eviction queue.
func (*Cache[K, V]) Remove ¶
Remove removes the cache entry for the given key.
It returns true if the entry is present and removed, otherwise it returns false.
If it encounters an expired entry, the expired entry is evicted. It results in calling the eviction callback with EvictionReasonExpired, not EvictionReasonRemoved. If entry is expired, it returns false.
func (*Cache[K, V]) RemoveAll ¶
func (c *Cache[K, V]) RemoveAll()
RemoveAll removes all entries.
If an eviction callback is set, it is called for each removed entry.
If it encounters an expired entry, the expired entry is evicted. It results in calling the eviction callback with EvictionReasonExpired, not EvictionReasonRemoved.
func (*Cache[K, V]) RemoveExpired ¶ added in v0.9.0
func (c *Cache[K, V]) RemoveExpired()
RemoveExpired removes all expired entries.
If an eviction callback is set, it is called for each removed entry.
func (*Cache[K, V]) Replace ¶
func (c *Cache[K, V]) Replace(key K, val V, exp Expiration) (present bool)
Replace replaces the value for the given key. It returns true if the value is present and replaced, otherwise it returns false.
If it encounters an expired entry, the expired entry is evicted.
If you want to add or replace an entry, use the Set method instead.
func (*Cache[K, V]) ReplaceKey ¶ added in v0.11.0
func (c *Cache[K, V]) ReplaceKey(old, new K, exp Expiration) (present bool)
ReplaceKey replaces the given old key with the new key. The value remains the same. It returns true if the key is present and replaced, otherwise it returns false. If there is an existing entry for the new key, it is replaced.
If it encounters an expired entry, the expired entry is evicted.
func (*Cache[K, V]) ReplaceWithFunc ¶ added in v0.5.0
func (c *Cache[K, V]) ReplaceWithFunc(key K, f func(current V) (new V), exp Expiration) (present bool)
ReplaceWithFunc replaces the value for the given key with the result of the given function that takes the current value as an argument. It returns true if the value is present and replaced, otherwise it returns false.
If it encounters an expired entry, the expired entry is evicted.
If you want to replace the value with a new value not depending on the current value, use the Replace method instead.
Example showing how to increment the value by 1 using ReplaceWithFunc:
var c imcache.Cache[string, int32] c.Set("foo", 997, imcache.WithNoExpiration()) _ = c.ReplaceWithFunc( "foo", func(current int32) int32 { return current + 1 }, imcache.WithNoExpiration(), )
func (*Cache[K, V]) Set ¶
func (c *Cache[K, V]) Set(key K, val V, exp Expiration)
Set sets the value for the given key. If the entry already exists, it is replaced.
If it encounters an expired entry, it is evicted and a new entry is added.
If you don't want to replace an existing entry, use the GetOrSet method instead. If you don't want to add a new entry if it doesn't exist, use the Replace method instead.
type DefaultStringHasher64 ¶ added in v0.2.0
type DefaultStringHasher64 struct{}
DefaultStringHasher64 is the default hasher for string keys. It uses the FNV-1a hash function.
func (DefaultStringHasher64) Sum64 ¶ added in v0.2.0
func (DefaultStringHasher64) Sum64(key string) uint64
Sum64 returns the 64-bit hash of the input key.
type EvictionCallback ¶
type EvictionCallback[K comparable, V any] func(key K, val V, reason EvictionReason)
EvictionCallback is the callback function that is called when an entry is evicted.
type EvictionPolicy ¶ added in v1.2.0
type EvictionPolicy int32
EvictionPolicy represents the eviction policy.
const ( // EvictionPolicyLRU is the least recently used eviction policy. EvictionPolicyLRU EvictionPolicy = iota + 1 // EvictionPolicyLFU is the least frequently used eviction policy. EvictionPolicyLFU // EvictionPolicyRandom is the random eviction policy. // It evicts the entry randomly when the max entries limit exceeded. EvictionPolicyRandom )
type EvictionReason ¶
type EvictionReason int32
EvictionReason is the reason why an entry was evicted.
const ( // EvictionReasonExpired indicates that the entry was evicted // because it expired. EvictionReasonExpired EvictionReason = iota + 1 // EvictionReasonRemoved indicates that the entry was evicted // because it was removed. EvictionReasonRemoved // EvictionReasonReplaced indicates that the entry was evicted // because it was replaced. EvictionReasonReplaced // EvictionReasonMaxEntriesExceeded indicates that the entry was evicted // because the max entries limit was exceeded. // // imcache uses LRU eviction policy when the cache exceeds the max entries // limit. The least recently used entry is evicted regardless of the // entry's expiration time. EvictionReasonMaxEntriesExceeded // EvictionReasonKeyReplaced indicates that the entry was evicted // because the key was replaced. EvictionReasonKeyReplaced )
func (EvictionReason) String ¶ added in v0.3.0
func (r EvictionReason) String() string
type Expiration ¶
type Expiration interface {
// contains filtered or unexported methods
}
Expiration is the expiration time of an entry.
func WithDefaultExpiration ¶
func WithDefaultExpiration() Expiration
WithDefaultExpiration returns an Expiration that sets the expiration time to the default expiration time.
func WithExpiration ¶
func WithExpiration(d time.Duration) Expiration
WithExpiration returns an Expiration that sets the expiration time to now + d.
func WithExpirationDate ¶ added in v0.4.0
func WithExpirationDate(t time.Time) Expiration
WithExpirationDate returns an Expiration that sets the expiration time to t.
func WithNoExpiration ¶
func WithNoExpiration() Expiration
WithNoExpiration returns an Expiration that sets the expiration time to never expire.
func WithSlidingExpiration ¶
func WithSlidingExpiration(d time.Duration) Expiration
WithSlidingExpiration returns an Expiration that sets the expiration time to now + d and sets the sliding expiration to d.
The sliding expiration is the time after which the entry is considered expired if it has not been accessed. If the entry has been accessed, the expiration time is reset to now + d where now is the time of the access.
type Hasher64 ¶ added in v0.2.0
type Hasher64[K comparable] interface { // Sum64 returns the 64-bit hash of the input key. Sum64(K) uint64 }
Hasher64 is the interface that wraps the Sum64 method.
type Number
deprecated
added in
v0.5.0
type Number interface { ~float32 | ~float64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr | ~int | ~int8 | ~int16 | ~int32 | ~int64 }
Number is a constraint that permits any numeric type except complex ones.
Deprecated: Number constraint is deprecated. It is easy to write your own constraint. imcache's goal is to be simple. Creating artificial types or functions that are not even needed conflicts with this goal.
type Option ¶
type Option[K comparable, V any] interface { // contains filtered or unexported methods }
Option configures the cache.
func WithCleanerOption ¶ added in v0.10.0
func WithCleanerOption[K comparable, V any](interval time.Duration) Option[K, V]
WithCleanerOption returns an Option that sets a cache cleaner that periodically removes expired entries from the cache.
A cleaner runs in a separate goroutine. It removes expired entries every interval. If the interval is less than or equal to zero, the cleaner is disabled.
A cleaner is stopped when the cache is closed.
func WithDefaultExpirationOption ¶
func WithDefaultExpirationOption[K comparable, V any](d time.Duration) Option[K, V]
WithDefaultExpirationOption returns an Option that sets the cache default expiration.
func WithDefaultSlidingExpirationOption ¶
func WithDefaultSlidingExpirationOption[K comparable, V any](d time.Duration) Option[K, V]
WithDefaultSlidingExpirationOption returns an Option that sets the cache default sliding expiration.
func WithEvictionCallbackOption ¶
func WithEvictionCallbackOption[K comparable, V any](f EvictionCallback[K, V]) Option[K, V]
WithEvictionCallbackOption returns an Option that sets the cache eviction callback.
func WithMaxEntriesLimitOption ¶ added in v1.2.0
func WithMaxEntriesLimitOption[K comparable, V any](limit int, policy EvictionPolicy) Option[K, V]
WithMaxEntriesLimitOption returns an Option that sets the cache maximum number of entries. When the limit is exceeded, the entry is evicted according to the eviction policy.
If used with Sharded type, the maximum size is per shard, not the total size of all shards.
func WithMaxEntriesOption
deprecated
added in
v0.8.0
func WithMaxEntriesOption[K comparable, V any](n int) Option[K, V]
WithMaxEntriesOption returns an Option that sets the cache maximum number of entries. When the maximum number of entries is exceeded, the entry is evicted according to the LRU eviction policy.
If used with Sharded type, the maximum size is per shard, not the total size of all shards.
Deprecated: Use WithMaxEntriesLimitOption instead.
type Sharded ¶ added in v0.7.0
type Sharded[K comparable, V any] struct { // contains filtered or unexported fields }
Sharded is a sharded in-memory cache. It is a cache consisting of n shards and sharded by the given Hasher64.
Each shard is a separate Cache instance.
By default, it has no default expiration, no default sliding expiration no entry limit and no eviction callback.
The zero value Sharded is NOT ready to use. The NewSharded function must be used to create a new Sharded.
Example:
c := imcache.NewSharded[string, interface{}](8, imcache.DefaultStringHasher64{}, imcache.WithDefaultExpirationOption[string, interface{}](time.Second), imcache.WithCleanerOption[string, interface{}](5*time.Minute), imcache.WithMaxEntriesOption[string, interface{}](10000), imcache.WithEvictionCallbackOption[string, interface{}](LogEvictedEntry), )
func NewSharded ¶
func NewSharded[K comparable, V any](n int, hasher Hasher64[K], opts ...Option[K, V]) *Sharded[K, V]
NewSharded returns a new Sharded instance. It panics if n is not greater than 0 or hasher is nil.
By default, a returned Sharded has no default expiration, no default sliding expiration, no entry limit and no eviction callback.
Option(s) can be used to customize the returned Sharded. Note that Option(s) are applied to each shard (Cache instance) not to the Sharded instance itself.
func (*Sharded[K, V]) Close ¶ added in v0.10.0
func (s *Sharded[K, V]) Close()
Close closes the cache. It purges all entries and stops the cleaner if it is running. After Close, all other methods are NOP returning zero values immediately.
It is safe to call Close multiple times.
It's not necessary to call Close if the cache is no longer referenced and there is no cleaner running. Garbage collector will collect the cache.
func (*Sharded[K, V]) CompareAndSwap ¶ added in v1.1.0
func (s *Sharded[K, V]) CompareAndSwap(key K, expected, new V, compare func(V, V) bool, exp Expiration) (swapped, present bool)
CompareAndSwap replaces the value for the given key if the current value is equal to the expected value.
Equality is defined by the given compare function.
If it encounters an expired entry, the expired entry is evicted.
func (*Sharded[K, V]) Get ¶ added in v0.7.0
Get returns the value for the given key.
If it encounters an expired entry, the expired entry is evicted.
func (*Sharded[K, V]) GetAll ¶ added in v0.7.0
func (s *Sharded[K, V]) GetAll() map[K]V
GetAll returns a copy of all entries in the cache.
If it encounters an expired entry, the expired entry is evicted.
func (*Sharded[K, V]) GetMultiple ¶ added in v1.1.0
func (s *Sharded[K, V]) GetMultiple(keys ...K) map[K]V
GetMultiple returns the values for the given keys. If the Sharded is not closed, then the returned map is always a non-nil one.
If it encounters an expired entry, the expired entry is evicted.
func (*Sharded[K, V]) GetOrSet ¶ added in v0.7.0
func (s *Sharded[K, V]) GetOrSet(key K, val V, exp Expiration) (value V, present bool)
GetOrSet returns the value for the given key and true if it exists, otherwise it sets the value for the given key and returns the set value and false.
If it encounters an expired entry, the expired entry is evicted.
func (*Sharded[K, V]) Peek ¶ added in v1.2.0
Peek returns the value for the given key without actively evicting the entry if it is expired and updating the entry's sliding expiration.
If the max entries limit is set, it doesn't update the entry's position in the eviction queue.
func (*Sharded[K, V]) PeekAll ¶ added in v1.2.0
func (s *Sharded[K, V]) PeekAll() map[K]V
PeekAll returns a copy of all entries in the cache without actively evicting the encountered entry if it is expired and updating the entry's sliding expiration.
If the max entries limit is set, it doesn't update the encountered entry's position in the eviction queue.
func (*Sharded[K, V]) PeekMultiple ¶ added in v1.2.0
func (s *Sharded[K, V]) PeekMultiple(keys ...K) map[K]V
PeekMultiple returns the values for the given keys without actively evicting the encountered entry if it is expired and updating the entry's sliding expiration. If the Sharded is not closed, then the returned map is always a non-nil one.
If the max entries limit is set, it doesn't update the encountered entry's position in the eviction queue.
func (*Sharded[K, V]) Remove ¶ added in v0.7.0
Remove removes the cache entry for the given key.
It returns true if the entry is present and removed, otherwise it returns false.
If it encounters an expired entry, the expired entry is evicted. It results in calling the eviction callback with EvictionReasonExpired, not EvictionReasonRemoved. If entry is expired, it returns false.
func (*Sharded[K, V]) RemoveAll ¶ added in v0.7.0
func (s *Sharded[K, V]) RemoveAll()
RemoveAll removes all entries.
If an eviction callback is set, it is called for each removed entry.
If it encounters an expired entry, the expired entry is evicted. It results in calling the eviction callback with EvictionReasonExpired, not EvictionReasonRemoved.
func (*Sharded[K, V]) RemoveExpired ¶ added in v0.9.0
func (s *Sharded[K, V]) RemoveExpired()
RemoveExpired removes all expired entries.
If an eviction callback is set, it is called for each removed entry.
func (*Sharded[K, V]) Replace ¶ added in v0.7.0
func (s *Sharded[K, V]) Replace(key K, val V, exp Expiration) (present bool)
Replace replaces the value for the given key. It returns true if the value is present and replaced, otherwise it returns false.
If it encounters an expired entry, the expired entry is evicted.
If you want to add or replace an entry, use the Set method instead.
func (*Sharded[K, V]) ReplaceKey ¶ added in v0.11.0
func (s *Sharded[K, V]) ReplaceKey(old, new K, exp Expiration) (present bool)
ReplaceKey replaces the given old key with the new key. The value remains the same. It returns true if the key is present and replaced, otherwise it returns false. If there is an existing entry for the new key, it is replaced.
If it encounters an expired entry, the expired entry is evicted.
func (*Sharded[K, V]) ReplaceWithFunc ¶ added in v0.7.0
func (s *Sharded[K, V]) ReplaceWithFunc(key K, fn func(V) V, exp Expiration) (present bool)
ReplaceWithFunc replaces the value for the given key with the result of the given function that takes the old value as an argument. It returns true if the value is present and replaced, otherwise it returns false.
If it encounters an expired entry, the expired entry is evicted.
If you want to replace the value with a new value not depending on the old value, use the Replace method instead.
imcache provides the Increment and Decrement functions that can be used as f to increment or decrement the old numeric type value.
Example:
c := imcache.NewSharded[string, int32](4, imcache.DefaultStringHasher64{}) c.Set("foo", 997, imcache.WithNoExpiration()) _ = c.ReplaceWithFunc("foo", imcache.Increment[int32], imcache.WithNoExpiration())
func (*Sharded[K, V]) Set ¶ added in v0.7.0
func (s *Sharded[K, V]) Set(key K, val V, exp Expiration)
Set sets the value for the given key. If the entry already exists, it is replaced.
If it encounters an expired entry, it is evicted and a new entry is added.
If you don't want to replace an existing entry, use the GetOrSet method instead. If you don't want to add a new entry if it doesn't exist, use the Replace method instead.