Documentation
¶
Overview ¶
Package task defines Task, a unit of work which can be retried if it fails.
Index ¶
- Constants
- Variables
- func Configurable(s any) bool
- func Configure(s any, configData []byte) error
- func Run(ctx context.Context, task Task, options ...Option) error
- func Stop(s any) error
- func Stoppable(s any) bool
- type Configurer
- type Group
- type GroupTask
- type Intermittent
- type Lifecycle
- type Next
- type Option
- type RunConfigFunc
- type Runner
- type StartFn
- type Starter
- type State
- type Status
- type StopFn
- type Stopper
- type Task
Examples ¶
Constants ¶
const RetryUnlimited int = math.MaxInt
RetryUnlimited allows a Task to be restarted forever. Used as an argument to WithRetry.
Variables ¶
var ErrCannotBeConfigured = errors.New("cannot be configured")
ErrCannotBeConfigured is returned when attempting to Configure an automation that does not implement Configurer.
var ErrCannotBeStopped = errors.New("cannot be stopped")
ErrCannotBeStopped is returned when attempting to Stop an automation that does not implement Stopper.
Functions ¶
func Configurable ¶
Configurable returns whether the given automation can be configured.
func Configure ¶
Configure attempts to configure the given automation. If the automation does not implement Configurer then ErrCannotBeConfigured will be returned.
func Run ¶
Run will run a Task to completion in a blocking fashion. By default, the Task is run once. Pass Options in order to add automatic retry with backoff, logging etc.
This is a convenience function that constructs a Runner and calls Runner.Step in a loop until the runner completes.
Types ¶
type Configurer ¶
Configurer describes types that can be configured. Configuration data is represented as a []byte and the automation is expected to decode this data into an internally significant data structure.
type Intermittent ¶
type Intermittent struct {
// contains filtered or unexported fields
}
Intermittent manages the lifecycle of a long-running background operation that needs to outlive a single context. A context can be attached to the Intermittent by calling Attach, which will start the background operation if it is not already running. Once all attached contexts are cancelled, the background operation will be stopped.
Attach is safe for use by multiple go routines.
func NewIntermittent ¶
func NewIntermittent(operation StartFn) *Intermittent
func Poll ¶
func Poll(action func(context.Context), interval time.Duration) *Intermittent
Poll creates a task that calls a function at a regular interval while it is running. The action will not be run until the returned Intermittent.Attach is called.
func (*Intermittent) Attach ¶
func (t *Intermittent) Attach(listener context.Context) error
Attach adds ensures that the background task will remain running for at least as long as listener is not done. If the background task is not running it will be started.
Returns an error iff the background task is started by this call and when starting it returns an error.
type Lifecycle ¶
type Lifecycle[C any] struct { // ApplyConfig is a function that gets called each time config is changed. ApplyConfig RunConfigFunc[C] Logger *zap.Logger // ReadConfig converts bytes into C. // Defaults to json.Unmarshal. ReadConfig func(bytes []byte) (C, error) // contains filtered or unexported fields }
Lifecycle manages the lifecycle of a driver as per task.Starter, task.Configurer, and task.Stopper. Embed Lifecycle into your own driver type and provide a RunConfigFunc that binds your driver based on config.
func NewLifecycle ¶
func NewLifecycle[C any](runFunc RunConfigFunc[C]) *Lifecycle[C]
NewLifecycle creates a new Lifecycle that calls runFunc each time config is loaded.
func (*Lifecycle[C]) Configure ¶
Configure instructs the driver to setup and announce any devices found in configData. configData should be an encoded JSON object matching config.Root.
Configure must not be called before Start, but once Started can be called concurrently.
func (*Lifecycle[C]) CurrentState ¶
func (*Lifecycle[C]) Start ¶
Start makes this driver available to be configured. Call Stop when you're done with the driver to free up resources.
Start must be called before Configure. Once started Configure and Stop may be called from any go routine.
type Next ¶
type Next int
Next allows a task to specify a preferred retry behaviour.
const ( // Normal mode of operation - Task is retried if it returns a non-nil error. Normal Next = iota // StopNow will prevent the task from being restarted, even if it returns a non-nil error. StopNow // RetryNow will restart the task immediately, without any delay. The backoff will also be reset. RetryNow // ResetBackoff will reset the Task restart delay to its starting value, and then continue as normal. ResetBackoff )
type Option ¶
type Option func(o *Runner)
func WithBackoff ¶
WithBackoff adds exponential backoff when retrying tasks. The delay begins at start, and is capped at max. After each attempt, the delay increases by a factor of 1.5.
func WithErrorLogger ¶
WithErrorLogger will log to the provided logger every time the Task returns a non-nil error.
func WithRetry ¶
WithRetry places a limit on the number of times a Task may be restarted before we give up. By default, a Task will only be run once. Pass RetryUnlimited to retry forever.
func WithRetryDelay ¶
WithRetryDelay adds a fixed delay between a Task returning and the next attempt starting. By default, there is no delay and retries happen immediately.
func WithTimeout ¶
WithTimeout imposes a time limit on each individual invocation of the Task.
type RunConfigFunc ¶
RunConfigFunc is called when a drivers config changes and should apply those changes. The ctx will be cancelled if the driver stops or the config is replaced. RunConfigFunc should only block while cfg is being applied, any long running tasks should run in separate go routines.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
A Runner allows the caller control over the invocation of a Task. Call Step to run the Task - the return values will tell you if and when to call Step again.
func (*Runner) Step ¶
Step will run this Runner's Task once. The error from the task is returned as err. If the task should be run again due to the applicable retry options, then the return value again will be true and the required delay before the next invocation is returned in delay.
Callers will generally want to call Step in a loop until again=false.
Example ¶
n := 0
t := Task(func(ctx context.Context) (Next, error) {
n++
return Normal, errors.New("an error")
})
runner := NewRunner(t, WithRetry(3))
for {
_, again, delay := runner.Step(context.Background())
if !again {
break
}
time.Sleep(delay)
}
fmt.Println(n)
Output: 3
type StartFn ¶
StartFn is called by an Intermittent to start a background operation. The provided context.Context init can be used for initialisation - it is simply the context passed to Intermittent.Attach. However, it is not suitable for long-running background operations - create a long-running context using context.WithCancel(context.Background()). If starting the background operations succeeds, then a StartFn should return a stop function and err should be nil. The stop function will be called when the background operation needs to stop. If starting the background operation fails, then return a non-nil err; the value of the stop function is ignored.
type Starter ¶
type Starter interface {
// Start instructs the automation to start.
// The ctx represents how long the type can spend starting before it should give up.
Start(ctx context.Context) error
}
Starter describes types that can be started.
type Status ¶
type Status string
const ( StatusInactive Status = "inactive" // Stopped task. Status after calling Stop StatusLoading Status = "loading" // The task is loading configuration. Status while Configure is running StatusActive Status = "active" // The task has valid config and is serving requests. Status after calling Start StatusError Status = "error" // The task failed to start. If start fails, the driver will be in this state. )
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package serviceapi implements gen.ServiceApi backed by a service.Map.
|
Package serviceapi implements gen.ServiceApi backed by a service.Map. |