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
}

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

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

type Hash interface {
	Sum64() uint64
}

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

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
}

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

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

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)
}