shutdown

Documentation

Overview

Package shutdown Providing shutdown callbacks for graceful app shutdow

Installation

To install run:

go get github.com/rose839/IAM/pkg/shutdown

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/rose839/IAM/pkg/shutdown"
	"github.com/rose839/IAM/pkg/shutdown/shutdownmanagers/posixsignal"
)

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

	// add posix shutdown manager
	gs.AddShutdownManager(posixsignal.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/rose839/IAM/pkg/shutdown"
	"github.com/rose839/IAM/pkg/shutdown/shutdownmanagers/posixsignal"
)

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

	// add posix shutdown manager
	gs.AddShutdownManager(posixsignal.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)
}

Index

• 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 ShutdownCallback
• type ShutdownFunc
  • func (sf ShutdownFunc) OnShutdown(shutdownManagerName string) error
• type ShutdownManager

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 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 (sf ShutdownFunc) OnShutdown(shutdownManagerName 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.