Documentation
¶
Overview ¶
Package task tracks detached background work so its status can be polled independently of the CLI invocation that started it.
Index ¶
- Variables
- type CreateOptions
- type State
- type Status
- type Store
- func (s *Store) Abandoned(state *State) bool
- func (s *Store) Create(opts CreateOptions) (*Task, error)
- func (s *Store) Delete(id string, force bool) 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) Reconcile(state *State) *State
- type Task
- func (t *Task) Cancel() error
- func (t *Task) Fail(err error) error
- func (t *Task) HoldWorkerLock() error
- func (t *Task) ID() string
- func (t *Task) ReleaseWorkerLockForTest() error
- func (t *Task) Reporter() status.Reporter
- func (t *Task) SetPID(pid int) error
- func (t *Task) SetWorkspaceID(id string) error
- func (t *Task) Succeed(result *config.Result) error
Constants ¶
This section is empty.
Variables ¶
var ( ErrCanceled = errors.New("canceled") ErrAbandoned = errors.New("worker exited without recording a result") )
Functions ¶
This section is empty.
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"`
Error string `json:"error,omitempty"`
Result *config.Result `json:"result,omitempty"`
PID int `json:"pid,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.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store persists task state as one JSON file per task under dir.
func NewStoreAt ¶
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) Cancel ¶
Cancel is safe to call even if the process already exited on its own. The terminal check and state transition happen atomically under the same lock, so a concurrent report from the task's own worker can't race with marking it canceled here.
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) HoldWorkerLock ¶
HoldWorkerLock claims this task's worker lock for the rest of the process's life, marking it as actively being worked on. Callers must not release it: the kernel does so when the process exits, crashes, or is killed.
Returns an error if another process already holds the lock, since that means a worker for this task is already running.
func (*Task) ReleaseWorkerLockForTest ¶
ReleaseWorkerLockForTest drops the lock HoldWorkerLock acquired, letting a test simulate a dead worker. Production code must never call it.
Not in export_test.go: other packages' tests need it, and a _test.go file is only compiled into its own package's test binary.
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