routine

package
v0.19.0 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

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

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

func NewBackoff(min, max time.Duration) *Backoff

NewBackoff returns a backoff from min to max.

func (*Backoff) Next

func (b *Backoff) Next() time.Duration

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.

func (*Backoff) Reset

func (b *Backoff) Reset()

Reset starts the delays over from min, after a success.

func (*Backoff) Wait

func (b *Backoff) Wait(ctx context.Context) error

Wait sleeps the next delay, or until ctx ends, returning its error.

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

func NewGroup(name string, logger *slog.Logger) *Group

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

func (g *Group) Loop(name string, fn func(context.Context) error, opts ...Option)

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

func (g *Group) Start(ctx context.Context)

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

func (g *Group) Stop(ctx context.Context) error

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

func (g *Group) Task(name string, fn func(context.Context) error) bool

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

func (g *Group) Worker(name string, fn func(context.Context))

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

func Jitter(f float64) Option

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

func RestartBackoff(min, max time.Duration) Option

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.

Jump to

Keyboard shortcuts

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