Documentation
¶
Overview ¶
Package cache provides generic file-based caching with platform-appropriate locking.
Index ¶
- Constants
- type FileCache
- func (c *FileCache) BaseDir() string
- func (c *FileCache) Clear() error
- func (c *FileCache) Delete(key string) error
- func (c *FileCache) Get(key string) ([]byte, bool, error)
- func (c *FileCache) GetOrFetch(key string, fetch func() ([]byte, error)) ([]byte, error)
- func (c *FileCache) GetPath(key string) (string, bool)
- func (c *FileCache) Set(key string, content []byte) error
- type FileCacheOption
- type FileLock
Constants ¶
const ( // DefaultCacheDirPerm is the default permission for cache directories. DefaultCacheDirPerm = 0o755 // DefaultFilePerm is the default permission for cache files. DefaultFilePerm = 0o644 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type FileCache ¶
type FileCache struct {
// contains filtered or unexported fields
}
FileCache provides atomic file-based caching with cross-process locking. It stores cached content in an XDG-compliant cache directory.
func NewFileCache ¶
func NewFileCache(subpath string, opts ...FileCacheOption) (*FileCache, error)
NewFileCache creates a new FileCache in the specified XDG cache subdirectory. The subpath is relative to the XDG cache directory (e.g., "stack-imports" creates ~/.cache/atmos/stack-imports/).
func (*FileCache) Delete ¶ added in v1.225.0
Delete removes a cached entry. A missing entry is treated as already deleted. Like Get and Set, deletion is serialized across Atmos processes.
func (*FileCache) Get ¶
Get returns the cached content for a key. Returns (content, true, nil) if found, (nil, false, nil) if not found, or (nil, false, error) on read error.
func (*FileCache) GetOrFetch ¶
GetOrFetch returns cached content for a key, or calls fetch() and caches the result. This provides a convenient way to implement cache-aside patterns.
type FileCacheOption ¶
type FileCacheOption func(*FileCache)
FileCacheOption is a functional option for configuring FileCache.
func WithBaseDir ¶
func WithBaseDir(dir string) FileCacheOption
WithBaseDir sets a custom base directory for the cache. This is primarily useful for testing.
func WithFileSystem ¶
func WithFileSystem(fs filesystem.FileSystem) FileCacheOption
WithFileSystem sets a custom filesystem implementation. This is primarily useful for testing.
type FileLock ¶
type FileLock interface {
// WithLock executes fn while holding an exclusive lock where supported.
// Windows cache operations execute best-effort without native file locking.
WithLock(fn func() error) error
// WithLockContext executes fn while holding an exclusive lock, blocking until
// the lock is acquired or ctx is done. Unlike WithLock's bounded retry, it
// waits the full duration of whatever the holder is doing (e.g. a multi-second
// download), making it suitable for collapsing a herd around a slow operation.
// Windows cache operations execute best-effort without native file locking.
WithLockContext(ctx context.Context, fn func() error) error
// WithRLock executes fn while holding a shared read lock where supported.
// Windows cache reads execute best-effort without native file locking.
WithRLock(fn func() error) error
// TryWithRLock executes fn while holding a shared read lock when it can be
// acquired quickly. It returns false, nil when another process holds an
// exclusive lock. On Windows, it executes without locking and returns true.
TryWithRLock(fn func() error) (acquired bool, err error)
}
FileLock provides file-level locking for cache operations.
func NewFileLock ¶
NewFileLock preserves the cache package API while using a stable sibling lock file that survives atomic cache-file replacement.
func NewFileLockAtPath ¶ added in v1.225.0
NewFileLockAtPath creates a FileLock that uses lockPath directly. Use this when compatibility requires a lock name other than targetPath + ".lock".
Source Files