shutdown

README

shutdown

English | 中文

Providing shutdown callbacks for graceful app shutdown

Installation

go get github.com/seacraft/shutdown

Documentation

github.com/seacraft/shutdown documentation is available on godoc.

• PosixSignalManager

Example - POSIX signals

Graceful shutdown will listen for posix SIGINT and SIGTERM signals. When they are received it will run all callbacks in separate go routines. When callbacks return, the application will exit with os.Exit(0)

package main

import (
	"fmt"
	"time"

	"github.com/seacraft/shutdown"
)

func main() {
	// initialize shutdown
	gs := shutdown.New()

	// add posix shutdown manager
	gs.AddShutdownManager(shutdown.NewPosixSignalManager())

	// add your tasks that implement ShutdownCallback
	gs.AddShutdownCallback(shutdown.ShutdownFunc(func(string) error {
		fmt.Println("Shutdown callback start")
		time.Sleep(time.Second)
		fmt.Println("Shutdown callback finished")
		return nil
	}))

	// start shutdown managers
	if err := gs.Start(); err != nil {
		fmt.Println("Start:", err)
		return
	}

	// do other stuff
	time.Sleep(time.Hour)
}

Example - posix signals with error handler

The same as above, except now we set an ErrorHandler that prints the error returned from ShutdownCallback.

package main

import (
	"fmt"
	"time"
	"errors"

	"github.com/seacraft/shutdown"
)

func main() {
	// initialize shutdown
	gs := shutdown.New()

	// add posix shutdown manager
	gs.AddShutdownManager(shutdown.NewPosixSignalManager())

	// set error handler
	gs.SetErrorHandler(shutdown.ErrorFunc(func(err error) {
		fmt.Println("Error:", err)
	}))

	// add your tasks that implement ShutdownCallback
	gs.AddShutdownCallback(shutdown.ShutdownFunc(func(string) error {
		fmt.Println("Shutdown callback start")
		time.Sleep(time.Second)
		fmt.Println("Shutdown callback finished")
		return errors.New("my-error")
	}))

	// start shutdown managers
	if err := gs.Start(); err != nil {
		fmt.Println("Start:", err)
		return
	}

	// do other stuff
	time.Sleep(time.Hour)
}

Licence

See LICENSE file in the root of the repository.

Documentation

Overview

Package posixsignal provides a listener for a posix signal. By default it listens for SIGINT and SIGTERM, but others can be chosen in NewPosixSignalManager. When ShutdownFinish is called it exits with os.Exit(0)

Index

• Constants
• type ErrorFunc
  • func (f ErrorFunc) OnError(err error)
• type ErrorHandler
• type GSInterface
• type GracefulShutdown
  • func New() *GracefulShutdown
  • func (gs *GracefulShutdown) AddShutdownCallback(shutdownCallback ShutdownCallback)
  • func (gs *GracefulShutdown) AddShutdownManager(manager ShutdownManager)
  • func (gs *GracefulShutdown) ReportError(err error)
  • func (gs *GracefulShutdown) SetErrorHandler(errorHandler ErrorHandler)
  • func (gs *GracefulShutdown) Start() error
  • func (gs *GracefulShutdown) StartShutdown(sm ShutdownManager)
• type PosixSignalManager
  • func NewPosixSignalManager(sig ...os.Signal) *PosixSignalManager
  • func (posixSignalManager *PosixSignalManager) GetName() string
  • func (posixSignalManager *PosixSignalManager) ShutdownFinish() error
  • func (posixSignalManager *PosixSignalManager) ShutdownStart() error
  • func (posixSignalManager *PosixSignalManager) Start(gs GSInterface) error
• type ShutdownCallback
• type ShutdownFunc
  • func (f ShutdownFunc) OnShutdown(shutdownManager string) error
• type ShutdownManager

Constants

const Name = "PosixSignalManager"

Name defines shutdown ShutdownManager name.

Types

type ErrorFunc

type ErrorFunc func(err error)

ErrorFunc is a helper type, so you can easily provide anonymous functions as ErrorHandlers.

func (ErrorFunc) OnError

func (f ErrorFunc) OnError(err error)

OnError defines the action needed to run when error occurred.

type ErrorHandler

type ErrorHandler interface {
	OnError(err error)
}

ErrorHandler is an interface you can pass to SetErrorHandler to handle asynchronous errors.

type GSInterface

type GSInterface interface {
	StartShutdown(sm ShutdownManager)
	ReportError(err error)
	AddShutdownCallback(shutdownCallback ShutdownCallback)
}

