filecache

README

filecache caches build artifacts in files

It is a copy of the Go internal cmd/go/internal/cache which is used for go build caching.

The default setup from the environment (GOCACHE) has been removed, but the trimming defaults (1 hour mtime resolution, evict files older than 5 days) has been kept. It is also possible to override these with TrimWithLimits.

Documentation

Index

• Constants
• func WithLogger(lgr *slog.Logger) cacheOption
• func WithMaxSize(n int64) cacheOption
• func WithNow(f func() time.Time) cacheOption
• func WithTrimInterval(d time.Duration) cacheOption
• func WithTrimLimit(d time.Duration) cacheOption
• func WithTrimSize(n int64) cacheOption
• type ActionID
  • func NewActionID(p []byte) ActionID
• type Cache
  • func Open(dir string, options ...cacheOption) (*Cache, error)
  • func (C *Cache) Get(id ActionID) (cache.Entry, error)
  • func (C *Cache) GetBytes(id ActionID) ([]byte, cache.Entry, error)
  • func (C *Cache) GetFile(id ActionID) (file string, entry cache.Entry, err error)
  • func (C *Cache) Put(id ActionID, file io.ReadSeeker) (OutputID, int64, error)
  • func (C *Cache) Trim() error
• type Hash
  • func NewHash() Hash
  • func (h Hash) SumID() ID
• type ID
  • func SumID(p []byte) ID
• type OutputID

Constants

const (
	DefaultMaxSize      = 0
	DefaultTrimInterval = 5 * time.Minute
	DefaultTrimLimit    = 24 * time.Hour
	DefaultTrimSize     = 100 << 20
)

const HashSize = sha256.Size

Functions

func WithLogger

func WithLogger(lgr *slog.Logger) cacheOption

WithLogger sets the logger to the given Logger - iff it is not nil.

func WithMaxSize

func WithMaxSize(n int64) cacheOption

func WithNow

func WithNow(f func() time.Time) cacheOption

func WithTrimInterval

func WithTrimInterval(d time.Duration) cacheOption

func WithTrimLimit

func WithTrimLimit(d time.Duration) cacheOption

func WithTrimSize

func WithTrimSize(n int64) cacheOption

Types

type ActionID

type ActionID = cache.ActionID

An ActionID is a cache action key, the hash of a complete description of a repeatable computation (command line, environment variables, input file contents, executable contents).

func NewActionID

func NewActionID(p []byte) ActionID

type Cache

type Cache struct {
	// contains filtered or unexported fields
}

A Cache is a package cache, backed by a file system directory tree.

func Open

func Open(dir string, options ...cacheOption) (*Cache, error)

Open opens and returns the cache in the given directory.

It is safe for multiple processes on a single machine to use the same cache directory in a local file system simultaneously. They will coordinate using operating system file locks and may duplicate effort but will not corrupt the cache.

However, it is NOT safe for multiple processes on different machines to share a cache directory (for example, if the directory were stored in a network file system). File locking is notoriously unreliable in network file systems and may not suffice to protect the cache.

func (*Cache) Get

func (C *Cache) Get(id ActionID) (cache.Entry, error)

Get looks up the action ID in the cache, returning the corresponding output ID and file size, if any. Note that finding an output ID does not guarantee that the saved file for that output ID is still available.

func (*Cache) GetBytes

func (C *Cache) GetBytes(id ActionID) ([]byte, cache.Entry, error)

GetBytes looks up the action ID in the cache and returns the corresponding output bytes. GetBytes should only be used for data that can be expected to fit in memory.

func (*Cache) GetFile

func (C *Cache) GetFile(id ActionID) (file string, entry cache.Entry, err error)

GetFile looks up the action ID in the cache and returns the name of the corresponding data file.

func (*Cache) Put

func (C *Cache) Put(id ActionID, file io.ReadSeeker) (OutputID, int64, error)

Put stores the given output in the cache as the output for the action ID. It may read file twice. The content of file must not change between the two passes.

func (*Cache) Trim

func (C *Cache) Trim() error

Trim removes old cache entries that are likely not to be reused.

type Hash

type Hash struct {
	hash.Hash
}

func NewHash

func NewHash() Hash

func (Hash) SumID

func (h Hash) SumID() ID

type ID

type ID [HashSize]byte

func SumID

func SumID(p []byte) ID

type OutputID

type OutputID = cache.OutputID

An OutputID is a cache output key, the hash of an output of a computation.