kocache

README

kocache

Single flight cache.

While one request is trying to fetch data to cache, subsequent requests wait for it.

Usage

Initialization

cache, err := kocache.New()

Get

value, err := cache.Get(key)

Cache

resolve := cache.Reserve(key)

data, err := fetchSomething();
resolve(data, err)
if err != nil {
    return err
}

Stats

stats := cache.Stats()
fmt.Printf("%+v", stats) // {Hits:123 Misses:456}

Documentation

Full docs are available on Godoc

And you can see the design concept at Qiita (Sorry, but it's Japanese)

Dependencies(Thanks)

• kocache wraps hashicorp/golang-lru inside.

Documentation

Index

• Constants
• Variables
• type Cache
  • func New(opts ...Option) (*Cache, error)
  • func (c *Cache) Get(key interface{}) (value interface{}, err error)
  • func (c *Cache) GetWithTimeout(key interface{}, timeout time.Duration) (value interface{}, err error)
  • func (c *Cache) Len() int
  • func (c *Cache) Reserve(key interface{}) ResolveFunc
  • func (c *Cache) ReserveWithLifetime(key interface{}, lifetime time.Duration) ResolveFunc
  • func (c *Cache) Stats() Stats
• type Option
  • func WithDefaultLifetime(defaultLifetime time.Duration) Option
  • func WithSize(size int) Option
  • func WithStats() Option
• type ResolveFunc
• type Stats

Constants

const (
	// DefaultSize is default cache size
	DefaultSize = 1024
)

Variables

var (
	// ErrEntryNotFound is an error that describes entry not found.
	ErrEntryNotFound = errors.New("entry not found")

	// ErrExpired is an error that describes cache expired
	ErrExpired = errors.New("expired")

	// ErrGetCacheTimeout is an error of timeout getting cache.
	ErrGetCacheTimeout = errors.New("get cache timeout")
)

Types

type Cache

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

Cache is single flight cache

func New

func New(opts ...Option) (*Cache, error)

New creates a new Cache.

func (*Cache) Get

func (c *Cache) Get(key interface{}) (value interface{}, err error)

Get gets a cache value by a key. It returns ErrEntryNotFound if entry is not registered.

func (*Cache) GetWithTimeout

func (c *Cache) GetWithTimeout(key interface{}, timeout time.Duration) (value interface{}, err error)

GetWithTimeout gets a cache value by a key, indicating timeout of other's fetch. It returns ErrEntryNotFound if entry is not registered, ErrGetCacheTimeout on timeout, and ErrExpired if expired.

func (*Cache) Len

func (c *Cache) Len() int

Len returns the number of entries in the cache.

func (*Cache) Reserve

func (c *Cache) Reserve(key interface{}) ResolveFunc

Reserve reserves cache entry to fetch. Caller must try fetch the value and call resolveFunc to set result. Reserve must be called jsut once. It will panic if called two or more times.

func (*Cache) ReserveWithLifetime

func (c *Cache) ReserveWithLifetime(key interface{}, lifetime time.Duration) ResolveFunc

ReserveWithLifetime reserves cache entry to fetch indicating its lifetime. Caller must try fetch the value and call resolveFunc to set result, otherwise others will wait until timeout. ReserveWithLifetime must be called jsut once. It will panic if called two or more times.

func (*Cache) Stats

func (c *Cache) Stats() Stats

Stats retuns statistics of the cache

type Option

type Option interface {
	Apply(cache *Cache)
}

An Option is an option for a kocache

func WithDefaultLifetime

func WithDefaultLifetime(defaultLifetime time.Duration) Option

WithDefaultLifetime returns an Option that defines cache default lifetime.

func WithSize

func WithSize(size int) Option

WithSize returns an Option that defines cache size.

func WithStats

func WithStats() Option

WithStats returns an Option that enables cache statistics.

type ResolveFunc

type ResolveFunc func(entity interface{}, err error)

ResolveFunc describes function which resolves cache.

type Stats

type Stats struct {
	Hits   uint32
	Misses uint32
}

Stats describes cache hits&misses statistics.