Documentation
¶
Overview ¶
Package graceful provides a graceful start and shutdown insturmentation for go programs based on a simple Plugin interface.
It supports
- graceful shutdown of plugins
- timeout for plugins to shutdown
- os.Signals to listen for (defaults to os.Interrupt and syscall.SIGTERM)
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrRunnerNotStarted = errors.New("server not started") ErrRunnerAlreadyStarted = errors.New("server already started") )
Functions ¶
This section is empty.
Types ¶
type Plugin ¶
type Plugin interface {
// Name returns the name of the plugin. This can be any identifier you like and
// will only be used for logging and debugging purposes.
Name() string
// Start starts the plugin with the context provided for cancellation.
// if the context is cancelled, the plugin should stop, cleanup and return.
// The start method _should_ be blocking, until the context is cancelled.
// If the plugin terminates early with an error, it will cause a shutdown
// in the system.
//
// Errors during shutdown should be logged within your plugin. Errors
// that occur during the shutdown process will be ignored by the server.
//
// Example:
// func (p *MyPlugin) Start(ctx context.Context) error {
// // do something
// <-ctx.Done()
// // cleanup / logging
// return nil
// }
Start(ctx context.Context) error
}
Plugin defines the interface for a plugin that can be started and stopped via the Runner. The plugin should be blocking until the context is cancelled. Note that startup order for plugins is non-deterministic and should not be relied upon. If you need to will need to manage coordination between plugins.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner is the orchestrator of the plugins provided. It will start and cancel the plugins based on the context and os.Signals provided.
func NewRunner ¶
func NewRunner(opts ...RunnerOptFunc) *Runner
func (*Runner) AddFunc ¶ added in v0.0.9
AddFunc adds a function as a plugin to the server during construction. This is useful for quick plugin creation and for passing structs that only provide the Start method.
Example:
svr.AddFunc("my-plugin", func(ctx context.Context) error {
// do something
<-ctx.Done()
// cleanup / logging
return nil
}
func (*Runner) AddPlugin ¶
AddPlugin adds a plugin to the server during construction. This returns the server for chaining.
func (*Runner) Shutdown ¶
func (svr *Runner) Shutdown()
Shutdown sends a signal to the server to stop all plugins and the server itself. This function returns immediately after the signal is sent.
type RunnerOptFunc ¶
type RunnerOptFunc func(*runnerOpts)
func WithPrintln ¶
func WithPrintln(fn func(...any)) RunnerOptFunc
WithPrintln provides a function to print messages
func WithSignals ¶
func WithSignals(signals ...os.Signal) RunnerOptFunc
WithSignals provides a list of signals to listen for when starting the server that will cancel the context
Defaults to
- os.Interrupt
- syscall.SIGTERM
Multiple calls to this option will override the previous
func WithTimeout ¶
func WithTimeout(timeout time.Duration) RunnerOptFunc
WithTimeout provides a timeout for the server to wait for plugins to stop before shutting down.
Defaults to 5 seconds
Source Files