cache

Documentation

Index

• type Cache
  • func NewCache[K comparable, V any](options ...Option[K, V]) Cache[K, V]
• type Func
• type GetPreLoadDataFunc
• type Hash
• type LoaderFunc
• type LoadingCache
  • func NewLoadingCache[K comparable, V any](loader LoaderFunc[K, V], options ...Option[K, V]) LoadingCache[K, V]
• type Option
  • func WithAsyncInitPreLoader[K comparable, V any](fn GetPreLoadDataFunc[K, V]) Option[K, V]
  • func WithExpireAfterAccess[K comparable, V any](d time.Duration) Option[K, V]
  • func WithExpireAfterWrite[K comparable, V any](d time.Duration) Option[K, V]
  • func WithInsertionListener[K comparable, V any](onInsertion Func[K, V]) Option[K, V]
  • func WithMaximumSize[K comparable, V any](size int64) Option[K, V]
  • func WithPolicy[K comparable, V any](name string) Option[K, V]
  • func WithRefreshAfterWrite[K comparable, V any](d time.Duration) Option[K, V]
  • func WithRemovalListener[K comparable, V any](onRemoval Func[K, V]) Option[K, V]
  • func WithStatsCounter[K comparable, V any](st StatsCounter) Option[K, V]
• type Stats
  • func (s *Stats) AverageLoadPenalty() time.Duration
  • func (s *Stats) HitRate() float64
  • func (s *Stats) LoadErrorRate() float64
  • func (s *Stats) MissRate() float64
  • func (s *Stats) RequestCount() uint64
  • func (s *Stats) String() string
• type StatsCounter

Types

type Cache

type Cache[K comparable, V any] interface {
	// GetIfPresent returns value associated with Key or (nil, false)
	// if there is no cached value for Key.
	GetIfPresent(K) (V, bool)

	// Put associates value with Key. If a value is already associated
	// with Key, the old one will be replaced with Value.
	Put(K, V)

	// Invalidate discards cached value of the given Key.
	Invalidate(K)

	// InvalidateAll discards all entries.
	InvalidateAll()

	// Scan walk cache and apply a filter func to each element
	Scan(func(K, V) bool) map[K]V

	// Stats returns cache statistics.
	Stats() *Stats

	// Close implements io.Closer for cleaning up all resources.
	// Users must ensure the cache is not being used before closing or
	// after closed.
	Close() error
}

Cache is a key-value cache which entries are added and stayed in the cache until either are evicted or manually invalidated. TODO: support async clean up expired data

func NewCache

func NewCache[K comparable, V any](options ...Option[K, V]) Cache[K, V]

NewCache returns a local in-memory Cache.

type Func

type Func[K comparable, V any] func(K, V)

Func is a generic callback for entry events in the cache.

type GetPreLoadDataFunc

type GetPreLoadDataFunc[K comparable, V any] func() (map[K]V, error)

type Hash

type Hash interface {
	Sum64() uint64
}

Hash is an interface implemented by cache keys to override default hash function.

type LoaderFunc

type LoaderFunc[K comparable, V any] func(K) (V, error)

LoaderFunc retrieves the value corresponding to given Key.

type LoadingCache

type LoadingCache[K comparable, V any] interface {
	Cache[K, V]

	// Get returns value associated with Key or call underlying LoaderFunc
	// to load value if it is not present.
	Get(K) (V, error)

	// Refresh loads new value for Key. If the Key already existed, it will
	// sync refresh it. or this function will block until the value is loaded.
	Refresh(K) error
}

LoadingCache is a cache with values are loaded automatically and stored in the cache until either evicted or manually invalidated.

func NewLoadingCache

func NewLoadingCache[K comparable, V any](loader LoaderFunc[K, V], options ...Option[K, V]) LoadingCache[K, V]

NewLoadingCache returns a new LoadingCache with given loader function and cache options.

type Option

type Option[K comparable, V any] func(c *localCache[K, V])

Option add options for default Cache.

func WithAsyncInitPreLoader

func WithAsyncInitPreLoader[K comparable, V any](fn GetPreLoadDataFunc[K, V]) Option[K, V]

WithAsyncInitPreLoader return an option which to async loading data during initialization.

func WithExpireAfterAccess

func WithExpireAfterAccess[K comparable, V any](d time.Duration) Option[K, V]

WithExpireAfterAccess returns an option to expire a cache entry after the given duration without being accessed.

func WithExpireAfterWrite

func WithExpireAfterWrite[K comparable, V any](d time.Duration) Option[K, V]

WithExpireAfterWrite returns an option to expire a cache entry after the given duration from creation.

func WithInsertionListener

func WithInsertionListener[K comparable, V any](onInsertion Func[K, V]) Option[K, V]

func WithMaximumSize

func WithMaximumSize[K comparable, V any](size int64) Option[K, V]

WithMaximumSize returns an Option which sets maximum size for the cache. Any non-positive numbers is considered as unlimited.

func WithPolicy

func WithPolicy[K comparable, V any](name string) Option[K, V]

WithPolicy returns an option which sets cache policy associated to the given name. Supported policies are: lru, slru.

func WithRefreshAfterWrite

func WithRefreshAfterWrite[K comparable, V any](d time.Duration) Option[K, V]

WithRefreshAfterWrite returns an option to refresh a cache entry after the given duration. This option is only applicable for LoadingCache.

func WithRemovalListener

func WithRemovalListener[K comparable, V any](onRemoval Func[K, V]) Option[K, V]

WithRemovalListener returns an Option to set cache to call onRemoval for each entry evicted from the cache.

func WithStatsCounter

func WithStatsCounter[K comparable, V any](st StatsCounter) Option[K, V]

WithStatsCounter returns an option which overrides default cache stats counter.

type Stats

type Stats struct {
	HitCount         uint64
	MissCount        uint64
	LoadSuccessCount uint64
	LoadErrorCount   uint64
	TotalLoadTime    time.Duration
	EvictionCount    uint64
}

Stats is statistics about performance of a cache.

func (*Stats) AverageLoadPenalty

func (s *Stats) AverageLoadPenalty() time.Duration

AverageLoadPenalty returns the average time spent loading new values.

func (*Stats) HitRate

func (s *Stats) HitRate() float64

HitRate returns the ratio of cache requests which were hits.

func (*Stats) LoadErrorRate

func (s *Stats) LoadErrorRate() float64

LoadErrorRate returns the ratio of cache loading attempts which returned errors.

func (*Stats) MissRate

func (s *Stats) MissRate() float64

MissRate returns the ratio of cache requests which were misses.

func (*Stats) RequestCount

func (s *Stats) RequestCount() uint64

RequestCount returns a total of HitCount and MissCount.

func (*Stats) String

func (s *Stats) String() string

String returns a string representation of this statistics.

type StatsCounter

type StatsCounter interface {
	// RecordHits records cache hits.
	RecordHits(count uint64)

	// RecordMisses records cache misses.
	RecordMisses(count uint64)

	// RecordLoadSuccess records successful load of a new entry.
	RecordLoadSuccess(loadTime time.Duration)

	// RecordLoadError records failed load of a new entry.
	RecordLoadError(loadTime time.Duration)

	// RecordEviction records eviction of an entry from the cache.
	RecordEviction()

	// Snapshot writes snapshot of this counter values to the given Stats pointer.
	Snapshot(*Stats)
}

StatsCounter accumulates statistics of a cache.