loadingcache

type Cache interface {

	// Get returns the value associated with a given key. If no entry exists for
	// the provided key, loadingcache.ErrKeyNotFound is returned.
	Get(key interface{}) (interface{}, error)

	// Put adds a value to the cache identified by a key.
	// If a value already exists associated with that key, it
	// is replaced.
	Put(key interface{}, value interface{})

	// Invalidate removes keys from the cache. If a key does not exists it is a noop.
	Invalidate(key interface{}, keys ...interface{})

	// InvalidateAll invalidates all keys
	InvalidateAll()

	// Close cleans up any resources used by the cache
	Close()

	// Stats returns the curret stats
	Stats() Stats
}

type CacheOption func(Cache)

type CacheOptions struct {
	// Clock allows passing a custom clock to be used with the cache.
	//
	// This is useful for testing, where controlling time is important.
	Clock clock.Clock

	// ExpireAfterWrite configures the cache to expire entries after
	// a given duration after writing.
	ExpireAfterWrite time.Duration

	// ExpireAfterRead configures the cache to expire entries after
	// a given duration after reading.
	ExpireAfterRead time.Duration

	// Load configures a loading function
	Load LoadFunc

	// MaxSize limits the number of entries allowed in the cache.
	// If the limit is achieved, an eviction process will take place,
	// this means that eviction policies will be executed such as write
	// time, read time or random entry if no evection policy frees up
	// space.
	//
	// If the cache is sharded, MaxSize is applied to each shard,
	// meaning that the overall capacity will be MaxSize * ShardCount.
	MaxSize int32

	// RemovalListeners configures a removal listeners
	RemovalListeners []RemovalListener

	// ShardCount indicates how many shards will be used by the cache.
	// This allows some degree of parallelism in read and writing to the cache.
	//
	// If the shard count is greater than 1, then HashCodeFunc must be provided
	// otherwise the constructor will panic.
	ShardCount int

	// HashCodeFunc is a function that produces a hashcode of the key.
	//
	// See https://docs.oracle.com/en/java/javase/15/docs/api/java.base/java/lang/Object.html#hashCode()
	// for best practices surrounding hash code functions.
	HashCodeFunc func(key interface{}) int

	// BackgroundEvictFrequency controls if a background go routine should be created
	// which automatically evicts entries that have expired. If not speficied
	// no background goroutine will be created.
	//
	// The background go routine runs with the provided frequency.
	// To avoid go routine leaks, use the close function when you're done with the cache.
	BackgroundEvictFrequency time.Duration
}

type LoadFunc func(interface{}) (interface{}, error)

type RemovalListener func(RemovalNotification)

type RemovalNotification struct {
	Key    interface{}
	Value  interface{}
	Reason RemovalReason
}

type RemovalReason string

type Stats interface {
	// EvictionCount is the number of times an entry has been evicted
	EvictionCount() int64

	// HitCount the number of times Cache lookup methods have returned a cached value
	HitCount() int64

	// HitRate is the ratio of cache requests which were hits. This is defined as
	// hitCount / requestCount, or 1.0 when requestCount == 0
	HitRate() float64

	// MissCount is the number of times Cache lookup methods have returned an uncached
	// (newly loaded) value
	MissCount() int64

	// MissRate is the ratio of cache requests which were misses. This is defined as
	// missCount / requestCount, or 0.0 when requestCount == 0
	MissRate() float64

	// RequestCount is the number of times Cache lookup methods have returned either a cached or
	// uncached value. This is defined as hitCount + missCount
	RequestCount() int64

	// LoadSuccessCount is the number of times Cache lookup methods have successfully
	// loaded a new value
	LoadSuccessCount() int64

	// LoadErrorCount is the number of times Cache lookup methods threw an exception while loading
	// a new value
	LoadErrorCount() int64

	// LoadErrorRate is the ratio of cache loading attempts which threw exceptions.
	// This is defined as loadExceptionCount / (loadSuccessCount + loadExceptionCount), or 0.0 when
	// loadSuccessCount + loadExceptionCount == 0
	LoadErrorRate() float64

	// LoadCount the total number of times that Cache lookup methods attempted to load new values.
	// This includes both successful load operations, as well as those that threw exceptions.
	// This is defined as loadSuccessCount + loadExceptionCount
	LoadCount() int64

	// LoadTotalTime is the total duration the cache has spent loading new values
	LoadTotalTime() time.Duration

	// AverageLoadPenalty is the average duration spent loading new values. This is defined as
	// totalLoadTime / (loadSuccessCount + loadExceptionCount).
	AverageLoadPenalty() time.Duration
}