lifecycle

package
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Sep 29, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package lifecycle coordinates an ordered tree of application components. Start runs parent hooks before children, in creation order. Stop unwinds children in reverse order, then cancels the node, runs its stop hooks in reverse order and drains its goroutines. A failed start is unwound too. Call Stop even when Start fails. Hooks must honor their context deadlines.

Node lifetimes are detached from the startup context, so shutdown can drain dependents before closing their dependencies. No signals, logging or health policy is imposed. The application drives Start, Failed and Stop.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrStopTimeout = errors.New("lifecycle: goroutines did not stop in time")
	ErrPanic       = errors.New("lifecycle: goroutine panicked")
	ErrStarted     = errors.New("lifecycle: node already started or stopped")
)

Functions

This section is empty.

Types

type Group

type Group interface {
	Go(func(context.Context) error)
}

Group is the registration side for components that own background work.

type Node

type Node struct {
	// contains filtered or unexported fields
}

Node owns start/stop hooks and goroutines. It must not be copied. Create a root with New and declare its children before Start. A starting node may also create children in its own start hooks. Start and Stop are serialized across the tree; they must not be called from a lifecycle hook.

func New

func New(name string) *Node

New creates a lifecycle root. Names identify failures; they need not be unique.

func (*Node) Budget

func (n *Node) Budget(fn func(ctx context.Context) (context.Context, context.CancelFunc))

Budget narrows the node's own stop (its stop hooks and the wait for its goroutines) to the context fn derives from the tree's stop context: a per-node sub-deadline within the shutdown budget. Its children keep the tree's context.

func (*Node) Child

func (n *Node) Child(name string) *Node

Child appends a child in startup order. After startup begins, only a currently starting parent may create children. Misuse panics.

func (*Node) Children

func (n *Node) Children() []*Node

Children are n's direct children in creation (start) order.

func (*Node) Failed

func (n *Node) Failed() <-chan error

Failed delivers the first goroutine failure of the tree.

func (*Node) Go

func (n *Node) Go(fn func(ctx context.Context) error)

Go runs fn on the node's context once the node has started; it is cancelled when the node stops, and the stop waits for it. A non-nil error (or a panic) stops the service. After the node stopped, fn is dropped.

func (*Node) Name

func (n *Node) Name() string

Name is the diagnostic label supplied to New or Child.

func (*Node) OnStart

func (n *Node) OnStart(fn func(ctx context.Context) error)

func (*Node) OnStop

func (n *Node) OnStop(fn func(ctx context.Context) error)

OnStop adds fn to the node's stop; stop hooks run in reverse.

func (*Node) Start

func (n *Node) Start(ctx context.Context) error

Start starts n's subtree depth-first in creation order. ctx bounds the start hooks; node lifetimes are detached from it. On error the caller must still call Stop, which unwinds whatever started.

func (*Node) Stop

func (n *Node) Stop(ctx context.Context) error

Stop stops n's subtree in exact reverse of Start within ctx. Nodes that never started are skipped.

func (*Node) Walk

func (n *Node) Walk(fn func(*Node))

Walk visits n's subtree depth-first in creation order.

Jump to

Keyboard shortcuts

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