acache

README

acache

Package acache contains an async cache implementation.

Reference

1. golang.org/x/sync/singleflight
2. sync.singleflight 到底怎么用才对？
3. AsyncCache from ByteDance

Documentation

Index

• Variables
• type Cache
  • func NewCache(opt Options) *Cache
  • func (c *Cache) Close()
  • func (c *Cache) Contains(key string) bool
  • func (c *Cache) Delete(key string)
  • func (c *Cache) DeleteFunc(match func(key string) bool)
  • func (c *Cache) Get(key string) (any, error)
  • func (c *Cache) GetOrDefault(key string, defaultVal any) any
  • func (c *Cache) SetDefault(key string, value any) (exists bool)
  • func (c *Cache) Update(key string, value any)
• type Options

Variables

var ErrFetchTimeout = errors.New("fetch timeout")

ErrFetchTimeout indicates a timeout error when refresh a cached value if Options.FetchTimeout is specified.

Types

type Cache

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

Cache is an asynchronous cache which prevents duplicate functions calls that is massive or maybe expensive, or some data which rarely change, and we want to get it quickly.

Zero value of Cache is not ready to use. Use the function NewCache to make a new Cache instance. A Cache value shall not be copied after initialized.

func NewCache

func NewCache(opt Options) *Cache

NewCache returns a new Cache instance using the given options.

func (*Cache) Close

func (c *Cache) Close()

Close closes the Cache. It signals the refreshing and expiring goroutines to shut down.

It should be called when the Cache is no longer needed, or may lead resource leaks.

func (*Cache) Contains

func (c *Cache) Contains(key string) bool

Contains tells whether the cache contains the specified key. It returns false if key is never accessed from the cache, true means that a value or an error for key exists in the cache.

func (*Cache) Delete

func (c *Cache) Delete(key string)

Delete deletes the entry of key from the cache if it exists.

func (*Cache) DeleteFunc

func (c *Cache) DeleteFunc(match func(key string) bool)

DeleteFunc iterates the cache and deletes entries that the key matches the given function.

func (*Cache) Get

func (c *Cache) Get(key string) (any, error)

Get tries to fetch a value corresponding to the given key from the cache. If it's not cached, a calling to function Options.FetchFunc will be fired and the result will be cached.

If error occurs during the first fetching, the error will be cached until the subsequent fetching requests triggered by refreshing succeed. The cached error will be returned, it does not trigger a calling to Options.FetchFunc.

If a default value is set by SetDefault, the default value will be used, it does not trigger a calling to Options.FetchFunc.

func (*Cache) GetOrDefault

func (c *Cache) GetOrDefault(key string, defaultVal any) any

GetOrDefault tries to fetch a value corresponding to the given key from the cache. If it's not cached, a calling to function Options.FetchFunc will be fired and the result will be cached.

If error occurs during the first fetching, defaultVal will be set into the cache and returned.

func (*Cache) SetDefault

func (c *Cache) SetDefault(key string, value any) (exists bool)

SetDefault sets the default value of a given key if it is new to the cache. The param val should not be nil, else it panics. The returned bool value indicates whether the key already exists in the cache, if it already exists, this is a no-op.

It's useful to warm up the cache.

func (*Cache) Update

func (c *Cache) Update(key string, value any)

Update sets a value for key into the cache. If key is not cached in the cache, it adds the given key value to the cache. The param val should not be nil, else it panics.

type Options

type Options struct {

	// FetchFunc is a function which retrieves data from upstream system for
	// the given key. The returned value or error will be cached till next
	// refresh execution.
	// FetchFunc must not be nil, else it panics.
	//
	// The provided function must return consistently typed values,
	// else it panics when storing a value of different type into the
	// underlying sync/atomic.Value.
	//
	// The returned value from this function should not be changed after
	// retrieved from the Cache, else data race happens since there may be
	// many goroutines access the same value concurrently.
	FetchFunc func(key string) (any, error)

	// FetchTimeout is used to timeout the fetch request if given,
	// default is zero (no timeout).
	//
	// NOTE: properly configured timeout will prevent task which take very long
	// time that don't fail fast, which may further block many requests, and
	// consume huge amount of resources, cause system overload or out of memory.
	FetchTimeout time.Duration

	// RefreshInterval specifies the interval to refresh the cache values,
	// default is zero which means don't refresh the cached values.
	//
	// If there is valid cache value and the subsequent fetch requests
	// failed, the existing cache value will be kept untouched.
	RefreshInterval time.Duration

	// ExpireInterval optionally enables purging unused cached values,
	// default is zero which means no expiration.
	//
	// Note this is mainly used to purge unused data to prevent the cache
	// growing endlessly, the timing is inaccurate. Also note that
	// it may delete unused default values set by SetDefault.
	//
	// Cached values are deleted using a mark-then-delete strategy.
	// In each tick of expire interval, an active value will be marked as inactive,
	// if it's not accessed within the next expire interval, it will be
	// deleted from the Cache by the next expire execution.
	//
	// Each access of the cache value will touch it and mark it as active, which
	// prevents it being deleted from the cache.
	ExpireInterval time.Duration

	// ErrorCallback is an optional callback which will be called when
	// an error is returned by the FetchFunc during refresh.
	ErrorCallback func(key string, err error)

	// ChangeCallback is an optional callback which will be called when
	// new value is returned by the FetchFunc during refresh.
	ChangeCallback func(key string, oldData, newData any)

	// DeleteCallback is an optional callback which will be called when
	// a value is deleted from the cache.
	DeleteCallback func(key string, data any)
}

Options configures the behavior of Cache.