lease

Documentation

Overview

Package lease holds the machine's shared resources, one holder at a time: kind labs, shared installations, the browser. A lease is a directory (mkdir is atomic) holding the holder's record; the record's fields are the ones the lab's earlier shell lock wrote, so both read the same directory.

While a supervisor is recorded, a free lease is not permission: a session claims only what the supervisor granted it, in the order the grants were given, from the supervisor's start to a deliberate stop, whether its session runs or has crashed. Grants live in the state document.

Index

• func Check(st *state.State, g Gate) (int, error)
• func Pending(st *state.State, res string, held bool, now time.Time, ttl time.Duration) []state.Grant
• func Prune(st *state.State, held map[string]bool, now time.Time, ttl time.Duration)
• type Dir
  • func (d Dir) Claim(res string, h Holder) (*Holder, error)
  • func (d Dir) Get(res string) (*Holder, error)
  • func (d Dir) List() ([]Holder, error)
  • func (d Dir) Release(res string) error
• type Gate
• type Holder
  • func (h Holder) Label() string
  • func (h Holder) Party() state.Party
  • func (h Holder) SinceTime() time.Time
• type Refusal
  • func (r *Refusal) Error() string

Functions

func Check

func Check(st *state.State, g Gate) (int, error)

Check decides whether the caller may claim and, when a grant carries the claim, returns its index in st.Grants (-1 when none is needed). While an upgrade runs on the installation of the resource's name only an upgrade-unblock grant admits a claim, in grant order.

func Pending

func Pending(st *state.State, res string, held bool, now time.Time, ttl time.Duration) []state.Grant

Pending returns the grants of res still claimable, in order.

func Prune

func Prune(st *state.State, held map[string]bool, now time.Time, ttl time.Duration)

Prune drops the grants whose time ran out; held says which resources are held right now (their grants wait without expiring).

Types

type Dir

type Dir string

Dir is the lease directory.

func (Dir) Claim

func (d Dir) Claim(res string, h Holder) (*Holder, error)

Claim takes res for h. It returns the current holder instead when res is held already.

func (Dir) Get

func (d Dir) Get(res string) (*Holder, error)

Get returns the holder of res, or nil when it is free.

func (Dir) List

func (d Dir) List() ([]Holder, error)

List returns every held lease, oldest first.

func (Dir) Release

func (d Dir) Release(res string) error

Release frees res.

type Gate

type Gate struct {
	Resource string
	Caller   state.Party
	// Supervisor is the recorded supervisor, nil when none is.
	Supervisor *state.Supervisor
	// RestartUntil is set while the supervisor's CLI may still come back
	// as a restart; Gone once its CLI stayed away longer: claims wait for
	// its successor.
	RestartUntil time.Time
	Gone         bool
	// Held is whether the resource is held right now (by anyone).
	Held bool
	Now  time.Time
	TTL  time.Duration
}

Gate is what a claim is checked against.

type Holder

type Holder struct {
	// Env is the resource; the field name is the shell lock's.
	Env         string `json:"env"`
	Holder      string `json:"holder"`
	Session     string `json:"session"`
	HostSession string `json:"hostSession,omitempty"`
	Name        string `json:"name,omitempty"`
	// Person, Team and Host are the holder party's.
	Person  string `json:"person,omitempty"`
	Team    string `json:"team,omitempty"`
	Host    string `json:"host,omitempty"`
	Purpose string `json:"purpose"`
	Since   string `json:"since"`
	// UpgradeUnblock is the reason of the upgrade-unblock grant the claim
	// was admitted by during an upgrade, empty for any other claim.
	UpgradeUnblock string `json:"upgradeUnblock,omitempty"`
	// BudgetGiB is what the holder's models may hold on the model server,
	// 0 on every other resource.
	BudgetGiB int `json:"budgetGiB,omitempty"`
}

Holder is the record in <leaseDir>/<resource>/holder.json.

func (Holder) Label

func (h Holder) Label() string

Label is the resource with the budget its claim carries.

func (Holder) Party

func (h Holder) Party() state.Party

Party is the holder as the state names it.

func (Holder) SinceTime

func (h Holder) SinceTime() time.Time

SinceTime parses Since.

type Refusal

type Refusal struct {
	Reason   string
	Position int
	Ahead    string
}

Refusal is why a claim is not allowed. A claim queued behind earlier grants carries its place: Position (from 1) and Ahead, the grantee who claims first.

func (*Refusal) Error

func (r *Refusal) Error() string