Documentation
¶
Overview ¶
Package task tracks detached background work so its status can be polled independently of the CLI invocation that started it.
Index ¶
- Variables
- func WorkerProcessName(id string) string
- type CreateOptions
- type State
- type Status
- type Store
- func (s *Store) Abandoned(state *State) bool
- func (s *Store) ActiveForWorkspace(workspaceID, command string) ([]*State, error)
- func (s *Store) CleanupCanceledWorkerTree(ctx context.Context, id string) error
- func (s *Store) CleanupExitedWorkerTree(id string) error
- func (s *Store) Create(opts CreateOptions) (*Task, error)
- func (s *Store) Delete(id string, force bool) error
- func (s *Store) ForWorkspace(workspaceID, command string) ([]*State, error)
- func (s *Store) Get(id string) (*State, error)
- func (s *Store) List() ([]*State, error)
- func (s *Store) Open(id string) *Task
- func (s *Store) ReconcileState(state *State) *State
- func (s *Store) ReconcileTask(ctx context.Context, id string) (*State, error)
- func (s *Store) WaitForWorkerObservation(ctx context.Context, id string) (WorkerObservation, error)
- type Task
- func (t *Task) BeginLaunch() error
- func (t *Task) Cancel() error
- func (t *Task) CancelContext(ctx context.Context) error
- func (t *Task) Fail(err error) error
- func (t *Task) FinishLaunch() error
- func (t *Task) HoldWorkerLock() error
- func (t *Task) ID() string
- func (t *Task) ReleaseWorkerLock() error
- func (t *Task) Reporter() status.Reporter
- func (t *Task) SetPID(pid int) error
- func (t *Task) SetProcess(ref command.ProcessRef) error
- func (t *Task) SetWorkspaceID(id string) error
- func (t *Task) Succeed(result *config.Result) error
- type WorkerObservation
Constants ¶
This section is empty.
Variables ¶
var ( ErrCanceled = errors.New("canceled") ErrAbandoned = errors.New("worker exited without recording a result") )
Functions ¶
func WorkerProcessName ¶
WorkerProcessName returns the background-process name a detached task's worker is registered under.
Types ¶
type CreateOptions ¶
CreateOptions labels a task at creation time for later listing.
type State ¶
type State struct {
ID string `json:"id"`
Command string `json:"command,omitempty"`
WorkspaceID string `json:"workspaceId,omitempty"`
Status Status `json:"status"`
Phase string `json:"phase,omitempty"`
Step string `json:"step,omitempty"`
OperationID string `json:"operationId,omitempty"`
ParentOperationID string `json:"parentOperationId,omitempty"`
DurationMs int64 `json:"durationMs,omitempty"`
Error string `json:"error,omitempty"`
ErrorCode string `json:"errorCode,omitempty"`
ErrorHint string `json:"errorHint,omitempty"`
ErrorContext map[string]string `json:"errorContext,omitempty"`
Result *config.Result `json:"result,omitempty"`
PID int `json:"pid,omitempty"`
ProcessTreeIdentity string `json:"processTreeIdentity,omitempty"`
Process *command.ProcessRef `json:"process,omitempty"`
ProcessCleanupComplete bool `json:"processCleanupComplete,omitempty"`
CancelRequested bool `json:"cancelRequested,omitempty"`
LaunchPending bool `json:"launchPending,omitempty"`
StartedAt time.Time `json:"startedAt"`
UpdatedAt time.Time `json:"updatedAt"`
}
State is the JSON snapshot persisted for a task. PID names the OS process doing the work, distinct from whatever process is merely polling this state.
func (*State) NeedsCanceledWorkerCleanup ¶
NeedsCanceledWorkerCleanup includes records written by versions that marked cancellation complete before the worker tree was actually terminated.
func (*State) NeedsExitedWorkerCleanup ¶
NeedsExitedWorkerCleanup identifies abandoned tasks whose saved tree has not yet been checked. Other terminal tasks completed their own teardown.
func (*State) ProcessReference ¶
func (s *State) ProcessReference() (command.ProcessRef, bool)
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store persists task state as one JSON file per task under dir.
func NewStoreAt ¶
func (*Store) ActiveForWorkspace ¶
ActiveForWorkspace returns non-terminal tasks for a workspace, newest first.
func (*Store) CleanupCanceledWorkerTree ¶
CleanupCanceledWorkerTree handles records that were marked canceled before their worker tree was terminated. A successful termination of an identityless tree is sufficient only while the worker lock proves it was still live.
func (*Store) CleanupExitedWorkerTree ¶
CleanupExitedWorkerTree tears down any descendants a dead worker left behind. Claiming the worker lock proves no worker is running, so a saved reference that still points at live processes belongs to a crashed worker's tree.
func (*Store) Delete ¶
Delete cleans any unfinished terminal process tree before removing its record. It rejects a non-terminal task unless force is set.
func (*Store) ForWorkspace ¶
ForWorkspace returns matching tasks, newest first, without changing state.
func (*Store) ReconcileState ¶
ReconcileState marks a task after its worker exits without a result. A requested cancellation completes cleanup here; an abandoned task's tree is cleaned up by the next workspace stop or delete.
func (*Store) ReconcileTask ¶
ReconcileTask cleans up a task whose worker exited before recording its result, then records it as canceled or abandoned.
func (*Store) WaitForWorkerObservation ¶
func (s *Store) WaitForWorkerObservation( ctx context.Context, id string, ) (WorkerObservation, error)
WaitForWorkerObservation waits until process metadata is published, the task becomes terminal, or its worker lock becomes available.
type Task ¶
type Task struct {
// contains filtered or unexported fields
}
Task is a handle to a single background task, bound to the Store it was created in. Report may be called from multiple goroutines; each call serializes its own read-modify-write of the state file.
func (*Task) BeginLaunch ¶
func (*Task) Cancel ¶
Cancel terminates the worker before recording cancellation. A termination failure leaves the task retryable.
func (*Task) Fail ¶
Fail preserves an existing terminal state, so the error a canceled worker reports on its way out doesn't mask ErrCanceled as the reason it stopped.
func (*Task) FinishLaunch ¶
func (*Task) HoldWorkerLock ¶
HoldWorkerLock claims this task's worker lock while its worker is active. Release it only when startup aborts before work begins.
Returns an error if another process already holds the lock, since that means a worker for this task is already running.
func (*Task) ReleaseWorkerLock ¶
ReleaseWorkerLock releases the worker claim when startup aborts before work begins.
func (*Task) SetProcess ¶
func (t *Task) SetProcess(ref command.ProcessRef) error
func (*Task) SetWorkspaceID ¶
SetWorkspaceID corrects the task's workspace label to the resolved ID, which may differ from whatever label it was created with (e.g. a raw source string guessed before workspace resolution ran). client.Status looks tasks up by this label, so it must end up accurate.
Source Files