stopper

Documentation

Overview

Package stopper contains a utility class for gracefully terminating long-running processes.

Index

• Variables
• func IsStopping(ctx context.Context) bool
• type Context
  • func Background() *Context
  • func From(ctx context.Context) *Context
  • func WithContext(ctx context.Context) *Context
  • func (s *Context) Deadline() (deadline time.Time, ok bool)
  • func (s *Context) Defer(fn func())
  • func (s *Context) Done() <-chan struct{}
  • func (s *Context) Err() error
  • func (s *Context) Go(fn func() error) (accepted bool)
  • func (s *Context) IsStopping() bool
  • func (s *Context) Stop(gracePeriod time.Duration)
  • func (s *Context) Stopping() <-chan struct{}
  • func (s *Context) Value(key any) any
  • func (s *Context) Wait() error

Variables

var ErrGracePeriodExpired = errors.New("grace period expired")

ErrGracePeriodExpired will be returned from context.Cause when the Context has been stopped, but the goroutines have not exited.

var ErrStopped = errors.New("stopped")

ErrStopped will be returned from context.Cause when the Context has been stopped.

Functions

func IsStopping

func IsStopping(ctx context.Context) bool

IsStopping is a convenience method to determine if a stopper is associated with a Context and if work should be stopped.

Types

type Context

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

A Context is conceptually similar to an [errgroup.Group] in that it manages a context.Context whose lifecycle is associated with some number of goroutines. Rather than canceling the associated context when a goroutine returns an error, it cancels the context after the Stop method is called and all associated goroutines have all exited.

As an API convenience, the Context type implements context.Context so that it fits into idiomatic context-plumbing. The From function can be used to retrieve a Context from any context.Context.

func Background

func Background() *Context

Background is analogous to context.Background. It returns a Context which cannot be stopped or canceled, but which is otherwise functional.

func From

func From(ctx context.Context) *Context

From returns a pre-existing Context from the Context chain. Use WithContext to construct a new Context.

If the chain is not associated with a Context, the Background instance will be returned.

func WithContext

func WithContext(ctx context.Context) *Context

WithContext creates a new Context whose work will be immediately canceled when the parent context is canceled. If the provided context is already managed by a Context, a call to the enclosing Context.Stop method will also trigger a call to Stop in the newly-constructed Context.

func (*Context) Deadline

func (s *Context) Deadline() (deadline time.Time, ok bool)

Deadline implements context.Context.

func (*Context) Defer

func (s *Context) Defer(fn func())

Defer registers a callback that will be executed after the Context.Done channel is closed. This method can be used to clean up resources that are used by goroutines associated with the Context (e.g. closing database connections). The Context will already have been canceled by the time the callback is run, so its behaviors should be associated with a background context. Callbacks will be executed in a LIFO manner. If the context has already stopped, the callback will be executed immediately.

Calling this method on the Background context will panic, since that context can never be cancelled.

func (*Context) Done

func (s *Context) Done() <-chan struct{}

Done implements context.Context. The channel that is returned will be closed when Stop has been called and all associated goroutines have exited. The returned channel will be closed immediately if the parent context (passed to WithContext) is canceled. Functions passed to Context.Go should prefer Context.Stopping instead.

func (*Context) Err

func (s *Context) Err() error

Err implements context.Context. When the return value for this is context.ErrCanceled, context.Cause will return ErrStopped if the context cancellation resulted from a call to Stop.

func (*Context) Go

func (s *Context) Go(fn func() error) (accepted bool)

Go spawns a new goroutine to execute the given function and monitors its lifecycle.

If the function returns an error, the Stop method will be called. The returned error will be available from Wait once the remaining goroutines have exited.

This method will not execute the function and return false if Stop has already been called.

The function passed to Go should prefer the Context.Stopping channel to return instead of depending on Context.Done. This allows a soft-stop, rather than waiting for the grace period to expire when Context.Stop is called.

func (*Context) IsStopping

func (s *Context) IsStopping() bool

IsStopping returns true once [Stop] has been called. See also [Stopping] for a notification-based API.

func (*Context) Stop

func (s *Context) Stop(gracePeriod time.Duration)

Stop begins a graceful shutdown of the Context. When this method is called, the Stopping channel will be closed. Once all goroutines started by Go have exited, the associated Context will be cancelled, thus closing the Done channel. If the gracePeriod is non-zero, the context will be forcefully cancelled if the goroutines have not exited within the given timeframe.

func (*Context) Stopping

func (s *Context) Stopping() <-chan struct{}

Stopping returns a channel that is closed when a graceful shutdown has been requested or when the parent context has been canceled.

func (*Context) Value

func (s *Context) Value(key any) any

Value implements context.Context.

func (*Context) Wait

func (s *Context) Wait() error

Wait will block until Stop has been called and all associated goroutines have exited or the parent context has been cancelled. This method will return the first, non-nil error from any of the callbacks passed to Go. If Wait is called on the Background instance, it will immediately return nil.