cache

Documentation

Overview

Package cache stores debuginfod-fetched artifacts on disk under a .build-id/<NN>/<rest>{.debug,} layout that blazesym's debug_dirs walker recognizes natively.

Index

• Variables
• type Cache
  • func (c *Cache) AbsPath(buildID string, kind Kind) string
  • func (c *Cache) Close() error
  • func (c *Cache) Evict() error
  • func (c *Cache) Has(buildID string, kind Kind) bool
  • func (c *Cache) Prewarm() error
  • func (c *Cache) WriteAtomic(buildID string, kind Kind, body io.Reader) (_ string, err error)
• type Entry
• type Index
  • func NewSQLiteIndex(dbPath string) (Index, error)
• type Kind

Variables

var ErrNoIndex = errors.New("cache: no index configured")

ErrNoIndex is returned when an operation requires a configured Index.

Types

type Cache

type Cache struct {
	Dir      string
	Index    Index
	MaxBytes int64 // 0 means unbounded
}

Cache wraps a directory containing the .build-id index.

func (*Cache) AbsPath

func (c *Cache) AbsPath(buildID string, kind Kind) string

AbsPath returns the absolute path within Dir for (buildID, kind). Returns "" when buildID is invalid (too short).

func (*Cache) Close

func (c *Cache) Close() error

Close closes the index. No-op when Index is nil.

func (*Cache) Evict

func (c *Cache) Evict() error

Evict deletes LRU entries until total cache size ≤ MaxBytes. Safe to call at any time. No-op when Index is nil or MaxBytes ≤ 0.

func (*Cache) Has

func (c *Cache) Has(buildID string, kind Kind) bool

Has reports whether the artifact is on disk.

func (*Cache) Prewarm

func (c *Cache) Prewarm() error

Prewarm walks Dir and records each existing artifact in the Index. Recovers from index loss (e.g., crash) and lets a fresh process inherit a populated cache from a previous run.

func (*Cache) WriteAtomic

func (c *Cache) WriteAtomic(buildID string, kind Kind, body io.Reader) (_ string, err error)

WriteAtomic streams body to a tmp file in the same directory as the final destination, then renames into place. Returns the absolute final path on success. On any error the tmp file is removed before returning.

type Entry

type Entry struct {
	BuildID    string
	Kind       Kind
	Size       int64
	LastAccess time.Time
}

Entry describes a cached artifact.

type Index

type Index interface {
	// Touch records (or refreshes) an entry. Called on every cache write
	// and on every cache hit (so LastAccess reflects actual use).
	Touch(buildID string, kind Kind, size int64) error

	// TotalBytes returns the sum of recorded entry sizes.
	TotalBytes() (int64, error)

	// EvictTo deletes the LRU-oldest entries until TotalBytes ≤ maxBytes.
	// Returns the entries that were evicted (caller is responsible for
	// removing the corresponding files).
	EvictTo(maxBytes int64) ([]Entry, error)

	// Iter visits every entry. The callback returns false to stop early.
	// Used at startup to re-populate from disk.
	Iter(yield func(Entry) bool) error

	// Forget removes a single entry's row (used during file deletion).
	Forget(buildID string, kind Kind) error

	Close() error
}

Index tracks cache entries for LRU eviction. Implementations must be safe for concurrent use by the cache.

func NewSQLiteIndex

func NewSQLiteIndex(dbPath string) (Index, error)

NewSQLiteIndex opens or creates a SQLite database at dbPath.

type Kind

type Kind int

Kind selects the artifact flavor. KindDebuginfo files are placed where blazesym's debug-link / build-id resolver finds them automatically. KindExecutable files are returned by the dispatcher to blazesym.

const (
	KindDebuginfo Kind = iota
	KindExecutable
)