The highest tagged major version is
README
¶
evcache 
This README is a work in progress.
How it works
The cache is a wrapper for sync.Map with autoexpiry, capacity limit and eviction order.
It acts like a non-blocking ordered map where writes do not block reads. Each value is wrapped
in a record type and uses its own RWMutex.
The default record order is insertion order. Records are always inserted to the back of a list and when overflow occurs, the front element is evicted.
When LFU ordering is used, then records which had accumulated hits since its last move will be periodically moved forwards in the list based on the hit count delta. Eventually the list becomes LFU ordered.
Documentation
¶
Overview ¶
Package evcache provides an in-memory ordered cache with optional eventually consistent LFU ordering.
Index ¶
- Variables
- type Builder
- type Cache
- func (c *Cache) Close() error
- func (c *Cache) Evict(key interface{})
- func (c *Cache) Exists(key interface{}) bool
- func (c *Cache) Fetch(key interface{}, ttl time.Duration, f FetchCallback) (value interface{}, closer io.Closer, err error)
- func (c *Cache) Flush()
- func (c *Cache) Get(key interface{}) (value interface{}, closer io.Closer, exists bool)
- func (c *Cache) Len() int
- func (c *Cache) LoadAndEvict(key interface{}) (interface{}, bool)
- func (c *Cache) OrderedRange(f func(key, value interface{}) bool)
- func (c *Cache) Pop() (key, value interface{})
- func (c *Cache) Range(f func(key, value interface{}) bool)
- func (c *Cache) Set(key, value interface{}, ttl time.Duration)
- type EvictionCallback
- type FetchCallback
Constants ¶
This section is empty.
Variables ¶
var SyncInterval = time.Second
SyncInterval is the interval for background loop for autoexpiry and optional eventual LFU ordering.
If cache overflows while LFU is enabled and records are created faster than SyncInterval can update record ordering, the eviction starts losing LFU order and will become the insertion order with eldest first.
Functions ¶
This section is empty.
Types ¶
type Builder ¶
type Builder func(*Cache)
Builder builds a cache.
func New ¶
func New() Builder
New creates an empty cache.
Cache must be closed after usage has stopped to prevent a leaking goroutine.
It is not safe to close the cache while in use.
func (Builder) WithCapacity ¶
WithCapacity configures the cache with specified capacity.
If cache exceeds the limit, the eldest record is evicted or if LFU is enabled, the least frequently used record is evicted.
func (Builder) WithEvictionCallback ¶
func (build Builder) WithEvictionCallback(cb EvictionCallback) Builder
WithEvictionCallback specifies an asynchronous eviction callback.
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
Cache is an in-memory ordered cache with optional eventually consistent LFU ordering.
By default, records are sorted by insertion order.
All methods except Close and OrderedRange are safe to use concurrently.
func (*Cache) Close ¶
Close shuts down the cache, evicts all keys and waits for eviction callbacks to finish.
It is not safe to close the cache while in use.
func (*Cache) Evict ¶
func (c *Cache) Evict(key interface{})
Evict a key. After Evict returns, no Get or Fetch will load the key.
func (*Cache) Fetch ¶
func (c *Cache) Fetch(key interface{}, ttl time.Duration, f FetchCallback) (value interface{}, closer io.Closer, err error)
Fetch attempts to get or set the value and calls f on a miss to receive the new value. If f returns an error, no value is cached and the error is returned back to caller.
When the returned value is not used anymore, the caller MUST call closer.Close() or a memory leak will occur.
func (*Cache) Get ¶
Get returns the value stored in the cache for a key. The boolean indicates whether a value was found.
When the returned value is not used anymore, the caller MUST call closer.Close() or a memory leak will occur.
func (*Cache) LoadAndEvict ¶ added in v1.6.0
LoadAndEvict evicts a key and returns its value.
func (*Cache) OrderedRange ¶ added in v1.4.0
OrderedRange calls f sequentially for each key and value present in the cache in order. If f returns false, Range stops the iteration. When LFU is used, the order is from least to most frequently used, otherwise it is the insertion order with eldest first by default.
It is not safe to use OrderedRange concurrently with any other method except Exists and Get or a deadlock may occur.
func (*Cache) Pop ¶ added in v1.6.0
func (c *Cache) Pop() (key, value interface{})
Pop evicts and returns the oldest key and value. If LFU ordering is enabled, then the least frequently used key and value.
func (*Cache) Range ¶ added in v0.1.3
Range calls f for each key and value present in the cache in no particular order. If f returns false, Range stops the iteration.
Range does not necessarily correspond to any consistent snapshot of the cache's contents: no key will be visited more than once, but if the value for any key is stored or deleted concurrently, Range may reflect any mapping for that key from any point during the Range call.
type EvictionCallback ¶
type EvictionCallback func(key, value interface{})
EvictionCallback is an asynchronous callback which is called after cache key eviction.
It waits until all io.Closers returned by Get or Fetch are closed.
type FetchCallback ¶
type FetchCallback func() (interface{}, error)
FetchCallback is called when *Cache.Fetch has a miss and must return a new value or an error.
It blocks the key from being accessed until the callback returns.
Source Files