Documentation
¶
Overview ¶
Package file implements a bounded persistent cache under an owned os.Root. Atomic operations serialize across local processes per key shard; network filesystems are unsupported. Tags, batch deletion and distributed fill leases are not supplied. Store.Invalidate physically removes a namespace's records.
Index ¶
- Constants
- type Backend
- func (b *Backend) Access(ctx context.Context, key cache.EntryKey, mode cacheatomic.Mode, ...) error
- func (b *Backend) Close(ctx context.Context) error
- func (b *Backend) Done() <-chan struct{}
- func (b *Backend) FlushNamespace(ctx context.Context, namespace cache.Namespace) (uint64, error)
- func (*Backend) FoundryAdapter(frameworkadapter.Seal)
- func (b *Backend) Inspect(ctx context.Context, key cache.EntryKey, inspect cacheatomic.Inspection) (bool, error)
- func (b *Backend) Prune(ctx context.Context, limit int) (int, error)
- func (b *Backend) Read(ctx context.Context, key cache.EntryKey, data bool) (*cacheatomic.Record, time.Time, error)
- func (b *Backend) Start(ctx context.Context) error
- func (b *Backend) Sweep(ctx context.Context, limit int) (PruneResult, error)
- type Config
- type PruneResult
Constants ¶
const MaxPrune = cacheatomic.MaxPrune
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Backend ¶
type Backend struct {
*cacheatomic.Backend
// contains filtered or unexported fields
}
Backend's embedded implementation supplies only the capabilities it supports. Close prevents new operations, stops the pruner and waits for active filesystem work. Filesystem syscalls cannot be interrupted, but contention observes the caller's context. Reads take no lock: records are published by atomic rename, so a reader sees either the old or the new complete record.
func Prepare ¶
Prepare validates configuration and constructs an unstarted backend without filesystem I/O.
func (*Backend) Access ¶
func (b *Backend) Access(ctx context.Context, key cache.EntryKey, mode cacheatomic.Mode, change cacheatomic.Change) error
Access runs one atomic change under the key's shard lock. A write that does not fit first reclaims expired records (at most once per second per backend) and then retries; only a cache still full of live records rejects it.
func (*Backend) Close ¶
Close stops startup and pruning, rejects new operations, and waits for admitted work before closing the root. Context cancellation ends only the wait.
func (*Backend) Done ¶
func (b *Backend) Done() <-chan struct{}
Done closes after shutdown has drained admitted work and closed the root.
func (*Backend) FlushNamespace ¶
FlushNamespace physically removes every readable record of namespace. It locks one shard at a time, so it is not a fence against concurrent writers.
func (*Backend) FoundryAdapter ¶
func (*Backend) FoundryAdapter(frameworkadapter.Seal)
FoundryAdapter marks the backend as framework-owned adapter I/O.
func (*Backend) Inspect ¶
func (b *Backend) Inspect(ctx context.Context, key cache.EntryKey, inspect cacheatomic.Inspection) (bool, error)
Inspect validates the envelope, payload size and checksum without decoding or buffering payloads. Expire streams a new atomic record under the key's shard lock. Corrupt and over-bound records are absent and are never modified.
func (*Backend) Read ¶
func (b *Backend) Read(ctx context.Context, key cache.EntryKey, data bool) (*cacheatomic.Record, time.Time, error)
Read observes one record without a lock. Corrupt and over-bound records are misses. The returned time is the configured clock after the read.
func (*Backend) Start ¶
Start opens and initializes the root, counts its records and, when PruneInterval is positive, starts the owned background pruner.
func (*Backend) Sweep ¶
Sweep deletes at most limit expired records and orphan publications, skipping (and counting) corrupt records and foreign files instead of stopping. It locks one shard at a time, never the whole root. A complete pass recounts the usage estimate. The scan is bounded by twice MaxEntries plus MaxPrune files.
type Config ¶
type Config struct {
Root string
MaxEntries int
MaxBytes int64
MaxValueBytes int
Sync bool
Clock clock.Clock
// PruneInterval runs automatic reclamation of expired records while the
// backend is started. Zero disables it; otherwise 1s to 24h.
PruneInterval time.Duration
// Logger optionally receives redacted automatic-prune failures.
Logger *slog.Logger
}
Config bounds physical record files and bytes (including record envelopes). A write never fails because of expired records: at capacity the backend first reclaims up to MaxPrune expired records, then rejects only if still full. Usage is an estimate maintained by this process and recounted by every prune pass, so processes sharing a root can briefly overshoot between passes. Roots must be existing trusted directories. Every process sharing a root must use the same bounds, synchronized clocks and the same Foundry version.
func DefaultConfig ¶
DefaultConfig returns persistent cache defaults for an existing trusted root directory.
type PruneResult ¶
type PruneResult = cacheatomic.PruneResult
PruneResult reports one bounded prune pass, including skipped corrupt records.
Source Files