Documentation
¶
Overview ¶
Package jobs provides a set of task grouping tools for running sequences of tasks, halting on error, and displaying their results.
The four main entrypoints are Run, RunContext, Parallel, and ParallelContext. They accept implementations of the Job interface, which you can either implement in your own task types, or simply cast functions to the JobFunc type. They return Events, a synchronous bus of events that, for each job, always occur in the following order:
*EventQueued *EventStarted *EventProgressed *EventFinished
Additionally, if a job spawns any sub-jobs, their events will arrive between *EventStarted and *EventFinished.
Index ¶
- type Context
- func (c *Context) Parallel(concurrency int, jobs ...Job) (events Events)
- func (c *Context) ParallelContext(ctx context.Context, concurrency int, jobs ...Job) (events Events)
- func (c *Context) Progress(payload interface{})
- func (c *Context) Run(jobs ...Job) (events Events)
- func (c *Context) RunContext(ctx context.Context, jobs ...Job) (events Events)
- type Event
- type EventFinished
- type EventProgressed
- type EventQueued
- type EventStarted
- type Events
- type Formatter
- type Job
- type JobFuncContext
- type Sequence
- type TextPresenter
- type TreeBinding
- type TreePresenter
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Context ¶
Context is passed as the argument to each job's Run function. It implements context.Context, and can be used to cancel jobs where possible.
It also allows jobs to spawn sub-jobs using its Run, RunContext, Parallel, and ParallelContext functions, which return their own Events busses. Events from sub-jobs are sent first to this bus, and then to the bus of the parent job.
func (*Context) Parallel ¶
Parallel runs the given jobs using a queue and the number of worker specified by concurrency. Errors do not affect continuation.
func (*Context) ParallelContext ¶
func (c *Context) ParallelContext(ctx context.Context, concurrency int, jobs ...Job) (events Events)
ParallelContext is identical to Parallel, but accepts a context.Context.
func (*Context) Progress ¶
func (c *Context) Progress(payload interface{})
Progress can be used to generate additional EventProgressed events, with implementation-specific payloads.
type Event ¶
type Event interface {
// Job is the job for which the event has occurred.
Job() Job
}
Event signals that a job has been queued, started, progressed, or finished.
type EventFinished ¶
type EventFinished struct {
// contains filtered or unexported fields
}
EventFinished occurs when a job finishes.
func (*EventFinished) Error ¶
func (e *EventFinished) Error() error
Error is the error returned by the job.
type EventProgressed ¶
type EventProgressed struct {
// contains filtered or unexported fields
}
EventProgressed occurs when a job progresses. It is triggered by a call from the job to its Context.Progress function.
func (*EventProgressed) Job ¶
func (e *EventProgressed) Job() Job
Job is the job that has progressed.
func (*EventProgressed) Payload ¶
func (e *EventProgressed) Payload() interface{}
Payload is the job-specific payload that contains information about the job's progress. It is the argument given by the job to its Context.Progress.
type EventQueued ¶
type EventQueued struct {
// contains filtered or unexported fields
}
EventQueued occurs when an event is queued by a call to Run, RunContext, Parallel, or ParallelContext. When multiple jobs are queued, EventQueued events occur in the same order.
func (*EventQueued) Parent ¶
func (e *EventQueued) Parent() Job
Parent is the job that queued Job, if it was queued using another job's Context. Otherwise, Parent is nil.
type EventStarted ¶
type EventStarted struct {
// contains filtered or unexported fields
}
EventStarted occurs when a Job starts.
type Events ¶
type Events chan Event
Events is a synchronous event bus for jobs and their sub-jobs.
func Parallel ¶
Parallel runs the given jobs using a queue and the number of worker specified by concurrency. Errors do not affect continuation.
func ParallelContext ¶
ParallelContext is identical to Parallel, but accepts a context.Context.
func Run ¶
Run runs the given jobs one after the other. If any job returns an error, subsequent jobs are not run.
func RunContext ¶
RunContext is identical to Run, but accepts a context.Context.
type JobFuncContext ¶
JobFuncContext converts a simple function that accepts a Context to a Job implementation.
func JobFunc ¶
func JobFunc(job func() (err error)) JobFuncContext
JobFunc converts a simple function to a Job implementation.
func (JobFuncContext) Run ¶
func (j JobFuncContext) Run(ctx *Context) (err error)
Run implements Job.
type Sequence ¶
type Sequence []Job
Sequence is an implementation of Job that runs a sequence of jobs using its Context.Run.
type TextPresenter ¶
type TextPresenter struct {
// When true, jobs that were queued but did not start will be included in TextPresenter's output.
ShowSkipped bool
// SuffixOk is appended to lines of jobs that succeed.
SuffixOk string
// SuffixFail is appended to lines of jobs that fail.
SuffixFail string
// SuffixSkipped is appended to lines of jobs that are queued but do not run.
SuffixSkipped string
// Indent is prepended to sub-jobs.
Indent string
// contains filtered or unexported fields
}
TextPresenter wraps a Job, and uses a Formatter to display each of Job's child jobs on a new line.
func NewTextPresenter ¶
func NewTextPresenter(job Job, writer io.Writer, formatter Formatter) *TextPresenter
NewTextPresenter creates a TextPresenter .
func (*TextPresenter) Run ¶
func (t *TextPresenter) Run(ctx *Context) (err error)
Run implements Job.
type TreeBinding ¶
type TreeBinding struct {
// contains filtered or unexported fields
}
TreeBinding creates a trees.Node on the given trees.Node for every descendent Job spawned by the given Job, and provides them through the Node function. TreeBinding implements Job, and can be run like any other Job. A zero TreeBinding is not valid; use NewTreeBinding.
func NewTreeBinding ¶
func NewTreeBinding(job Job, node trees.Node) *TreeBinding
NewTreeBinding creates a new TreeBinding for the given job and node.
type TreePresenter ¶
type TreePresenter struct {
// contains filtered or unexported fields
}
TreePresenter wraps a Job, and uses a Formatter to display each of Job's descendants in a node of a trees.Node.
func NewTreePresenter ¶
func NewTreePresenter(job Job, node trees.Node, formatter Formatter) *TreePresenter
NewTreePresenter creates TreePresenter.
func (*TreePresenter) Run ¶
func (t *TreePresenter) Run(ctx *Context) (err error)
Run implements Job.
Source Files