Documentation
¶
Overview ¶
Package runqueue coordinates CPU-heavy commands across WB processes.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Announcement ¶ added in v0.120.0
type Announcement struct {
// contains filtered or unexported fields
}
Announcement is the live handle returned by Lease.Announce. Heartbeat keeps the holder records fresh while the lease is held — call it from the same ~10s loop `wb run` already runs while a command executes, mirroring how a waiting Ticket is refreshed — so readHolders does not age the slots out as stale while the holder is legitimately still running. Cleanup removes the holder records once the lease is released; callers should defer it alongside Lease.Release. Both methods are safe to call on a nil Announcement (e.g. the zero-unit case where Announce never wrote anything).
func (*Announcement) Cleanup ¶ added in v0.120.0
func (announcement *Announcement) Cleanup()
Cleanup removes this announcement's holder records. Safe to call more than once and on a nil Announcement.
func (*Announcement) Heartbeat ¶ added in v0.120.0
func (announcement *Announcement) Heartbeat()
Heartbeat refreshes every announced holder record's UpdatedAt so readHolders keeps treating this lease as live. Best-effort, like Announce: a failed refresh just risks the holder aging past staleAfter and being reaped as if the process had died, which only affects visibility.
type Holder ¶ added in v0.120.0
type Holder struct {
Participant
StartedAt time.Time `json:"started_at"`
UpdatedAt time.Time `json:"updated_at"`
}
Holder is a Participant currently holding one or more CPU lease slots.
type Lease ¶
type Lease struct {
// contains filtered or unexported fields
}
Lease holds units machine-wide until Release. Slot files live below the projects root so harnesses already permitted to write repositories can join the same budget without requiring access to the user's home directory.
func Acquire ¶
func Acquire(ctx context.Context, projectsRoot string, units, budget int) (*Lease, time.Duration, error)
Acquire waits for units from one projects-root budget. Each attempt either acquires every requested slot or releases all partial locks before waiting, preventing two multi-unit commands from deadlocking one another.
func (*Lease) Announce ¶ added in v0.120.0
func (lease *Lease) Announce(self Participant) *Announcement
Announce records this Lease's slots as held by self, for State/Snapshot and `wb run --queue` visibility. Best-effort: a failure to write a holder file just means that slot stays anonymous in State (readHolders skips slots with no holder file), never a hard error.
type Participant ¶ added in v0.120.0
type Participant struct {
PID int `json:"pid"`
Summary string `json:"summary"`
Worktree string `json:"worktree,omitempty"`
}
Participant identifies who is waiting for or holding a CPU lease slot, for human-readable queue visibility (`wb run`'s queued/heartbeat/admitted lines and `wb run --queue`). Summary is a short, already-public label (the program name and its verb, e.g. "go test") — never full command arguments, paths, or flags — matching runlog's privacy-safe-telemetry contract even though these records are transient rather than durable.
type QueueEntry ¶ added in v0.120.0
type QueueEntry struct {
PID int `json:"pid"`
Summary string `json:"summary"`
Worktree string `json:"worktree,omitempty"`
Age time.Duration `json:"age_ns"`
}
QueueEntry is one running or waiting governed command, for `wb run --queue`.
type QueueListing ¶ added in v0.120.0
type QueueListing struct {
Budget int `json:"budget"`
Running []QueueEntry `json:"running"`
Waiting []QueueEntry `json:"waiting"`
}
QueueListing is the inspectable state of the CPU lease queue for `wb run --queue`: who currently holds a slot, and who is waiting, oldest first.
func ListQueue ¶ added in v0.120.0
func ListQueue(projectsRoot string, budget int) QueueListing
ListQueue reports every currently announced holder and registered waiter. It is read-only and safe to call from a separate `wb run --queue` invocation while other WB processes hold or wait for slots.
type State ¶ added in v0.120.0
type State struct {
// Position is this ticket's 1-based rank among current waiters, oldest
// first. Zero when the ticket is not registered (units <= 0) or the
// caller asked for Peek rather than a specific Ticket's Snapshot.
Position int
// Total is the number of tickets currently registered as waiting.
Total int
// Holders are the Participants currently holding CPU lease slots,
// oldest first. It can be shorter than the busy-slot count when a
// holder never announced (e.g. an older WB binary, or a caller other
// than `wb run` sharing the same budget).
Holders []Holder
}
State is a point-in-time snapshot of the CPU lease queue relevant to one waiter: its position among registered waiters, how many waiters are registered in total, and who currently holds slots.
type Ticket ¶ added in v0.120.0
type Ticket struct {
// contains filtered or unexported fields
}
Ticket is one caller's registered wait for CPU units, used only for queue visibility; it never gates admission itself.
func Register ¶ added in v0.120.0
func Register(projectsRoot string, self Participant) *Ticket
Register records a waiter so State/Snapshot can report queue position and depth while units > 0. Callers must call Forget once they stop waiting, admitted or not — typically via defer immediately after Register. Registration is best-effort: a failure to write the ticket file degrades to an invisible waiter (Snapshot reports Position 0) rather than blocking or failing the caller, since visibility must never become a new way for `wb run` to hang or refuse work.
func (*Ticket) Forget ¶ added in v0.120.0
func (ticket *Ticket) Forget()
Forget removes the waiter's ticket. Safe to call more than once and on a Ticket whose registration never succeeded.
func (*Ticket) Heartbeat ¶ added in v0.120.0
func (ticket *Ticket) Heartbeat()
Heartbeat refreshes the ticket's UpdatedAt so readTickets keeps treating it as live while its caller is still waiting. Callers already poll queue state on an interval (e.g. `wb run`'s queued-command heartbeat every ~10s); call Heartbeat from that same loop rather than adding a new one. Safe to call on a nil Ticket or one whose registration never succeeded, and best-effort like Register: a failed refresh just means the ticket may age past staleAfter and be reaped as if its process had died, which only affects visibility, never admission.
func (*Ticket) Snapshot ¶ added in v0.120.0
Snapshot reports this ticket's current position and the queue depth, plus the Participants currently holding CPU lease slots. Safe to call repeatedly (e.g. from a heartbeat); it reflects other WB processes' registrations and slot holdings on disk at the moment of the call.
Source Files