Documentation
¶
Overview ¶
Package cachevolumedir keeps cache volumes as plain directories under one directory, apart from the engine's snapshots, so that the directory can be handed from one engine to the next.
One engine owns the directory at a time. Every volume is named by a digest of its identity and carries its own metadata, so an engine that receives the directory from another can use it with no database.
Layout, for format 1:
<dir>/owner.lock flock held by the owning process
<dir>/v1/volumes/<id>/ one volume
meta.json identity and bookkeeping (temp file + rename)
dirty present while the stored size may be stale
fs/ the volume's contents
<dir>/v1/tmp/ volumes being created
<dir>/v1/trash/ volumes being removed
The store reads and writes only its own format's subdirectory, and leaves anything else under <dir> alone.
Every change a crash could interrupt is a rename or a temp-file-and-rename, so the directory is consistent at any point a process stops.
Index ¶
- Constants
- Variables
- type Entry
- type Identity
- type Options
- type Pin
- type Policy
- type Report
- type Store
- func (s *Store) Acquire(ctx context.Context, ident Identity, writable bool, ...) (*Pin, error)
- func (s *Store) Close() error
- func (s *Store) Closed() bool
- func (s *Store) Collect(ctx context.Context, policy Policy) (Report, error)
- func (s *Store) Dir() string
- func (s *Store) PinnedPath(ident Identity) (string, error)
- func (s *Store) Usage(ctx context.Context) ([]Entry, int64, error)
- func (s *Store) WaitRemovals(ctx context.Context) error
Constants ¶
const FormatVersion = 1
FormatVersion is the on-disk format this package writes, as v<N>/ under the directory.
Variables ¶
var ErrClosed = errors.New("cache volume directory is closed")
ErrClosed is returned by Acquire once the store is closed.
var ErrOwned = errors.New("cache volume directory is owned by another process")
ErrOwned is returned by Open when another process owns the directory.
var ErrPinned = errors.New("cache volumes are still in use")
ErrPinned is returned by Close when volumes are still pinned.
Functions ¶
This section is empty.
Types ¶
type Entry ¶
type Entry struct {
ID string
Identity Identity
SizeBytes int64
CreatedAt time.Time
LastUsedAt time.Time
Pinned bool
// contains filtered or unexported fields
}
Entry describes one volume in the directory.
type Identity ¶
type Identity struct {
Namespace string `json:"namespace,omitempty"`
Key string `json:"key"`
Sharing string `json:"sharing,omitempty"`
Owner string `json:"owner,omitempty"`
// Source is the recipe digest of the volume's source directory, or empty.
// The recipe includes which subdirectory of its parent the source is, so
// the identity needs no separate selector.
Source string `json:"source,omitempty"`
}
Identity is what names a cache volume. Two calls with equal identities use the same directory, in any engine.
type Options ¶
type Options struct {
// EngineVersion is recorded in the metadata of volumes this store creates.
EngineVersion string
// Now is the clock; time.Now when nil.
Now func() time.Time
}
Options configures a Store.
type Pin ¶
type Pin struct {
// contains filtered or unexported fields
}
Pin keeps a volume from being collected until it is released.
func (*Pin) FirstPin ¶
FirstPin reports whether this is the store's first pin on the volume since it took the directory, or since it last removed the volume.
type Policy ¶
type Policy struct {
ReservedSpace int64
MaxUsedSpace int64
MinFreeSpace int64
// CurrentFreeSpace is the filesystem's free bytes, for MinFreeSpace.
CurrentFreeSpace int64
// All removes every volume that isn't pinned, whatever the thresholds.
All bool
}
Policy decides what Collect removes. Byte values are resolved; zero means unset. Thresholds work as in the engine's other cache policies.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is an owned cache volume directory.
func Open ¶
Open takes ownership of dir, creating it and its layout if needed, and removes what a previous owner left in tmp/ and trash/. It returns ErrOwned if another process owns dir.
func (*Store) Acquire ¶
func (s *Store) Acquire(ctx context.Context, ident Identity, writable bool, populate func(ctx context.Context, fsDir string) error) (*Pin, error)
Acquire pins the volume, creating it first if it doesn't exist: populate fills the new volume's contents directory, which exists and is empty when it is called. Creation of one volume is serialized; a failed populate leaves no volume behind. A writable pin marks the volume's stored size stale until a measurement taken with no writer finds it again.
func (*Store) Close ¶
Close gives up ownership. If volumes are still pinned, or acquisitions are still in progress, it keeps ownership and returns ErrPinned: another owner could otherwise collect a volume that is still in use, or sweep one being created. The ownership lock then lasts until the process exits. Once closed, Acquire fails with ErrClosed. Removals in progress keep running until they finish.
func (*Store) Closed ¶
Closed reports whether the store has given up ownership. A nil store is closed.
func (*Store) Collect ¶
Collect removes volumes until the policy is met, the least recently used first, never a pinned one. Bytes already being removed count as freed. Removed volumes are moved aside at once and deleted in the background. Collect stops between volumes when ctx ends, leaving the directory consistent.
func (*Store) PinnedPath ¶
PinnedPath is the contents directory of a volume this process has pinned. Mounting it is safe while the pin is held; it is an error to ask for a volume that isn't pinned, since nothing then keeps it from being removed.
Source Files