Documentation ¶
Overview ¶
Package shutdown provides management of your shutdown process.
The package will enable you to get notifications for your application and handle the shutdown process.
See more information about the how to use it in the README.md file ¶
Package home: https://github.com/eikmadsen/shutdown
Index ¶
- Variables
- type LogPrinter
- type Manager
- func (m *Manager) CancelCtx(parent context.Context) (ctx context.Context, cancel context.CancelFunc)
- func (m *Manager) CancelCtxN(parent context.Context, s Stage) (ctx context.Context, cancel context.CancelFunc)
- func (m *Manager) CompletedCh() <-chan struct{}
- func (m *Manager) First(ctx ...interface{}) Notifier
- func (m *Manager) FirstFn(fn func(), ctx ...interface{}) Notifier
- func (m *Manager) Lock(ctx ...interface{}) func()
- func (m *Manager) OnSignal(exitCode int, sig ...os.Signal)
- func (m *Manager) PreShutdown(ctx ...interface{}) Notifier
- func (m *Manager) PreShutdownFn(fn func(), ctx ...interface{}) Notifier
- func (m *Manager) Second(ctx ...interface{}) Notifier
- func (m *Manager) SecondFn(fn func(), ctx ...interface{}) Notifier
- func (m *Manager) Shutdown()
- func (m *Manager) Started() bool
- func (m *Manager) StartedCh() <-chan struct{}
- func (m *Manager) Third(ctx ...interface{}) Notifier
- func (m *Manager) ThirdFn(fn func(), ctx ...interface{}) Notifier
- func (m *Manager) Wait()
- func (m *Manager) WrapHandler(h http.Handler) http.Handler
- func (m *Manager) WrapHandlerFunc(h http.HandlerFunc) http.HandlerFunc
- type Notifier
- type Option
- func WithLogLockTimeouts(logTimeouts bool) Option
- func WithLogPrinter(fn func(format string, v ...interface{})) Option
- func WithOSExit(b bool) Option
- func WithOnTimeout(fn func(Stage, string)) Option
- func WithStatusTimer(statusTimer time.Duration) Option
- func WithTimeout(d time.Duration) Option
- func WithTimeoutN(s Stage, d time.Duration) Option
- func WithWarningPrefix(s string) Option
- func WithnErrorPrefix(s string) Option
- type Stage
- type Started
- type StartedCh
Constants ¶
This section is empty.
Variables ¶
var ( // StagePS indicates the pre shutdown stage when waiting for locks to be released. StagePS = Stage{0} // Stage1 Indicates first stage of timeouts. Stage1 = Stage{1} // Stage2 Indicates second stage of timeouts. Stage2 = Stage{2} // Stage3 indicates third stage of timeouts. Stage3 = Stage{3} )
Functions ¶
This section is empty.
Types ¶
type LogPrinter ¶
type LogPrinter interface {
Printf(format string, v ...interface{})
}
LogPrinter is an interface for writing logging information. The writer must handle concurrent writes.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager encapsulates all state/settings previously stored at package level
func (*Manager) CancelCtx ¶
func (m *Manager) CancelCtx(parent context.Context) (ctx context.Context, cancel context.CancelFunc)
CancelCtx will cancel the supplied context when shutdown starts. The returned context must be cancelled when done similar to https://golang.org/pkg/context/#WithCancel
func (*Manager) CancelCtxN ¶
func (m *Manager) CancelCtxN(parent context.Context, s Stage) (ctx context.Context, cancel context.CancelFunc)
CancelCtxN will cancel the supplied context at a supplied shutdown stage. The returned context must be cancelled when done similar to https://golang.org/pkg/context/#WithCancel
func (*Manager) CompletedCh ¶
func (m *Manager) CompletedCh() <-chan struct{}
CompletedCh returns a channel that will be closed when shutdown has completed
func (*Manager) First ¶
First returns a notifier that will be called in the first stage of shutdowns. If shutdown has started and this stage has already been reached, the notifiers Valid() will be false. The context is printed if LogLockTimeouts is enabled.
func (*Manager) FirstFn ¶
FirstFn executes a function in the first stage of the shutdown If shutdown has started and this stage has already been reached, the notifiers Valid() will be false. The context is printed if LogLockTimeouts is enabled.
func (*Manager) Lock ¶
func (m *Manager) Lock(ctx ...interface{}) func()
Lock will signal that you have a function running, that you do not want to be interrupted by a shutdown.
The lock is created with a timeout equal to the length of the preshutdown stage at the time of creation. When that amount of time has expired the lock will be removed, and a warning will be printed.
If the function returns nil shutdown has already been initiated, and you did not get a lock. You should therefore not call the returned function.
If the function did not return nil, you should call the function to unlock the lock.
You should not hold a lock when you start a shutdown.
For easier debugging you can send a context that will be printed if the lock times out. All supplied context is printed with '%v' formatting.
func (*Manager) OnSignal ¶
OnSignal will start the shutdown when any of the given signals arrive
A good shutdown default is
shutdown.OnSignal(0, os.Interrupt, syscall.SIGTERM)
which will do shutdown on Ctrl+C and when the program is terminated.
func (*Manager) PreShutdown ¶
PreShutdown will return a Notifier that will be fired as soon as the shutdown. is signalled, before locks are released. This allows to for instance send signals to upstream servers not to send more requests. The context is printed if LogLockTimeouts is enabled.
func (*Manager) PreShutdownFn ¶
PreShutdownFn registers a function that will be called as soon as the shutdown. is signalled, before locks are released. This allows to for instance send signals to upstream servers not to send more requests. The context is printed if LogLockTimeouts is enabled.
func (*Manager) Second ¶
Second returns a notifier that will be called in the second stage of shutdowns. If shutdown has started and this stage has already been reached, the notifiers Valid() will be false. The context is printed if LogLockTimeouts is enabled.
func (*Manager) SecondFn ¶
SecondFn executes a function in the second stage of the shutdown. If shutdown has started and this stage has already been reached, the notifiers Valid() will be false. The context is printed if LogLockTimeouts is enabled.
func (*Manager) Shutdown ¶
func (m *Manager) Shutdown()
Shutdown will signal all notifiers in three stages. It will first check that all locks have been released - see Lock() This method is not safe to call concurrently, as a datarace for shutdownRequested is possible. As shutdown is called
func (*Manager) Started ¶
Started returns true if shutdown has been started. Note that shutdown can have been started before you check the value.
func (*Manager) StartedCh ¶
func (m *Manager) StartedCh() <-chan struct{}
StartedCh returns a channel that is closed once shutdown has started.
func (*Manager) Third ¶
Third returns a notifier that will be called in the third stage of shutdowns. If shutdown has started and this stage has already been reached, the notifiers Valid() will be false. The context is printed if LogLockTimeouts is enabled.
func (*Manager) ThirdFn ¶
ThirdFn executes a function in the third stage of the shutdown. If shutdown has started and this stage has already been reached, the notifiers Valid() will be false. The context is printed if LogLockTimeouts is enabled.
func (*Manager) Wait ¶
func (m *Manager) Wait()
Wait will wait until shutdown has finished. This can be used to keep a main function from exiting until shutdown has been called, either by a goroutine or a signal.
func (*Manager) WrapHandler ¶
WrapHandler will return an http Handler That will lock shutdown until all have completed and will return http.StatusServiceUnavailable if shutdown has been initiated.
func (*Manager) WrapHandlerFunc ¶
func (m *Manager) WrapHandlerFunc(h http.HandlerFunc) http.HandlerFunc
WrapHandlerFunc will return an http.HandlerFunc that will lock shutdown until all have completed. The handler will return http.StatusServiceUnavailable if shutdown has been initiated.
type Notifier ¶
type Notifier struct {
// contains filtered or unexported fields
}
Notifier is a channel, that will be sent a channel once the application shuts down. When you have performed your shutdown actions close the channel you are given.
func (Notifier) Cancel ¶
func (s Notifier) Cancel()
Cancel a Notifier. This will remove a notifier from the shutdown queue, and it will not be signalled when shutdown starts. If the shutdown has already started this will not have any effect, but a goroutine will wait for the notifier to be triggered.
func (Notifier) CancelWait ¶
func (s Notifier) CancelWait()
CancelWait will cancel a Notifier, or wait for it to become active if shutdown has been started. This will remove a notifier from the shutdown queue, and it will not be signalled when shutdown starts. If the notifier is invalid (requested after its stage has started), it will return at once. If the shutdown has already started, this will wait for the notifier to be called and close it.
type Option ¶
type Option func(*Manager)
func WithLogLockTimeouts ¶
WithLogLockTimeouts toggles logging timeouts. Default: true
func WithLogPrinter ¶
WithLogPrinter sets the logprinter
func WithOnTimeout ¶
WithOnTimeout allows you to get a notification if a shutdown stage times out. The stage and the context of the hanging shutdown/lock function is returned.
func WithStatusTimer ¶
WithStatusTimer is the time between logging which notifiers are waiting to finish.
func WithTimeout ¶
WithTimeout sets maximum delay to wait for each stage to finish. When the timeout has expired for a stage the next stage will be initiated.
func WithTimeoutN ¶
WithTimeoutN set maximum delay to wait for a specific stage to finish. When the timeout expired for a stage the next stage will be initiated. The stage can be obtained by using the exported variables called 'Stage1, etc.
func WithWarningPrefix ¶
WithWarningPrefix is printed before warnings.
func WithnErrorPrefix ¶
WithErrorPrefix is printed before errors.