GSInterface is an interface implemented by GracefulShutdown, that gets passed to ShutdownManager to call StartShutdown when shutdown is requested.

type GracefulShutdown

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

GracefulShutdown is main struct that handles ShutdownCallbacks and ShutdownManagers. Initialize it with New.

func New

func New() *GracefulShutdown

New initializes GracefulShutdown.

func (*GracefulShutdown) AddShutdownCallback

func (gs *GracefulShutdown) AddShutdownCallback(shutdownCallback ShutdownCallback)

AddShutdownCallback adds a ShutdownCallback that will be called when shutdown is requested.

You can provide anything that implements ShutdownCallback interface, or you can supply a function like this:

AddShutdownCallback(shutdown.ShutdownFunc(func() error {
	// callback code
	return nil
}))

func (*GracefulShutdown) AddShutdownManager

func (gs *GracefulShutdown) AddShutdownManager(manager ShutdownManager)

AddShutdownManager adds a ShutdownManager that will listen to shutdown requests.

func (*GracefulShutdown) ReportError

func (gs *GracefulShutdown) ReportError(err error)

ReportError is a function that can be used to report errors to ErrorHandler. It is used in ShutdownManagers.

func (*GracefulShutdown) SetErrorHandler

func (gs *GracefulShutdown) SetErrorHandler(errorHandler ErrorHandler)

SetErrorHandler sets an ErrorHandler that will be called when an error is encountered in ShutdownCallback or in ShutdownManager.

You can provide anything that implements ErrorHandler interface, or you can supply a function like this:

SetErrorHandler(shutdown.ErrorFunc(func (err error) {
	// handle error
}))

func (*GracefulShutdown) Start

func (gs *GracefulShutdown) Start() error

Start calls Start on all added ShutdownManagers. The ShutdownManagers start to listen to shutdown requests. Returns an error if any ShutdownManagers return an error.

func (*GracefulShutdown) StartShutdown

func (gs *GracefulShutdown) StartShutdown(sm ShutdownManager)

StartShutdown is called from a ShutdownManager and will initiate shutdown. first call ShutdownStart on Shutdownmanager, call all ShutdownCallbacks, wait for callbacks to finish and call ShutdownFinish on ShutdownManager.

type PosixSignalManager

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

PosixSignalManager implements ShutdownManager interface that is added to GracefulShutdown. Initialize with NewPosixSignalManager.

func NewPosixSignalManager

func NewPosixSignalManager(sig ...os.Signal) *PosixSignalManager

NewPosixSignalManager initializes the PosixSignalManager. As arguments you can provide os.Signal-s to listen to, if none are given, it will default to SIGINT and SIGTERM.

func (*PosixSignalManager) GetName

func (posixSignalManager *PosixSignalManager) GetName() string

GetName returns name of this ShutdownManager.

func (*PosixSignalManager) ShutdownFinish

func (posixSignalManager *PosixSignalManager) ShutdownFinish() error

ShutdownFinish exits the app with os.Exit(0).

func (*PosixSignalManager) ShutdownStart

func (posixSignalManager *PosixSignalManager) ShutdownStart() error

ShutdownStart does nothing.

func (*PosixSignalManager) Start

func (posixSignalManager *PosixSignalManager) Start(gs GSInterface) error

Start starts listening for posix signals.

type ShutdownCallback

type ShutdownCallback interface {
	OnShutdown(string) error
}

ShutdownCallback is an interface you have to implement for callbacks. OnShutdown will be called when shutdown is requested. The parameter is the name of the ShutdownManager that requested shutdown.

type ShutdownFunc

type ShutdownFunc func(string) error

ShutdownFunc is a helper type, so you can easily provide anonymous functions as ShutdownCallbacks.

func (ShutdownFunc) OnShutdown

func (f ShutdownFunc) OnShutdown(shutdownManager string) error

OnShutdown defines the action needed to run when shutdown triggered.

type ShutdownManager

type ShutdownManager interface {
	GetName() string
	Start(gs GSInterface) error
	ShutdownStart() error
	ShutdownFinish() error
}

ShutdownManager is an interface implemnted by ShutdownManagers. GetName returns the name of ShutdownManager. ShutdownManagers start listening for shutdown requests in Start. When they call StartShutdown on GSInterface, first ShutdownStart() is called, then all ShutdownCallbacks are executed and once all ShutdownCallbacks return, ShutdownFinish is called.