cache

Documentation

Overview

Package cache implements a build artifact cache.

Index

• Constants
• Variables
• func DefaultDir() string
• func FileHash(file string) ([HashSize]byte, error)
• func SetFileHash(file string, sum [HashSize]byte)
• type ActionID
  • func Subkey(parent ActionID, desc string) ActionID
• type Cache
  • func Default() *Cache
  • func Open(dir string) (*Cache, error)
  • func (c *Cache) FuzzDir() string
  • func (c *Cache) Get(id ActionID) (Entry, error)
  • func (c *Cache) GetBytes(id ActionID) ([]byte, Entry, error)
  • func (c *Cache) GetFile(id ActionID) (file string, entry Entry, err error)
  • func (c *Cache) GetMmap(id ActionID) ([]byte, Entry, error)
  • func (c *Cache) OutputFile(out OutputID) string
  • func (c *Cache) Put(id ActionID, file io.ReadSeeker) (OutputID, int64, error)
  • func (c *Cache) PutBytes(id ActionID, data []byte) error
  • func (c *Cache) PutNoVerify(id ActionID, file io.ReadSeeker) (OutputID, int64, error)
  • func (c *Cache) Trim()
• type Entry
• type Hash
  • func NewHash(name string) *Hash
  • func (h *Hash) Sum() [HashSize]byte
  • func (h *Hash) Write(b []byte) (int, error)
• type OutputID

Constants

const HashSize = 32

HashSize is the number of bytes in a hash.

Variables

var DebugTest = false

DebugTest is set when GODEBUG=gocachetest=1 is in the environment.

Functions

func DefaultDir

func DefaultDir() string

DefaultDir returns the effective GOCACHE setting. It returns "off" if the cache is disabled.

func FileHash

func FileHash(file string) ([HashSize]byte, error)

FileHash returns the hash of the named file. It caches repeated lookups for a given file, and the cache entry for a file can be initialized using SetFileHash. The hash used by FileHash is not the same as the hash used by NewHash.

func SetFileHash

func SetFileHash(file string, sum [HashSize]byte)

SetFileHash sets the hash returned by FileHash for file.

Types

type ActionID

type ActionID [HashSize]byte

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 Subkey

func Subkey(parent ActionID, desc string) ActionID

Subkey returns an action ID corresponding to mixing a parent action ID with a string description of the subkey.

type Cache

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

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

func Default

func Default() *Cache

Default returns the default cache to use, or nil if no cache should be used.

func Open

func Open(dir string) (*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) FuzzDir

func (c *Cache) FuzzDir() string

FuzzDir returns a subdirectory within the cache for storing fuzzing data. The subdirectory may not exist.

This directory is managed by the internal/fuzz package. Files in this directory aren't removed by the 'go clean -cache' command or by Trim. They may be removed with 'go clean -fuzzcache'.

TODO(#48526): make Trim remove unused files from this directory.

func (*Cache) Get

func (c *Cache) Get(id ActionID) (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, 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 Entry, err error)

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

func (*Cache) GetMmap

func (c *Cache) GetMmap(id ActionID) ([]byte, Entry, error)

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

func (*Cache) OutputFile

func (c *Cache) OutputFile(out OutputID) string

OutputFile returns the name of the cache file storing output with the given OutputID.

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) PutBytes

func (c *Cache) PutBytes(id ActionID, data []byte) error

PutBytes stores the given bytes in the cache as the output for the action ID.

func (*Cache) PutNoVerify

func (c *Cache) PutNoVerify(id ActionID, file io.ReadSeeker) (OutputID, int64, error)

PutNoVerify is like Put but disables the verify check when GODEBUG=goverifycache=1 is set. It is meant for data that is OK to cache but that we expect to vary slightly from run to run, like test output containing times and the like.

func (*Cache) Trim

func (c *Cache) Trim()

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

type Entry

type Entry struct {
	OutputID OutputID
	Size     int64
	Time     time.Time
}

type Hash

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

A Hash provides access to the canonical hash function used to index the cache. The current implementation uses salted SHA256, but clients must not assume this.

func NewHash

func NewHash(name string) *Hash

NewHash returns a new Hash. The caller is expected to Write data to it and then call Sum.

func (*Hash) Sum

func (h *Hash) Sum() [HashSize]byte

Sum returns the hash of the data written previously.

func (*Hash) Write

func (h *Hash) Write(b []byte) (int, error)

Write writes data to the running hash.

type OutputID

type OutputID [HashSize]byte

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