Documentation
¶
Overview ¶
Package lru provides a basic least-recently-used cache. It can be used as either a read-through or a manual cache.
It supports per-entry cost, and custom on-retrieve and on-evict callbacks.
Anticipated usage (read-through):
func retrieveEntry(key lru.Key) (interface{}, lru.Cost, error) {
// Expensive retrieval operation.
}
func evictEntry(key lru.Key, value interface{}) {
// Optional release operation.
}
cache := lru.New(5)
cache.OnRetrieve = retrieveEntry
cache.OnEvict = evictEntry
value, err := cache.Get(key)
cache.Clear()
Anticipated usage (manual caching):
cache := lru.New(5)
cache.Put(key1, value1)
cache.Put(key2, value2)
value, err := cache.Get(key1)
if err != nil {
// ... (must be ErrMissingEntry)
}
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrMissingEntry = errors.New("missing entry")
ErrMissingEntry is returned from `Get` if there is no such entry in the cache, and there is no retriever function.
If there is no retriever function, this is the only error than can be returned from `Get`.
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache struct {
// MaxCost is the cost of entries allowed in the cache.
//
// If reduced between calls to Get, the next call to Get that adjusts the
// contents of the cache will reduce the cache size.
//
// The total cost of the cache may be higher than this, but only if due to
// a single "jumbo" entry whose cost is greater than this.
MaxCost Cost
// OnRetrieve, if not nil, is called when Get does not find an entry in the
// cache.
//
// If nil, the return value will be nil with a `ErrMissingEntry` error.
OnRetrieve RetrieverFunc
// OnEvict, if not nil, is called each time a cache entry is evicted.
OnEvict EvictionFunc
// contains filtered or unexported fields
}
Cache is the main cache type.
Not internally synchronized.
func New ¶
New returns a new LRU cache with the given maximum size.
You may want to add a retriever and/or eviction function to the returned cache.
If you want to limit by entry count, set the `maxCost` to the desired maximum number of entries, and return a cost of 1 from your retriever function.
Entries with a cost of 0 cannot evict other entries, but they will themselves be evicted if something more expensive comes in and the 0-cost entries were the least recently used.
Negative costs are not supported and will cause panics.
Maximum cache cost is `math.MaxInt64`.
func (*Cache) Clear ¶
func (c *Cache) Clear()
Clear evicts every entry in the cache.
If there is an OnEvict function, calls it for each entry.
func (*Cache) Evict ¶
Evict evicts a specific entry from the cache.
Does nothing if the entry does not exist in the cache.
Calls the OnEvict function if there is one.
Returns the value evicted, or nil.
func (*Cache) EvictOldest ¶
func (c *Cache) EvictOldest() interface{}
EvictOldest evicts the least recently used entry from the cache.
Returns the value evicted, or nil if the cache was empty.
func (*Cache) Get ¶
Get retrieves an entry.
If necessary and available, the cache will request the entry from the RetrieverFunc.
Panics if the cost of a new entry would overflow the cache cost.
If there is no retriever function, the only error that this can return is `ErrMissingEntry`. If there is a retriever function, this will return whatever error the retriever returned.
If the retriever returns an error, the value will not be saved in the cache, but this will return whatever value the retriever returned.
func (*Cache) Put ¶
Put directly adds an entry to the cache, or refreshes an existing entry.
If the entry already existed in the cache, its cost and value will be updated to the values provided in this call.
May cause evictions of other entries.
Panics if the cost of the new entry would overflow the cache cost.
Returns the previous value of the entry, or nil.
type Cost ¶
type Cost int64
Cost is a measure of how much an entry "costs".
The cache is limited to a chosen maximum total cost.
type EvictionFunc ¶
type EvictionFunc func(key Key, value interface{})
EvictionFunc is called when the cache evicts a value.
type RetrieverFunc ¶
RetrieverFunc is called when the cache is missing a necessary value.
If it returns an error, the value is not added to the cache, and the error is returned from `Get`.
Source Files