Documentation
¶
Overview ¶
Package fleet implements an in-memory task board that workers pull from. Every operation runs under a single mutex, so each task is claimed by at most one worker at a time. Claims are served FIFO, and failed tasks can be requeued for retry.
Index ¶
- Variables
- type Board
- func (b *Board) Add(payload string) *Task
- func (b *Board) Claim(owner string) (Task, bool)
- func (b *Board) Complete(id, owner, result string) error
- func (b *Board) Export() []Task
- func (b *Board) Fail(id, owner, errMsg string, requeue bool) error
- func (b *Board) Get(id string) (Task, bool)
- func (b *Board) Heartbeat(id, owner string) (Task, error)
- func (b *Board) List() []Task
- func (b *Board) Remaining() int
- func (b *Board) SetLease(d time.Duration)
- func (b *Board) Stats() Stats
- func (b *Board) Sweep(now time.Time) []Task
- type Stats
- type Task
- type TaskState
Constants ¶
This section is empty.
Variables ¶
var ( ErrNotFound = errors.New("fleet: task not found") ErrIllegalTransition = errors.New("fleet: illegal state transition") )
Sentinel errors returned by Board methods.
Functions ¶
This section is empty.
Types ¶
type Board ¶
type Board struct {
// contains filtered or unexported fields
}
Board is an in-memory task board. Construct with NewBoard or Seed. All methods are safe for concurrent use.
func Load ¶
Load reconstructs a board from an Export snapshot, preserving IDs, states, and insertion order.
func (*Board) Claim ¶
Claim takes the oldest pending task, marks it claimed by owner, and returns a copy. It returns false if nothing is pending. The scan-and-mutate runs under the board mutex, so two callers can never get the same task.
func (*Board) Complete ¶
Complete marks the claimed task id as done with the given result. owner must match the worker that claimed the task (empty owner skips the check, for trusted/local callers).
func (*Board) Export ¶
Export returns a copy of every task in insertion order, suitable for serialization.
func (*Board) Fail ¶
Fail marks the claimed task id as failed with errMsg. When requeue is true the task instead goes back to the pending pool (owner cleared, attempts kept) so another worker can retry it. owner must match the claiming worker (empty owner skips the check, for trusted/local callers).
func (*Board) Heartbeat ¶
Heartbeat extends the lease on a claimed task held by owner. It fails if the task doesn't exist, isn't claimed, or is claimed by someone else.
func (*Board) Remaining ¶
Remaining returns the number of tasks still in flight: pending plus claimed.
func (*Board) SetLease ¶
SetLease sets the claim lease duration. When d > 0, Claim stamps a deadline of now+d, Heartbeat extends it, and Sweep requeues tasks whose lease has passed. Non-positive d disables lease expiry.
type Stats ¶
type Stats struct {
Total int `json:"total"`
Pending int `json:"pending"`
Claimed int `json:"claimed"`
Done int `json:"done"`
Failed int `json:"failed"`
}
Stats is a point-in-time count of tasks by state.
type Task ¶
type Task struct {
ID string `json:"id"`
Payload string `json:"payload"`
State TaskState `json:"state"`
// Owner is the worker that last claimed the task; cleared on requeue.
Owner string `json:"owner"`
// Attempts counts claims, not completions.
Attempts int `json:"attempts"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
Result string `json:"result"`
Error string `json:"error"`
// LeaseExpiry is when the current claim expires; Sweep requeues claimed
// tasks past it. Zero means no lease (claims never expire).
LeaseExpiry time.Time `json:"lease_expiry,omitempty"`
}
Task is a unit of work on the board. Board methods hand out copies, so callers can never mutate board state through a returned value.
Source Files