Documentation
¶
Overview ¶
Package cache provides a generic in-memory TTL cache used to avoid redundant gh/git/jj calls across TUI refreshes.
Index ¶
- Variables
- func ClearAll()
- func DiskPath(d *DiskCache, upstream string) string
- func Persist[T any](c *TTLCache[T], upstream, key string, stamp Stamp, value T)
- func PersistUsing[T any](d *DiskCache, c *TTLCache[T], upstream, key string, stamp Stamp, value T)
- func Persisted[T any](c *TTLCache[T], upstream, key string, stamp Stamp) (T, bool)
- func PersistedUsing[T any](d *DiskCache, c *TTLCache[T], upstream, key string, stamp Stamp) (T, bool)
- func RemoteScope(repoPath, remoteID string) string
- func SetAllTTLs(ttl time.Duration)
- func SetDiskCache(store *DiskCache)
- type DiskCache
- type Stamp
- type TTLCache
Constants ¶
This section is empty.
Variables ¶
var NoStamp = Stamp{} //nolint:gochecknoglobals // an empty-value constant, never assigned to
NoStamp is the stamp for a value no local state can invalidate.
Functions ¶
func ClearAll ¶
func ClearAll()
ClearAll clears every registered package-level cache, and the installed disk store with them.
func Persist ¶
Persist stores value in c and, when a store is installed, in upstream's cache file. An empty upstream is memory-only: a checkout with no resolvable remote shares its values with nobody, and a file per path is the unbounded growth the size budget exists to prevent.
func PersistUsing ¶
PersistUsing and PersistedUsing drive Persist and Persisted against an explicit store, so a test works in its own directory instead of the installed one and stays parallel-safe.
func Persisted ¶
Persisted returns the value for key, reading the upstream's cache file when the memory cache misses and seeding memory from what it finds. The file is read on the miss that needs it rather than at startup, so landing on one row costs one small read instead of one per repo on the roster.
The disk entry keeps its own expiry and the fingerprints it was written under, so reading it back neither restarts the TTL nor loses the stamp rule.
func PersistedUsing ¶
func PersistedUsing[T any](d *DiskCache, c *TTLCache[T], upstream, key string, stamp Stamp) (T, bool)
PersistedUsing drives Persisted against an explicit store, so a test works in its own directory instead of the installed one and stays parallel-safe.
func RemoteScope ¶
RemoteScope returns the key prefix for a value that belongs to the remote, so every checkout of one remote reads a single entry. A checkout with no resolvable remote falls back to its own path, since an empty identity would otherwise pool every remoteless repo into one entry.
func SetAllTTLs ¶
SetAllTTLs overrides every registered cache's entry lifetime. Intended for startup config application; existing entries keep their original expiry.
func SetDiskCache ¶
func SetDiskCache(store *DiskCache)
SetDiskCache installs the store Persist writes through and Persisted reads back. Nothing is installed until a caller opts in, so a `cache_to_disk = false` run (and every test) touches no files at all.
Types ¶
type DiskCache ¶
type DiskCache struct {
// contains filtered or unexported fields
}
DiskCache persists remote-derived cache values between runs, one file per upstream identity, so a cold start on a large fleet does not re-issue a network call per repo. It holds only counts, states, numbers, and titles (never bodies or comment text) in mode 0600 files under a 0700 directory. A corrupt, truncated, or unreadable file is dropped and refetched, never reported as an error.
func NewDiskCache ¶
NewDiskCache returns a store writing under dir, which is created on first write.
func NewSizedDiskCache ¶
NewSizedDiskCache returns a disk store with a small byte budget, so a test can overflow it without writing megabytes.
func UserDiskCache ¶
UserDiskCache returns the store under os.UserCacheDir(), which is where a cache belongs on every platform the app builds for.
type Stamp ¶
Stamp is what a checkout looked like when a value was read from it. The cache compares Fingerprint for equality and never interprets it; Scope names the checkout it came from, so an entry several checkouts of one remote share is only evicted for the checkout that actually changed. An empty Fingerprint proves nothing: it is what a caller passes for a value no local state can invalidate, and what vcs returns for a checkout it could not read.
type TTLCache ¶
type TTLCache[T any] struct { // contains filtered or unexported fields }
TTLCache is a generic in-memory cache whose entries expire after a fixed duration.
func NewRegistered ¶
NewRegistered builds a TTLCache like NewTTLCache and appends it to the package-level registry that ClearAll drains. Reserved for the package-level cache variables below; tests wanting a throwaway cache should use NewTTLCache directly so they don't accumulate in the registry.
func NewTTLCache ¶
NewTTLCache returns an empty TTLCache with the given entry lifetime.
func NewTTLCacheWithClock ¶
NewTTLCacheWithClock returns a TTLCache reading the current time from now, so a test can age an entry past its TTL without sleeping.
func (*TTLCache[T]) Fresh ¶
Fresh returns the cached value for key when stamp matches the one it was written under, for a value derived from local state alone. An unchanged checkout cannot have changed the answer, so the entry stays correct however old it is and the TTL never evicts it. A checkout that could not be stamped always misses.
func (*TTLCache[T]) Get ¶
Get returns the cached value for key, for a value the checkout cannot prove still correct. The TTL is the ceiling and stamp only lowers it: a checkout whose stamp moved since it last touched this entry evicts it early, because a local change (a push above all) is exactly when a remote-derived value stops matching. Pass NoStamp for a value no local state bears on.
Source Files