cache

Documentation

Index

• Variables
• func PrometheusCacheMonitor[K comparable, V any](c Cache[K, V], namespace, subsystem string)
• type Cache
• type CacheBuilder
  • func NewCacheBuilder[K comparable, V any]() *CacheBuilder[K, V]
  • func (b *CacheBuilder[K, V]) Build() Cache[K, V]
  • func (b *CacheBuilder[K, V]) WithCapacity(capacity int64) *CacheBuilder[K, V]
  • func (b *CacheBuilder[K, V]) WithFinalizer(finalizer Finalizer[K, V]) *CacheBuilder[K, V]
  • func (b *CacheBuilder[K, V]) WithLazyScavenger(weight func(K) int64, capacity int64) *CacheBuilder[K, V]
  • func (b *CacheBuilder[K, V]) WithLoader(loader Loader[K, V]) *CacheBuilder[K, V]
  • func (b *CacheBuilder[K, V]) WithReloader(reloader Loader[K, V]) *CacheBuilder[K, V]
• type Finalizer
• type LazyScavenger
  • func NewLazyScavenger[K comparable](weight func(K) int64, capacity int64) *LazyScavenger[K]
  • func (s *LazyScavenger[K]) Collect(key K) (bool, func(K) bool)
  • func (s *LazyScavenger[K]) Replace(key K) (bool, func(K) bool, func())
  • func (s *LazyScavenger[K]) Spare(key K) func(K) bool
  • func (s *LazyScavenger[K]) Throw(key K)
• type Loader
• type Scavenger
• type Stats

Variables

var (
	ErrNoSuchItem     = merr.WrapErrServiceInternal("no such item")
	ErrNotEnoughSpace = merr.WrapErrServiceInternal("not enough space")
)

Functions

func PrometheusCacheMonitor

func PrometheusCacheMonitor[K comparable, V any](c Cache[K, V], namespace, subsystem string)

WIP: this function is a showcase of how to use prometheus, do not use it in production.

Types

type Cache

type Cache[K comparable, V any] interface {
	// Do the operation `doer` on the given key `key`. The key is kept in the cache until the operation
	// completes.
	// Throws `ErrNoSuchItem` if the key is not found or not able to be loaded from given loader.
	Do(ctx context.Context, key K, doer func(context.Context, V) error) (missing bool, err error)

	// Get stats
	Stats() *Stats

	MarkItemNeedReload(ctx context.Context, key K) bool

	// Remove removes the item from the cache.
	// Return nil if the item is removed.
	// Return error if the Remove operation is canceled.
	Remove(ctx context.Context, key K) error
}

type CacheBuilder

type CacheBuilder[K comparable, V any] struct {
	// contains filtered or unexported fields
}

func NewCacheBuilder

func NewCacheBuilder[K comparable, V any]() *CacheBuilder[K, V]

func (*CacheBuilder[K, V]) Build

func (b *CacheBuilder[K, V]) Build() Cache[K, V]

func (*CacheBuilder[K, V]) WithCapacity

func (b *CacheBuilder[K, V]) WithCapacity(capacity int64) *CacheBuilder[K, V]

func (*CacheBuilder[K, V]) WithFinalizer

func (b *CacheBuilder[K, V]) WithFinalizer(finalizer Finalizer[K, V]) *CacheBuilder[K, V]

func (*CacheBuilder[K, V]) WithLazyScavenger

func (b *CacheBuilder[K, V]) WithLazyScavenger(weight func(K) int64, capacity int64) *CacheBuilder[K, V]

func (*CacheBuilder[K, V]) WithLoader

func (b *CacheBuilder[K, V]) WithLoader(loader Loader[K, V]) *CacheBuilder[K, V]

func (*CacheBuilder[K, V]) WithReloader

func (b *CacheBuilder[K, V]) WithReloader(reloader Loader[K, V]) *CacheBuilder[K, V]

type Finalizer

type Finalizer[K comparable, V any] func(ctx context.Context, key K, value V) error

type LazyScavenger

type LazyScavenger[K comparable] struct {
	// contains filtered or unexported fields
}

func NewLazyScavenger

func NewLazyScavenger[K comparable](weight func(K) int64, capacity int64) *LazyScavenger[K]

func (*LazyScavenger[K]) Collect

func (s *LazyScavenger[K]) Collect(key K) (bool, func(K) bool)

func (*LazyScavenger[K]) Replace

func (s *LazyScavenger[K]) Replace(key K) (bool, func(K) bool, func())

func (*LazyScavenger[K]) Spare

func (s *LazyScavenger[K]) Spare(key K) func(K) bool

func (*LazyScavenger[K]) Throw

func (s *LazyScavenger[K]) Throw(key K)

type Loader

type Loader[K comparable, V any] func(ctx context.Context, key K) (V, error)

type Scavenger

type Scavenger[K comparable] interface {
	// Collect records entry additions, if there is room, return true, or else return false and a collector.
	//	The collector is a function which can be invoked repetedly, each invocation will test if there is enough
	//	room provided that all entries in the collector is evicted. Typically, the collector will get multiple false
	//	before it gets a true.
	Collect(key K) (bool, func(K) bool)
	// Throw records entry removals.
	Throw(key K)
	// Spare returns a collector function based on given key.
	//	The collector is a function which can be invoked repetedly, each invocation will test if there is enough
	//	room for all the pending entries if the thrown entry is evicted. Typically, the collector will get multiple true
	//	before it gets a false.
	Spare(key K) func(K) bool
	Replace(key K) (bool, func(K) bool, func())
}

Scavenger records occupation of cache and decide whether to evict if necessary.

The scavenger makes decision based on keys only, and it is called before value loading,
because value loading could be very expensive.

type Stats

type Stats struct {
	HitCount            atomic.Uint64
	MissCount           atomic.Uint64
	LoadSuccessCount    atomic.Uint64
	LoadFailCount       atomic.Uint64
	TotalLoadTimeMs     atomic.Uint64
	TotalFinalizeTimeMs atomic.Uint64
	EvictionCount       atomic.Uint64
}