filecache

Documentation

Overview

The filecache package provides a file-based shared durable blob cache.

The cache is a machine-global mapping from (kind string, key [32]byte) to []byte, where kind is an identifier describing the namespace or purpose (e.g. "analysis"), and key is a SHA-256 digest of the recipe of the value. (It need not be the digest of the value itself, so you can query the cache without knowing what value the recipe would produce.)

The space budget of the cache can be controlled by SetBudget. Cache entries may be evicted at any time or in any order. Note that "du -sh $GOPLSCACHE" may report a disk usage figure that is rather larger (e.g. 50%) than the budget because it rounds up partial disk blocks.

The Get and Set operations are concurrency-safe.

Index

• Variables
• func BugReports() (string, []bug.Bug)
• func Bytes(data []byte) []byte
• func Get[T any](kind string, key [32]byte, decode func([]byte) T) (T, error)
• func GetOrFatal[T any](kind string, key [32]byte, decode func([]byte) T) (T, bool)
• func Set(kind string, key [32]byte, value []byte) error
• func SetBudget(new int64) (old int64)
• func Start()
• type ErrNoCache

Variables

var ErrNotFound = fmt.Errorf("not found")

ErrNotFound is the distinguished error returned by Get when the key is not found.

Functions

func BugReports

func BugReports() (string, []bug.Bug)

BugReports returns a new unordered array of the contents of all cached bug reports produced by this executable. It also returns the location of the cache directory used by this process (or "" on initialization error).

func Bytes

func Bytes(data []byte) []byte

Bytes is the identity decoder, for use with Get when the caller wants the raw bytes.

func Get

func Get[T any](kind string, key [32]byte, decode func([]byte) T) (T, error)

Get retrieves from the cache the value most recently supplied to Set(kind, key), possibly by another process, and passes it through decode. The decoded result is cached in memory so that repeated reads avoid both I/O and deserialization. On a memory-cache hit holding raw bytes (from a recent Set), the entry is decoded once and upgraded in place from raw bytes to the decoded value.

Get returns ErrNotFound if the value was not found.

Get returns ErrNoCache if the cache did not exist and could not be created. This may be due to ENOSPC, deletion of the process's executable, deletion or corruption of the cache by external meddling while gopls is running, or by faulty hardware (see issue #67433). In this case, terminating the application is likely the best course; see GetOrFatal.

Each kind must be used with exactly one decoded type T; mixing types for the same kind is a programming error and will panic. The returned value may be shared with other callers and must not be mutated.

func GetOrFatal

func GetOrFatal[T any](kind string, key [32]byte, decode func([]byte) T) (T, bool)

GetOrFatal retrieves from the cache like Get, but if it encounters an unrecoverable ErrNoCache error, it calls log.Fatal. Any unexpected error (not ErrNotFound) is logged.

func Set

func Set(kind string, key [32]byte, value []byte) error

Set updates the value in the cache.

Set may fail due to: - failure to access/create the cache (first call only); - out of space (ENOSPC); - deletion of the cache concurrent with a call to Set; - faulty hardware. See issue #67433.

func SetBudget

func SetBudget(new int64) (old int64)

SetBudget sets a soft limit on disk usage of regular files in the cache (in bytes) and returns the previous value. Supplying a negative value queries the current value without changing it.

If two gopls processes have different budgets, the one with the lower budget will collect garbage more actively, but both will observe the effect.

Even in the steady state, the storage usage reported by the 'du' command may exceed the budget by as much as a factor of 3 due to the overheads of directories and the effects of block quantization, which are especially pronounced for the small index files.

func Start

func Start()

Start causes the filecache to initialize and start garbage collection.

Start is automatically called by the first call to Get, but may be called explicitly to pre-initialize the cache.

Types

type ErrNoCache

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

ErrNoCache is the type of errors returned by Get when the cache cannot be created at all (e.g. due to disk space, lack of permission, deletion of the gopls executable, or hardware fault).

The appropriate action in this case is typically to log.Fatal since there is little the application can do and performance will inevitably be terrible; See GetOrFatal.