cache

type Cache[K KeyString, V any] interface {
	// Get returns the value for the given key and true if it is present;
	// otherwise it returns the zero value of V and false.
	Get(key K) (V, bool)

	// GetTTL returns the TTL configured for entries in this cache.
	// If zero, entries never expire. The current Otter-backed
	// implementation refreshes the TTL on access.
	GetTTL() time.Duration

	// Set attempts to store an entry for key, overwriting any existing entry,
	// and returns true if the write was accepted for processing. cost is
	// passed to the eviction policy and weighed against Config.MaxCost;
	// the Otter implementation saturates cost at math.MaxUint32.
	// A false return means the implementation did not enqueue the write
	// (as Ristretto may do under pressure); the Otter-backed implementation
	// always returns true. A true return does not guarantee retention —
	// the entry may still be dropped or evicted by the underlying
	// implementation, so writes are best-effort.
	Set(key K, entry V, cost int64) bool

	// Wait blocks until buffered Set calls have been processed by the
	// underlying implementation. Required for read-your-own-writes
	// semantics with implementations that buffer writes (e.g. Ristretto);
	// a no-op on the current Otter-backed implementation, which applies
	// writes synchronously.
	Wait()

	// Close stops the cache's background workers (if any) and tears down
	// associated metrics registration, if one was set up.
	Close()

	// GetMetrics returns the metrics block for the cache.
	// Some implementations may choose to not return some of these metrics.
	GetMetrics() Metrics

	zerolog.LogObjectMarshaler
}

type Config struct {
	// Deprecated: NumCounters was used to control behavior of the cache
	// when the underlying cache exposed it, but the current cache implementation
	// does not use it.
	NumCounters int64

	// MaxCost can be considered as the cache capacity, in whatever units you
	// choose to use.
	//
	// For example, if you want the cache to have a max capacity of 100MB, you
	// would set MaxCost to 100,000,000 and pass an item's number of bytes as
	// the `cost` parameter for calls to Set. If new items are accepted, the
	// eviction process will take care of making room for the new item and not
	// overflowing the MaxCost value.
	MaxCost int64

	// DefaultTTL configures a default deadline on the lifetime of any keys set
	// to the cache.
	DefaultTTL time.Duration
}

type KeyString interface {
	comparable
	KeyString() string
}

type Metrics interface {
	// Hits is the number of cache hits.
	Hits() uint64

	// Misses is the number of cache misses.
	Misses() uint64

	// CostAdded returns the total cost of added items.
	CostAdded() uint64

	// CostEvicted returns the total cost of evicted items.
	CostEvicted() uint64
}

type StringKey string