task

package
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Index

Constants

View Source
const DefaultGracePeriod = 10 * time.Second

Variables

This section is empty.

Functions

This section is empty.

Types

type Command added in v0.8.0

type Command struct {
	Argv  []string          `json:"argv"` // the executable first
	Dir   string            `json:"dir,omitempty"`
	Env   map[string]string `json:"env,omitempty"`   // on top of the process environment
	Grace time.Duration     `json:"grace,omitempty"` // how long a stopped command gets before a SIGKILL; zero is DefaultGracePeriod
	Out   io.Writer         `json:"-"`               // nil discards the output
}

Command is a command task. job.New(id, cmd.Run) takes a copy, which fixes the definition.

func (Command) Run added in v0.8.0

func (c Command) Run(jc job.Context) error

Run returns nil when the command ended on its own with status 0, a *CommandError otherwise. A job function with bookkeeping of its own calls it on a copy with the Out it wants.

type CommandError added in v0.8.0

type CommandError struct {
	Result CommandResult
}

CommandError unwraps to what stopped the command, so errors.Is(err, context.Canceled) works.

func (*CommandError) Error added in v0.8.0

func (e *CommandError) Error() string

func (*CommandError) Unwrap added in v0.8.0

func (e *CommandError) Unwrap() error

type CommandResult added in v0.8.0

type CommandResult struct {
	ExitCode int   // -1 if the command never started or died of a signal
	Stopped  error // context.Canceled or context.DeadlineExceeded if it was stopped, nil if it ended on its own
	Killed   bool  // it was sent a SIGKILL: forced, or its grace period ran out
	Err      error // why it could not start, or what waiting on it reported
}

type Manager

type Manager interface {
	common.Service
	common.Daemon
	Add(tasks ...*Task) error
	// Remove forgets the tasks and ends what they are doing, then waits for their executions
	// until ctx ends; nothing of them starts after Remove. What still runs once ctx ends is
	// sent SignalKill, like Stop, and the error wraps ctx's.
	Remove(ctx context.Context, tasks ...*Task) error
	Trigger(id string, params any) error
	Cancel(id string) error
	Stats(id string) *Stats
}

func New

func New(opts ...Option) Manager

type Option

type Option func(*manager)

func MaxConcurrency

func MaxConcurrency(size int) Option

func WithLogger

func WithLogger(logger log.Logger) Option

type Stats added in v0.7.0

type Stats struct {
	executor.Stats
	Requeues uint          `json:"requeues"` // times the current firing went back to the queue
	Cooldown time.Duration `json:"cooldown"` // what is left of the current RequeueCooldown
	// Requeueing says the latest execution failed and the task waits to run again, cooling
	// down or back in the queue. Its job stays failed meanwhile: that run did fail.
	Requeueing bool `json:"requeueing"`
}

Stats is what the task's executor reports, plus what the manager adds on top of it.

type Task

type Task struct {
	Job      job.Job         `json:"-"`
	Ctx      context.Context `json:"-"`
	Params   any             `json:"params"`
	Schedule string          `json:"schedule"`
	// Manual keeps the task registered without running it on its own: only Trigger does.
	Manual   bool `json:"manual,omitempty"`
	Priority int  `json:"priority"` // lower runs first; within one, in the order queued
	// Exclusive runs it alone: it takes every slot, so it waits for the executions going on
	// and nothing else starts until it ends. What a forced stop left running holds no slot.
	Exclusive     bool          `json:"exclusive"`
	Timeout       time.Duration `json:"timeout,omitempty"`
	RetryAttempts int           `json:"retry_attempts,omitempty"`
	RetryDelay    time.Duration `json:"retry_delay,omitempty"`
	// GracePeriod is how long a canceled or timed out execution gets to end on its own, for
	// whoever stops it to honor; the manager itself never reads it. Zero means
	// DefaultGracePeriod. A Command has its own Grace for how it stops.
	GracePeriod time.Duration `json:"grace_period,omitempty"`
	// RequeueAttempts is how many times a failed execution, its retries used
	// up, goes back to the queue. Unlike a retry it gives up its slot while
	// it waits, and it counts on top: a task runs up to
	// (RetryAttempts+1) * (RequeueAttempts+1) times.
	RequeueAttempts int `json:"requeue_attempts,omitempty"`
	// RequeueCooldown is how long a failed execution waits before going back to
	// the queue.
	RequeueCooldown time.Duration `json:"requeue_cooldown,omitempty"`
}

Task is configuration; the manager keeps its state of a task elsewhere, so a Task copies like any value.

func (*Task) Grace added in v0.8.0

func (t *Task) Grace() time.Duration

func (*Task) ID added in v0.7.0

func (t *Task) ID() string

ID is the task's identity, its job's ID; look tasks up by ID only.

func (*Task) IsValid

func (t *Task) IsValid() bool

func (*Task) String

func (t *Task) String() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL