singleflight

README

singleflight

Package singleflight provides a duplicate function call suppression mechanism, and some cache related utilities.

Reference

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

Documentation

Overview

Package singleflight provides utilities wrapping around package golang.org/x/sync/singleflight, which provides a duplicate function call suppression mechanism.

Index

• Variables
• type Cache
  • func NewCache(opt CacheOptions) *Cache
  • func (c *Cache) Close()
  • 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, val any) (exists bool)
• type CacheOptions
• type Group
• type Result

Variables

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

ErrFetchTimeout indicates a timeout error when refresh a cached value if CacheOptions.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 fastly.

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 CacheOptions) *Cache

NewCache returns a new Cache instance using the given options.

func (*Cache) Close

func (c *Cache) Close()

Close closes the Cache. It will signal the refresh and expire goroutines of the Cache to shut down.

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

func (*Cache) Delete

func (c *Cache) Delete(key string)

Delete deletes the entry of key from the cache if it is cached.

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 first. If it's not cached, a calling of function Cache.Fetch will be fired and the result will be cached.

If error occurs during the first fetching, the error will be cached until the subsequential fetching succeeded.

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 first. If it's not cached, a calling of function Cache.Fetch will be fired and the result will be cached.

If the fetching fails, the default value will be set into the cache and returned.

func (*Cache) SetDefault

func (c *Cache) SetDefault(key string, val 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, or it panics.

It's useful to warm up the cache.

type CacheOptions

type CacheOptions struct {

	// 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 subsequential fetch requests
	// failed, the cache value will be kept untouched.
	RefreshInterval time.Duration

	// ExpireInterval optionally enables a go goroutine to expire the cached
	// values, default is zero which means no expiration.
	//
	// Cached values are expired using a mark-then-delete strategy. In each
	// tick of expire duration, 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

	// Fetch 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.
	//
	// If RefreshInterval is provided, this option cannot be nil, or it panics.
	//
	// The provided function must return consistently typed values, or 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 it may panic since there may be many
	// goroutines access the same value concurrently.
	Fetch func(key string) (any, error)

	// ErrorCallback is an optional callback which will be called in a new
	// goroutine when error is returned by the Fetch function during refresh.
	ErrorCallback func(key string, err error)

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

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

CacheOptions .

type Group

type Group = singleflight.Group

Group is an alias name of golang.org/x/sync/singleflight.Group.

type Result

type Result = singleflight.Result

Result is an alias name of golang.org/x/sync/singleflight.Result.