README
¶
Mango Cache
Partial implementations of Guava Cache in Go.
Supported cache replacement policies:
- LRU
- Segmented LRU (default)
- TinyLFU (experimental)
The TinyLFU implementation is inspired by Caffeine by Ben Manes and go-tinylfu by Damian Gryski.
Improvement
- [Cache.GetIfPresent] return nil while value expired. ignore LoadingCache.refreshAfterWrite
- [LoadingCache.Get] refresh value if expired
- [LoadingCache.Reload] new API. force reload value from loader
- [Cache.Put,Invalidate] sync with timeout. Cache.Put(k, v).Sync() / Cache.Put(k, v).Wait(time.Second)
Download
go get -u github.com/goburrow/cache
Example
package main
import (
"fmt"
"math/rand"
"time"
"github.com/goburrow/cache"
)
func main() {
load := func(k cache.Key) (cache.Value, error) {
return fmt.Sprintf("%d", k), nil
}
// Create a new cache
c := cache.NewLoadingCache(load,
cache.WithMaximumSize(1000),
cache.WithExpireAfterAccess(10*time.Second),
cache.WithRefreshAfterWrite(60*time.Second),
)
getTicker := time.Tick(10 * time.Millisecond)
reportTicker := time.Tick(1 * time.Second)
for {
select {
case <-getTicker:
_, _ = c.Get(rand.Intn(2000))
case <-reportTicker:
st := cache.Stats{}
c.Stats(&st)
fmt.Printf("%+v\n", st)
}
}
}
Performance
See traces
Documentation
¶
Overview ¶
Package cache provides partial implementations of Guava Cache, including support for LRU, Segmented LRU and TinyLFU.
Index ¶
- type Cache
- type Func
- type Future
- type Hash
- type Key
- type LoaderFunc
- type LoadingCache
- type Option
- func WithExpireAfterAccess(d time.Duration) Option
- func WithExpireAfterWrite(d time.Duration) Option
- func WithFullGcDuration(d time.Duration) Option
- func WithMaximumSize(size int) Option
- func WithPolicy(name string) Option
- func WithRefreshAfterWrite(d time.Duration) Option
- func WithRemovalListener(onRemoval Func) Option
- func WithStatsCounter(st StatsCounter) Option
- type Stats
- type StatsCounter
- type Value
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache interface {
// GetIfPresent returns value associated with Key or (nil, false)
// if there is no cached value for Key.
GetIfPresent(Key) (Value, bool)
// Put associates value with Key. If a value is already associated
// with Key, the old one will be replaced with Value.
Put(Key, Value) Future
// Invalidate discards cached value of the given Key.
Invalidate(Key) Future
// InvalidateAll discards all entries.
InvalidateAll() Future
// Stats copies cache statistics to given Stats pointer.
Stats(*Stats)
// Close implements io.Closer for cleaning up all resources.
// Once cache is closed, it should no longer be used.
Close() error
}
Cache is a key-value cache which entries are added and stayed in the cache until either are evicted or manually invalidated.
type Hash ¶
type Hash interface {
Sum64() uint64
}
Hash is an interface implemented by cache keys to override default hash function.
type Key ¶
type Key interface{}
Key is any value which is comparable. See http://golang.org/ref/spec#Comparison_operators for details.
type LoaderFunc ¶
LoaderFunc retrieves the value corresponding to given Key.
type LoadingCache ¶
type LoadingCache interface {
Cache
// Get returns value associated with Key or call underlying LoaderFunc
// to load value if it is not present.
Get(Key) (Value, error)
Reload(k Key) (Value, Future, error)
}
LoadingCache is a cache with values are loaded automatically and stored in the cache until either evicted or manually invalidated.
func NewLoadingCache ¶
func NewLoadingCache(loader LoaderFunc, options ...Option) LoadingCache
NewLoadingCache returns a new LoadingCache with given loader function and cache options.
type Option ¶
type Option func(c *localCache)
Option add options for default Cache.
func WithExpireAfterAccess ¶
WithExpireAfterAccess returns an option to expire a cache entry after the given duration without being accessed.
func WithExpireAfterWrite ¶
WithExpireAfterWrite returns an option to expire a cache entry after the given duration from creation.
func WithFullGcDuration ¶
func WithMaximumSize ¶
WithMaximumSize returns an Option which sets maximum size for the cache. Any non-positive numbers is considered as unlimited.
func WithPolicy ¶
WithPolicy returns an option which set cache policy associated to the given name. Supported policies are: lru, slru, tinylfu.
func WithRefreshAfterWrite ¶
WithRefreshAfterWrite returns an option to refresh a cache entry after the given duration. This option is only applicable for LoadingCache.
func WithRemovalListener ¶
WithRemovalListener returns an Option to set cache to call onRemoval for each entry evicted from the cache.
func WithStatsCounter ¶
func WithStatsCounter(st StatsCounter) Option
WithStatsCounter returns an option which overrides default cache stats counter.
type Stats ¶
type Stats struct {
HitCount uint64
MissCount uint64
LoadSuccessCount uint64
LoadErrorCount uint64
TotalLoadTime time.Duration
EvictionCount uint64
}
Stats is statistics about performance of a cache.
func (*Stats) AverageLoadPenalty ¶
AverageLoadPenalty returns the average time spent loading new values.
func (*Stats) LoadErrorRate ¶
LoadErrorRate returns the ratio of cache loading attempts which returned errors.
func (*Stats) RequestCount ¶
RequestCount returns a total of HitCount and MissCount.
type StatsCounter ¶
type StatsCounter interface {
// RecordHits records cache hits.
RecordHits(count uint64)
// RecordMisses records cache misses.
RecordMisses(count uint64)
// RecordLoadSuccess records successful load of a new entry.
RecordLoadSuccess(loadTime time.Duration)
// RecordLoadError records failed load of a new entry.
RecordLoadError(loadTime time.Duration)
// RecordEviction records eviction of an entry from the cache.
RecordEviction()
// Snapshot writes snapshot of this counter values to the given Stats pointer.
Snapshot(*Stats)
}
StatsCounter accumulates statistics of a cache.
Source Files
Directories