ocache

type LoadFunc func(ctx context.Context, id string) (value Object, err error)

type OCache interface {
	// DoLockedIfNotExists does an action if the object with id is not in cache
	// under a global lock, this will prevent a race which otherwise occurs
	// when object is created in parallel with action
	DoLockedIfNotExists(id string, action func() error) error
	// Get gets an object from cache or creates a new one via 'loadFunc';
	// it also refreshes the object's GC deadline.
	// When 'loadFunc' returns a non-nil error, an object will not be stored to cache.
	// A load that completed by the time ctx is done still returns its value.
	// Returns ErrClosed on a closed cache, including for waiters whose load
	// lands after Close.
	Get(ctx context.Context, id string) (value Object, err error)
	// Pick returns value if it's present in cache (will not call loadFunc,
	// does not refresh the GC deadline) — but it waits out an in-flight load
	// for the id, bounded by ctx. Returns ErrClosed on a closed cache.
	Pick(ctx context.Context, id string) (value Object, err error)
	// Add adds new object to cache
	// Returns error when the value is nil, the object exists or the cache is closed
	Add(id string, value Object) (err error)
	// Remove closes and removes object
	Remove(ctx context.Context, id string) (ok bool, err error)
	// RemoveSame closes and removes the object only if the value currently
	// stored under id is exactly the given one (pointer identity). It lets a
	// caller evict a specific instance it owns without racing a newer value
	// that has replaced it under the same id. A value that is not comparable
	// has no identity and is never matched (store such values behind a
	// pointer). Returns ok=true only when this call performed the removal.
	RemoveSame(ctx context.Context, id string, value Object) (ok bool, err error)
	// TryRemove tries to close and to remove the object. ok reports whether
	// this call removed it; (false, nil) means the object declined to close,
	// is still loading, or another closer owns it. A non-nil err can
	// accompany ok=true when the value closed with an error.
	TryRemove(id string) (ok bool, err error)
	// ForEach iterates over all loaded objects, breaks when callback returns false
	ForEach(f func(v Object) (isContinue bool))
	// GC frees not used and expired objects
	// Will automatically called every 'gcPeriod'
	GC()
	// Len returns current cache size
	Len() int
	// Close closes all objects and the cache. The pass is bounded by a close
	// timeout; an entry held past it by an in-flight load or a busy closer is
	// not waited for — its value is closed by that path's own closed-cache
	// branch when it completes.
	Close() (err error)
}

type Object interface {
	Close() (err error)
	TryClose(objectTTL time.Duration) (res bool, err error)
}

type Option func(*oCache)

type PeekState int

type Peeker interface {
	// Peek returns the value for id only if it is loaded and not being
	// closed, without loading, waiting or allocating: the hot path for
	// callers that handle a miss themselves. With touch a hit refreshes the
	// GC deadline like Get. The state tells a miss from an entry that is
	// loading or closing (a caller that must not act on a false miss waits
	// for the latter, see WaitClosing). Peek counts no metrics: the caller,
	// which decides whether the result is used, accounts for it.
	Peek(id string, touch bool) (value Object, state PeekState)
	// WaitClosing blocks while the entry for id is being closed, bounded by
	// ctx, and returns at once when there is no such entry or it is not
	// closing. It is the wait a caller needs before it can add a replacement
	// for a value whose removal is still running.
	WaitClosing(ctx context.Context, id string) error
}

type PrometheusCollectors struct {
	Hit, Miss, GC prometheus.Counter
	Size          prometheus.GaugeFunc
}