bigcache

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

import "github.com/allegro/bigcache"

cache := bigcache.NewBigCache(bigcache.DefaultConfig(10 * time.Minute))

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

entry, _ := cache.Get("my-unique-key")
fmt.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.

import "github.com/allegro/bigcache"

config := bigcache.Config{
		Shards: 1000,                       // number of shards
		LifeWindow: 10 * time.Minute,       // time after which entry can be evicted
		MaxEntriesInWindow: 1000 * 10 * 60, // rps * lifeWindow
		MaxEntrySize: 500,                  // max entry size in bytes
		Verbose: true,                      // prints information about additional memory allocation
	}

cache := bigcache.NewBigCache(config)

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

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

How it works

BigCache relays 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.

License

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

Documentation

Index

• type BigCache
  • func NewBigCache(config Config) *BigCache
  • func (c *BigCache) Get(key string) ([]byte, error)
  • func (c *BigCache) Set(key string, entry []byte)
• type Config
  • func DefaultConfig(eviction time.Duration) Config
• type EntryNotFoundError
  • func (e EntryNotFoundError) Error() string

Types

type BigCache

type BigCache struct {
	// contains filtered or unexported fields
}

BigCache is fast, concurrent, evicting cache created to keep big number of entries without impact on performance. It 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.

func NewBigCache

func NewBigCache(config Config) *BigCache

NewBigCache initialize new instance of BigCache

func (*BigCache) Get

func (c *BigCache) Get(key string) ([]byte, error)

Get reads entry for the key

func (*BigCache) Set

func (c *BigCache) Set(key string, entry []byte)

Set saves entry under the key

type Config

type Config struct {
	// Number of cache shards
	Shards int
	// Time after which entry can be evicted
	LifeWindow time.Duration
	// Max number of entries in life window. Used to allocate proper size of cache in every shard.
	// When proper value is set then cache will not allocate additional memory
	MaxEntriesInWindow int
	// Max size of entry in bytes. Used to allocate proper size of cache in every shard.
	MaxEntrySize int
	// Verbose mode prints information about new memory allocation
	Verbose bool
}

Config for BigCache

func DefaultConfig

func DefaultConfig(eviction time.Duration) Config

DefaultConfig initializes config with default values. When load for BigCache can be predicted in advance then it is better to use custom config.

type EntryNotFoundError

type EntryNotFoundError struct {
	// contains filtered or unexported fields
}

EntryNotFoundError is an error type struct which is returned when entry was not found for provided key

func (EntryNotFoundError) Error

func (e EntryNotFoundError) Error() string

Error returned when entry does not exist.