allegro/bigcache

Name: bigcache

Owner: Allegro Tech

Description: Efficient cache for gigabytes of data written in Go.

Created: 2016-03-23 07:18:52.0

Updated: 2018-01-18 17:10:45.0

Pushed: 2017-11-30 23:44:30.0

Homepage: http://allegro.tech/2016/03/writing-fast-cache-service-in-go.html

Size: 107

Language: Go

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

BigCache    

Fast, concurrent, evicting in-memory cache written to keep big number of entries without impact on performance. BigCache keeps entries on heap but omits GC for them. To achieve that operations on bytes arrays take place, therefore entries (de)serialization in front of the cache will be needed in most use cases.

Usage

Simple initialization

rt "github.com/allegro/bigcache"

e, _ := bigcache.NewBigCache(bigcache.DefaultConfig(10 * time.Minute))

e.Set("my-unique-key", []byte("value"))

y, _ := cache.Get("my-unique-key")
Println(string(entry))

Custom initialization

When cache load can be predicted in advance then it is better to use custom initialization because additional memory allocation can be avoided in that way.

rt (
"log"

"github.com/allegro/bigcache"


ig := bigcache.Config {
    // number of shards (must be a power of 2)
    Shards: 1024,
    // time after which entry can be evicted
    LifeWindow: 10 * time.Minute,
    // rps * lifeWindow, used only in initial memory allocation
    MaxEntriesInWindow: 1000 * 10 * 60,
    // max entry size in bytes, used only in initial memory allocation
    MaxEntrySize: 500,
    // prints information about additional memory allocation
    Verbose: true,
    // cache will not allocate more memory than this limit, value in MB
    // if value is reached then the oldest entries can be overridden for the new ones
    // 0 value means no size limit
    HardMaxCacheSize: 8192,
    // callback fired when the oldest entry is removed because of its
    // expiration time or no space left for the new entry. Default value is nil which
    // means no callback and it prevents from unwrapping the oldest entry.
    OnRemove: nil,
}

e, initErr := bigcache.NewBigCache(config)
nitErr != nil {
log.Fatal(initErr)


e.Set("my-unique-key", []byte("value"))

ntry, err := cache.Get("my-unique-key"); err == nil {
fmt.Println(string(entry))

Benchmarks

Three caches were compared: bigcache, freecache and map. Benchmark tests were made using an i7-6700K with 32GB of RAM on Windows 10.

Writes and reads

aches_bench; go test -bench=. -benchtime=10s ./... -timeout 30m

hmarkMapSet-8                        2000000           716 ns/op         336 B/op          3 allocs/op
hmarkConcurrentMapSet-8              1000000          1292 ns/op         347 B/op          8 allocs/op
hmarkFreeCacheSet-8                  3000000           501 ns/op         371 B/op          3 allocs/op
hmarkBigCacheSet-8                   3000000           482 ns/op         303 B/op          2 allocs/op
hmarkMapGet-8                        5000000           309 ns/op          24 B/op          1 allocs/op
hmarkConcurrentMapGet-8              2000000           659 ns/op          24 B/op          2 allocs/op
hmarkFreeCacheGet-8                  3000000           541 ns/op         152 B/op          3 allocs/op
hmarkBigCacheGet-8                   3000000           420 ns/op         152 B/op          3 allocs/op
hmarkBigCacheSetParallel-8          10000000           184 ns/op         313 B/op          3 allocs/op
hmarkFreeCacheSetParallel-8         10000000           195 ns/op         357 B/op          4 allocs/op
hmarkConcurrentMapSetParallel-8      5000000           242 ns/op         200 B/op          6 allocs/op
hmarkBigCacheGetParallel-8          20000000           100 ns/op         152 B/op          4 allocs/op
hmarkFreeCacheGetParallel-8         10000000           133 ns/op         152 B/op          4 allocs/op
hmarkConcurrentMapGetParallel-8     10000000           202 ns/op          24 B/op          2 allocs/op

Writes and reads in bigcache are faster than in freecache. Writes to map are the slowest.

GC pause time

aches_bench; go run caches_gc_overhead_comparison.go

er of entries:  20000000
ause for bigcache:  27.81671ms
ause for freecache:  30.218371ms
ause for map:  11.590772251s

Test shows how long are the GC pauses for caches filled with 20mln of entries. Bigcache and freecache have very similar GC pause time. It is clear that both reduce GC overhead in contrast to map which GC pause time took more than 10 seconds.

How it works

BigCache relies on optimization presented in 1.5 version of Go (issue-9477). This optimization states that if map without pointers in keys and values is used then GC will omit it?s content. Therefore BigCache uses map[uint64]uint32 where keys are hashed and values are offsets of entries.

Entries are kept in bytes array, to omit GC again. Bytes array size can grow to gigabytes without impact on performance because GC will only see single pointer to it.

Bigcache vs Freecache

Both caches provide the same core features but they reduce GC overhead in different ways. Bigcache relies on map[uint64]uint32, freecache implements its own mapping built on slices to reduce number of pointers.

Results from benchmark tests are presented above. One of the advantage of bigcache over freecache is that you don?t need to know the size of the cache in advance, because when bigcache is full, it can allocate additional memory for new entries instead of overwriting existing ones as freecache does currently. However hard max size in bigcache also can be set, check HardMaxCacheSize.

More

Bigcache genesis is described in allegro.tech blog post: writing a very fast cache service in Go

License

BigCache is released under the Apache 2.0 license (see LICENSE)