README
¶
Gograce
gograce let's you run your programs gracefully managing signal handling, cleanup timeouts and force quit for you.
Usage
package main
import (
"context"
"github.com/itzloop/gograce"
"time"
)
func main() {
grace := gograce.NewGraceful(gograce.Options{
// Timeout sets a hard deadline for cleanup phase. If time out is specified,
// gograce will wait for that amount and then terminates forcefully
Timeout: 10 * time.Second,
// This controls whether or not sending terminate signal twice will forcefully
// terminate the application
NoForceQuit: false,
// Setting this will limit the number of go-routines running at the same time.
MaxGoRoutines: 0,
// Setting this will overwrite the default signals
Signals: nil,
})
app := App{}
grace.GoWithContext(app.Start)
grace.GoWithContext(app.Close)
grace.FatalWait()
}
type App struct{}
func (app *App) Start(ctx context.Context) error {
// run stuff
}
func (app *App) Close(ctx context.Context) error {
<-ctx.Done()
// do cleanup
}
For more information on how to use it refer to examples readme.
Testing
$ go test -v ./...
Contributing
TODO
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Graceful ¶
type Graceful struct {
// contains filtered or unexported fields
}
func NewGraceful ¶
NewGraceful calls NewGracefulWithContext with context.Background()
func NewGracefulWithContext ¶
NewGracefulWithContext will create a SignalHandler and a TimeoutHandler which are started automatically.
func (*Graceful) FatalWait ¶
func (grace *Graceful) FatalWait()
FatalWait calls Wait but log.Fatals when an error is received
func (*Graceful) GoWithContext ¶
GoWithContext is convenient wrapper for (*errgroup.Group).Go that accepts a functions that takes a context as input instead of not having any input.
type Options ¶
type Options struct {
// Timeout defines how long should the program wait before forcefully exiting.
// a zero-value indicates no timeout.
Timeout time.Duration
// NoForceQuit disables the force quit feature. After the first termination signal, any further signals
// will be ignored.
NoForceQuit bool
// MaxGoRoutines defines how many go-routines can be started. This value is passed to SetLimit on errgroup.Group.
// a zero-value or negative indicates no limit.
MaxGoRoutines int
// TODO custom signals?
// Signals let's you overwrite graceful.defaultSignals.
// a zero-value or an empty slice indicate no overwrite
Signals []os.Signal
}
type SignalHandler ¶
type SignalHandler struct {
// contains filtered or unexported fields
}
A SignalHandler listens for signals and handles graceful and forceful shutdown When a signal has been sent twice SignalHandler will call forceFunc. Default forceFunc is os.Exit(1) so application will terminate.
func NewSignalHandler ¶
func NewSignalHandler(ctx context.Context, opts SignalHandlerOptions) (*SignalHandler, context.Context)
NewSignalHandler will create a signal handler based on the desired opts given. It will then start the signal handler as well.
func (*SignalHandler) Close ¶
func (sh *SignalHandler) Close()
Close closes sigChan. Calls to close only work when SignalHandler has been started and other wise it has no effect. It is also safe to call it from multiple go-routines.
func (*SignalHandler) Start ¶
func (s *SignalHandler) Start(ctx context.Context) context.Context
Start will start the SignalHandler by listening to signals and parent context. If at anypoint parent context gets canceled, Start will return. It is safe but useless to call Start from multiple go-routines because it will start it the first and you have to Close it first to be able to Start it again.
type SignalHandlerOptions ¶
type SignalHandlerOptions struct {
// Force enables quiting forcefully (by sending one of the Signals twice)
// when graceful shutdown is in progress
Force bool
// Signals overwrites the defaultSignals.
Signals []os.Signal
// ForceFunc is called when Force = true and one of the Signals is sent twice.
// If ForceFunc is nil, defaultForceFunc will be used which is os.Exit(1).
ForceFunc ForceFunc
}
SignalHandlerOptions
type TimeoutHandler ¶
type TimeoutHandler struct {
// contains filtered or unexported fields
}
TimeoutHandler will set a hard limit for graceful shutdown. If that limit is reached the program will call timeoutFunc. defaultTimeoutFunc is os.Exit(1) so this will terminate the application.
func NewTimeoutHandler ¶
func NewTimeoutHandler(ctx context.Context, opts TimeoutHandlerOptions) *TimeoutHandler
NewTimeoutHandler
func (*TimeoutHandler) Start ¶
func (th *TimeoutHandler) Start(ctx context.Context)
type TimeoutHandlerOptions ¶
type TimeoutHandlerOptions struct {
// Timeout is the value that is passed to time.AfterFunc.
Timeout time.Duration
// TimeoutFunc is the function that is passed to time.AfterFunc.
TimeoutFunc TimeoutFunc
}
TimeoutHandlerOptions
Source Files
Directories