Controller reference¶

Controller is the supervisor: it owns the registered services, the control goroutines, the lifecycle state and the shutdown sequence. This page lists its constructor, its options and every method, with the behaviour of each when it is called at the wrong time.

NewController: what it sets up¶

func NewController(ctx context.Context, opts ...ControllerOpt) *Controller

NewController allocates the controller and applies the options. It starts no goroutine, installs no OS signal handler and touches no process-global state, so constructing a controller you never start is harmless.

The ctx you pass is watched, not inherited. The controller derives its own context with context.WithCancelCause(context.WithoutCancel(ctx)) and watches ctx.Done() separately: completing your context, by cancel or by deadline, triggers the ordinary shutdown sequence, so every service still observes ErrShutdown as its context cause. Values on your context are preserved and visible to services. See Cause determinism.

State immediately after NewController, before any option is applied:

Controller options¶

Each option is a ControllerOpt passed to NewController. There is no way to apply one after construction that is safe once the controller is running; see Setters.

Lifecycle methods¶

Wait and WaitContext are methods on the concrete *Controller only; they are on no interface, including Controllable.

Registration methods¶

Health and introspection methods¶

All three reports are safe to call concurrently while the controller runs, and stay responsive during shutdown, because the stop sequence does not hold the services mutex.

Channels¶

Stop is the only Message the controller defines and the only one the message processor acts on. Sending controls.Stop directly on Messages() drives the same shutdown sequence as calling Stop().

The controller never reads the error channel. It logs each failure at ERROR where it happens, with service_name and kind, and delivers the error to the channel through a forwarder that is the channel's only sender, so a slow reader never blocks a service.

• Calling Errors() subscribes. Failures before your first call are not delivered. Call it before Start, or use WithOnEvent, if you must see a service fail at boot.
• Read the controller's own channel until it closes, which it does before Done closes. A reader that stops early holds Done, and Wait, back by up to the shutdown budget whenever errors are queued for it.
• A channel you install with SetErrorsChannel before Start is subscribed from Start. It is yours, so the controller never closes it, and sends nothing on it after Done. Read it until Done, then take whatever is still buffered.
• Never send on Errors(). Nothing receives, so the send blocks until the channel closes, and then panics.

The channel carries the same failures as WithOnEvent, as bare errors.

Service events¶

type ServiceEvent struct {
    Service  string
    Kind     EventKind
    Err      error
    Restarts int
}

Restarts is the consecutive-restart count, which resets after a healthy run; for a terminal event it is the count the service gave up at. A failure noticed after shutdown has cancelled the services' context is not reported. Events queued when shutdown begins are delivered within the remaining budget, and the number left undelivered at the deadline is logged.

A WithOnEvent callback can run after the controller reaches Stopped, and one still running at the deadline can outlive Done, because a callback cannot be interrupted. A callback that calls Wait or blocks on Done holds up its own drain until the budget expires.

A failure caused by a panic has an Err satisfying errors.Is(err, ErrPanicked), on the event, the error channel and ServiceInfo.Error alike, and its log line carries a stack attribute naming the line that panicked.

Panics¶

Every panic the controller recovers, in a start, stop or probe, or in a standalone health check, is an error wrapping ErrPanicked, with the panic site's stack as its errors.OriginStack. WithOnPanic also hands each one to a callback, for an error tracker:

type PanicReport struct {
    Service string    // the service or health check that panicked
    Site    PanicSite // SiteStart, SiteStop, SiteProbe or SiteHealthCheck
    Value   any       // the recovered value
    Err     error     // wraps ErrPanicked
    Repeats int       // panics merged into this report while it waited
}

• It runs from Start until shutdown's cutoff. A panic before Start, or in a probe called during the drain or after Done, is still recovered and still reported unhealthy, but is not delivered.
• Repeats merge. While a report waits behind a busy callback, a newer panic from the same service, or health check, at the same site replaces its Value and Err and adds one to Repeats. A tracker sees the latest panic at each site with a count of how many it stands for.
• It is drained like the event callback, within the remaining budget after the error channel and WithOnEvent, and what is left at the deadline is logged as undelivered with consumer=WithOnPanic.
• A callback may call Stop. A panic in it is recovered and logged, never reported.
• Nothing orders a report against the event or log line for the same failure.

The shutdown outcome¶

type Outcome struct {
    Cause      StopCause
    Err        error     // context.Cause of the parent for CauseParent; the failure for CauseGaveUp
    Signal     os.Signal // for CauseSignal
    Service    string    // for CauseGaveUp and CauseCompleted
    Unfinished []Unfinished
}

type Unfinished struct {
    Service string
    Reason  UnfinishedReason
    Err     error // the stop's error, for StopFailed
}

Exactly one cause is recorded however many triggers race, and the shutdown deadline is recorded with it, so the budget runs from the trigger. A service giving up after another trigger changes nothing, silently, though its event is still published.

Complete() is true when Unfinished is empty.

Setters, and when they are safe to call¶

SetLogger, SetShutdownTimeout, SetErrorsChannel, SetMessageChannel, SetSignalsChannel, SetWaitGroup and SetState mutate fields that the control goroutines read after Start. They carry no internal synchronisation.

Call them only during construction, before Start, which is what the WithX options do internally. Calling one on a running controller races the running goroutines and is a programming error, not a supported reconfiguration path.

SetState is a different case, and the earlier version of this page had it wrong. It is not there for fakes: StateAccessor is meant to be consumed and implemented outside this module, and a consumer driving a controller it owns needs to say what state it is in. What is true is that it bypasses the compare-and-set transitions, so calling it on a controller you did not construct races the control goroutines, and since readiness is gated on the state it can take a healthy process out of rotation. See wiki spec 0003 D7.

SetSignalsChannel detaches any previous signal.Notify registration before storing the new channel, so swapping the channel cannot leave an orphaned registration receiving signals nobody reads.

Package-level values¶

The Supervisor sentinels and DefaultFailureBufferSize are on the Supervisor page. Generational's four sentinels are on the Generational page.

Related¶

• Services and restart policy: what Register accepts.
• Defaults and timings: every default in one table.
• Handle graceful shutdown and signals: the shutdown sequence in order, and the signal-ownership rule.