Package: go.pact.im/x/supervisor

package supervisor Import Path go.pact.im/x/supervisor (on go.dev) Dependency Relation imports 7 packages, and imported by 0 packages Involved Source Files builder.go group.go interrupt.go d supervisor.go Package supervisor provides [process.Runner] supervision implementation. Code Examples GroupBuilder { ctx := context.Background() builder := NewBuilder(GroupBuilder) _ = builder.Run(ctx, func(_ context.Context) error { g, _ := builder.Runner() g.Go(process.Nop(), nil) return nil }) } Package-Level Type Names (total 6, in which 5 are exported) /* sort exporteds by: alphabet | popularity */ type Builder[T] (struct) Type Parameters: T: process.Runner Builder is a reusable [process.Runner] implementation that uses [BuilderFunc] on each [Builder.Run] invocation to create a fresh [process.Runner] instance for implementations that would otherwise be single-use (do not allow calling Run more than once per instance). Fields (total 3, none are exported) /* 3 unexporteds ... *//* 3 unexporteds: */ build BuilderFunc[T] runner option.Of[T] runnerMu sync.RWMutex Methods (total 3, in which 2 are exported) (*Builder[T]) Run(ctx context.Context, callback process.Callback) error Run implements the [process.Runner] interface. It uses [BuildFunc] to create a runner, executes it, and discards the instance when complete. Use [Builder.Runner] to get the currently executing runner instance. (*Builder[T]) Runner() (T, bool) Runner returns the runner currently executing via [Builder.Run] It returns false when no execution is active. /* one unexported ... *//* one unexported: */ (*Builder[T]) setRunner(v option.Of[T]) setRunner updates the currently execution runner instance. Implements (at least one exported) *Builder : go.pact.im/x/process.Runner As Outputs Of (at least one exported) func NewBuilder[T](f BuilderFunc[T]) *Builder[T] type BuilderFunc[T] (func) Type Parameters: T: process.Runner BuilderFunc is a factory function that constructs [process.Runner] instances. Methods (only one, which is exported) ( BuilderFunc[T]) Run(ctx context.Context, callback process.Callback) error Run implements the [process.Runner] interface. It calls the factory function to create a runner, then delegates to that runner’s Run method. Implements (at least one exported) BuilderFunc : go.pact.im/x/process.Runner As Outputs Of (at least one exported) func Identity[T](runner T) BuilderFunc[T] As Inputs Of (at least one exported) func NewBuilder[T](f BuilderFunc[T]) *Builder[T] type Group (struct) Group manages a collection of [process.Runner] instances that run concurrently in the background and can be stopped together. Use Go method to add runners, Interrupt to signal them to shutdown gracefully, and Wait to wait for them to complete. Fields (total 4, none are exported) /* 4 unexporteds ... *//* 4 unexporteds: */ ctx context.Context done chan struct{} mu sync.Mutex wg sync.WaitGroup Methods (total 4, all are exported) (*Group) Go(p process.Runner, atExit func(error)) Go starts a runner in the background, calling atExit when it finishes. (*Group) Interrupt() Interrupt signals all runners started before the next [Group.Wait] call to stop. (*Group) Run(ctx context.Context, callback process.Callback) error Run implements the [process.Runner] interface. It runs the callback, then interrupts all runners in the group and waits for them to complete. (*Group) Wait() Wait blocks until all currently running processes exit. Implements (at least one exported) *Group : go.pact.im/x/process.Runner As Outputs Of (at least 2, both are exported) func GroupBuilder(ctx context.Context) (*Group, error) func NewGroup(ctx context.Context) *Group type Hook (struct) Hook is a set of hooks for supervisor’s runner. Fields (total 2, both are exported) Post func(context.Context, *Supervisor) error Post is a function that is called before runner’s callback returns. The result is returned from the callback. Defaults to a function that returns nil error. Pre func(context.Context, *Supervisor) error Pre is a function that is called on runner’s callback. A non-nil error is immediately returned from the callback. In that case, an error from PostHook is ignored. Defaults to a function that returns nil error. As Inputs Of (at least one exported) func NewSupervisor(runner process.Runner, exec flaky.Executor, hook Hook) *Supervisor type Supervisor (struct) Supervisor runs a [process.Runner] alongside a control callback, managing their concurrent execution and coordinated shutdown. It wraps the runner with [flaky.Executor] retry logic and pre/post execution hooks. Fields (total 4, none are exported) /* 4 unexporteds ... *//* 4 unexporteds: */ exec flaky.Executor hook Hook intr atomic.Pointer[supervisorInterrupter] runner process.Runner Methods (total 5, in which 2 are exported) (*Supervisor) Interrupt() Interrupt signals the supervisor to stop the current execution. This method is non-blocking and returns immediately; it does not wait for execution to complete. If no execution is active ([Supervisor.Run] is not being called), this method does nothing. Otherwise, it signals the process to stop, but the caller must separately wait for Run to return if synchronization is needed. It is safe to call from multiple goroutines concurrently. (*Supervisor) Run(ctx context.Context, callback process.Callback) error Run executes the supervisor’s managed process concurrently with the provided callback function without waiting for the initial process startup. Use [Hook.Pre] and [Hook.Post] to run code in runner’s callback. It returns an error combining any errors from the callback and runner execution. Execution timeline: - T0: Start runner under executor in background goroutine. - T0: Start callback in current goroutine. - T1: Callback returns → interrupt executor. - T1: Executor returns → cancel callback context. - T2: Wait for executor to complete cleanup → return combined errors. Only one active Run invocation is permitted per Supervisor instance. Concurrent or recursive calls will return an error. /* 3 unexporteds ... *//* 3 unexporteds: */ (*Supervisor) execute(ctx context.Context, intr *supervisorInterrupter) error execute runs the supervised process under the executor with pre/post Run hooks. (*Supervisor) post(ctx context.Context) error pre runs post hook of the supervisor. (*Supervisor) pre(ctx context.Context) error pre runs pre hook of the supervisor. Implements (at least one exported) *Supervisor : go.pact.im/x/process.Runner As Outputs Of (at least one exported) func NewSupervisor(runner process.Runner, exec flaky.Executor, hook Hook) *Supervisor /* one unexported ... *//* one unexported: */ type supervisorInterrupter (struct) supervisorInterrupter manages the interruption state between [flaky.Executor], [process.Runner] and [process.Callback]. Fields (total 5, none are exported) /* 5 unexporteds ... *//* 5 unexporteds: */ cancel context.CancelFunc done chan struct{} running bool stopMu sync.Mutex stopped bool Methods (total 3, in which 1 is exported) (*supervisorInterrupter) Interrupt() Interrupt signals the supervisor to stop execution. /* 2 unexporteds ... *//* 2 unexporteds: */ (*supervisorInterrupter) afterRunner() afterRunner handles cleanup after the runner completes execution. It cancels the callback context if an interrupt was requested during execution. (*supervisorInterrupter) shouldStopBeforeRunner() bool shouldStopBeforeRun checks if an interrupt was requested before runner execution starts. It sets the running flag to true and returns whether execution should be stopped. It panics if the executor wasn’t properly interrupted after a stop was requested. As Inputs Of (at least one unexported) /* at least one unexported ... *//* at least one unexported: */ func (*Supervisor).execute(ctx context.Context, intr *supervisorInterrupter) error Package-Level Functions (total 5, all are exported) func GroupBuilder(ctx context.Context) (*Group, error) GroupBuilder is a [BuilderFunc] function for the [Group] type. func Identity[T](runner T) BuilderFunc[T] Type Parameters: T: process.Runner Identity returns a [BuilderFunc] that always returns the given runner. func NewBuilder[T](f BuilderFunc[T]) *Builder[T] Type Parameters: T: process.Runner NewBuilder returns a new [Builder] instance for the given factory function. The function will be called each time [Builder.Run] method is invoked to create a fresh runner instance. func NewGroup(ctx context.Context) *Group NewGroup returns a new [Group] instance that runs processes in the background under the given context. func NewSupervisor(runner process.Runner, exec flaky.Executor, hook Hook) *Supervisor NewSupervisor returns a new [Supervisor] instance for the given runner. Package-Level Variables (total 2, neither is exported) /* 2 unexporteds ... *//* 2 unexporteds: */ var errInterrupt error errInterrupt is an internal error used to distinguish between supervisor interrupts and other errors. var errRecursiveOrConcurrentRun error errRecursiveOrConcurrentRun is an error that [Supervisor] returns on recursive or concurrent Run call.