graceful

Documentation

Overview

Package graceful provides mechanisms to gracefully stop processes on os signals.

Index

• Variables
• func Background(opts ...BackgroundOption) context.Context
• func MaybeDebugf(log Logger, format string, args ...interface{})
• func MaybeErrorf(log Logger, format string, args ...interface{})
• func MaybeInfof(log Logger, format string, args ...interface{})
• func SignalNotify(signals ...os.Signal) chan os.Signal
• func SignalNotifyWithCapacity(capacity int, signals ...os.Signal) chan os.Signal
• func StartForShutdown(ctx context.Context, hosted ...Service) error
• type BackgroundOption
  • func OptBackgroundContext(ctx context.Context) BackgroundOption
  • func OptBackgroundLog(log Logger) BackgroundOption
  • func OptBackgroundSignals(signals ...os.Signal) BackgroundOption
• type BackgroundOptions
• type Graceful
  • func (g Graceful) StartForShutdown(ctx context.Context) error
• type Logger
• type Service

Variables

var DefaultRestartSignals = []os.Signal{
	syscall.SIGHUP,
}

DefaultRestartSignals are the default os signals to capture to restart.

var DefaultShutdownSignals = []os.Signal{
	os.Interrupt, syscall.SIGTERM,
}

DefaultShutdownSignals are the default os signals to capture to shut down.

Functions

func Background

func Background(opts ...BackgroundOption) context.Context

Background yields a context that will signal `<-ctx.Done()` when a signal is sent to the process (as specified in `DefaultShutdownSignals`).

This context will cancel only (1) time.

func MaybeDebugf

func MaybeDebugf(log Logger, format string, args ...interface{})

MaybeDebugf calls the logger debugf method if the logger is set.

func MaybeErrorf

func MaybeErrorf(log Logger, format string, args ...interface{})

MaybeErrorf calls the logger errorf method if the logger is set.

func MaybeInfof

func MaybeInfof(log Logger, format string, args ...interface{})

MaybeInfof calls the logger infof method if the logger is set.

func SignalNotify

func SignalNotify(signals ...os.Signal) chan os.Signal

SignalNotify returns a channel that listens for a given set of os signals.

func SignalNotifyWithCapacity

func SignalNotifyWithCapacity(capacity int, signals ...os.Signal) chan os.Signal

SignalNotifyWithCapacity returns a channel with a given capacity that listens for a given set of os signals.

func StartForShutdown

func StartForShutdown(ctx context.Context, hosted ...Service) error

StartForShutdown is a helper that sets up a graceful hosted process with default signals. You can pass a context to this function to explicitly control shutdown, in addition to setting up notification on process signals.

Types

type BackgroundOption

type BackgroundOption func(*BackgroundOptions)

BackgroundOption mutates background options

func OptBackgroundContext

func OptBackgroundContext(ctx context.Context) BackgroundOption

OptBackgroundSkipStopOnSignal sets if we should stop the signal channel on stop.

func OptBackgroundLog

func OptBackgroundLog(log Logger) BackgroundOption

OptBackgroundLog sets the logger.

func OptBackgroundSignals

func OptBackgroundSignals(signals ...os.Signal) BackgroundOption

OptBackgroundSignals sets the signals.

type BackgroundOptions

type BackgroundOptions struct {
	// Context is a root context, if unset `context.Background()` is used.
	Context context.Context
	// Signals are the specific os signals to intercept.
	Signals []os.Signal
	// Log holds an reference to a graceful logger.
	Log Logger
}

BackgroundOptions are options for the background context.

type Graceful

type Graceful struct {
	Hosted          []Service
	ShutdownSignals []os.Signal
	RestartSignals  []os.Signal
	Log             Logger
}

Graceful is the main entrypoint for hosting graceful processes.

func (Graceful) StartForShutdown

func (g Graceful) StartForShutdown(ctx context.Context) error

StartForShutdown starts, and prepares to gracefully stop, a set hosted processes based on a provided context's cancellation.

The context is used to stop the goroutines this function spawns, as well as call `Stop(...)` on the hosted processes when it cancels.

type Logger

type Logger interface {
	Infof(format string, args ...interface{})
	Debugf(format string, args ...interface{})
	Errorf(format string, args ...interface{})
}

Logger is a type that can be used as a graceful process logger.

type Service

type Service interface {
	Start(context.Context) error // this call must block
	Restart(context.Context) error
	Stop(context.Context) error
}

Service is a server that can start and stop.