Documentation
¶
Overview ¶
Package routine runs a server's background routines: the work it does beside its requests (docs/designs/background-routines.md).
A Group owns a set of routines, starts each, and stops them together. Each kind is one method:
- Every: a short run, every interval, on the group's clock.
- Loop: one run that lasts, deciding for itself when it next wakes: a listener or a poller that paces itself. Restarted with backoff when it returns early, since its source breaks in normal operation.
- Worker: one run that handles a queue other code feeds. Stop drains it.
- Task: one piece of work, handed in at any time after Start.
Stop cancels what never ends on its own, a loop, and lets the rest finish, until its own context ends. A panic crashes the process, after a log line naming the routine, unless the routine was registered with Recover.
The helper keeps nothing that survives a restart: whatever must is the routine's own concern, kept in a store by its function.
Index ¶
- type Backoff
- type Group
- func (g *Group) Every(name string, interval time.Duration, fn func(context.Context) error, ...)
- func (g *Group) Loop(name string, fn func(context.Context) error, opts ...Option)
- func (g *Group) Start(ctx context.Context)
- func (g *Group) Stop(ctx context.Context) error
- func (g *Group) Task(name string, fn func(context.Context) error) bool
- func (g *Group) Worker(name string, fn func(context.Context))
- type Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Backoff ¶
type Backoff struct {
// contains filtered or unexported fields
}
Backoff is a retry delay: exponential from its min to its max, with jitter. A Loop restarts by one; a routine retrying its own items, a worker's failed write say, uses one of its own. Not safe for concurrent use.
func NewBackoff ¶
NewBackoff returns a backoff from min to max.
func (*Backoff) Next ¶
Next is the next delay, and counts an attempt. Each is between half and all of min doubled once per attempt before it, capped at max.
type Group ¶
type Group struct {
// contains filtered or unexported fields
}
Group owns a set of routines. Register them with Every, Loop and Worker before Start; hand it tasks with Task after.
func NewGroup ¶
NewGroup returns an empty group. name names it in its log lines; logger is slog.Default() when nil.
func (*Group) Every ¶
func (g *Group) Every(name string, interval time.Duration, fn func(context.Context) error, opts ...Option)
Every runs fn every interval, measured from the end of the last run, with jitter, so runs never overlap. Its first run comes a random part of interval after Start, unless Immediately, so instances started together do not run in lockstep. An error is logged and counted; the next tick runs as usual.
fn returns once it has done what is due, and promptly once its context ends. Stop starts no new run and lets the current one finish.
func (*Group) Loop ¶
Loop runs fn, which runs until its context ends. If fn returns before then, with an error or without, the return is logged and counted, and fn is called again after backoff (RestartBackoff; 1s to 30s by default).
fn opens its source, catches up on what it missed, then consumes. It returns an error for an outage of its source, which reopening fixes, and handles a failed event itself. Stop cancels its context at once, cutting a backoff short.
func (*Group) Start ¶
Start starts every routine registered. ctx gives them its values, such as a tracer's; its cancellation is ignored, since Stop ends them. A group started twice panics; one stopped before it started never starts.
func (*Group) Stop ¶
Stop starts no new run or task, cancels the loops, and waits for every routine to return: runs and tasks in progress finish, and workers drain. Once ctx ends, it cancels those too, waits for them to return, and returns ctx's error. A second call waits as the first does. Stop before Start is harmless.
Stop returns only once every routine has returned, so what they use can then be closed.
func (*Group) Task ¶
Task runs fn once, now, on a goroutine of its own, and reports whether it did: false before Start, and once Stop has begun, so the caller can do the work inline or drop it. An error is logged and counted; nothing retries a task, so one that must succeed retries inside fn.
Stop lets a running task finish: its context is cancelled only once Stop's own context ends.
func (*Group) Worker ¶
Worker runs fn once. Its return ends it, whenever that is: it is never called again.
fn handles a queue its owner feeds, and returns once the owner has closed it and it is empty, or once its context ends. It handles every failure itself, having no error to return. Stop lets it drain: its context is cancelled only once Stop's own context ends.
type Option ¶
type Option struct {
// contains filtered or unexported fields
}
Option changes how a routine runs. Each applies to some kinds only; given to another, it panics at registration.
func Immediately ¶
func Immediately() Option
Immediately runs an Every's first run at Start, rather than a random part of its interval later.
func Jitter ¶
Jitter sets the jitter on an Every's interval: each wait is the interval, give or take f of it. 0.1 by default; 0 for none.
func Recover ¶
func Recover() Option
Recover makes an Every recover a panic in a run, counting it as a failed run and carrying on, rather than crashing the process. Use it only for a routine whose run holds no state outside its own call: one that works through a database transaction, which a panic rolls back, and touches no shared memory.
func RestartBackoff ¶
RestartBackoff sets a Loop's restart delay: exponential from min to max, with jitter, and reset once a run lasts longer than max. 1s to 30s by default.