closer

README

Closer

The aim of this package is to provide an universal way to catch the event of application’s exit and perform some actions before it’s too late. closer doesn’t care about the way application tries to exit, i.e. was that a panic or just a signal from the OS, it calls the provided methods for cleanup and that’s the whole point.

Usage

Be careful, this package is using the singleton pattern (like net/http does) and doesn't require any initialisation step. However, there’s an option to provide a custom configuration struct.

// Init allows user to override the defaults (a set of OS signals to watch for, for example).
func Init(cfg Config)

// Close sends a close request.
// The app will be terminated by OS as soon as the first close request will be handled by closer, this
// function will return no sooner. The exit code will always be 0 (success).
func Close()

// Bind will register the cleanup function that will be called when closer will get a close request.
// All the callbacks will be called in the reverse order they were bound, that's similar to how `defer` works.
func Bind(cleanup func())

// Checked runs the target function and checks for panics and errors it may yield. In case of panic or error, closer
// will terminate the app with an error code, but either case it will call all the bound callbacks beforehand.
// One can use this instead of `defer` if you need to care about errors and panics that always may happen.
// This function optionally can emit log messages via standard `log` package.
func Checked(target func() error, logging bool)

// Hold is a helper that may be used to hold the main from returning,
// until the closer will do a proper exit via `os.Exit`.
func Hold()

The the usage examples: example, example-error and example-panic.

Table of exit codes

All errors and panics will be logged if the logging option of closer.Checked was set true, also the exit code (for os.Exit) will be determined accordingly:

Event	Default exit code
error = nil	0 (success)
error != nil	1 (failure)
panic	1 (failure)

License

MIT

Documentation

Overview

Package closer ensures a clean exit for your Go app.

The aim of this package is to provide an universal way to catch the event of application’s exit and perform some actions before it’s too late. Closer doesn’t care about the way application tries to exit, i.e. was that a panic or just a signal from the OS, it calls the provided methods for cleanup and that’s the whole point.

Exit codes

All errors and panics will be logged if the logging option of `closer.Checked` was set true, also the exit code (for `os.Exit`) will be determined accordingly:

Event         | Default exit code
------------- | -------------
error = nil   | 0 (success)
error != nil  | 1 (failure)
panic         | 1 (failure)

Index

• Variables
• func Bind(cleanup func())
• func Checked(target func() error, logging bool)
• func Close()
• func Exit(code int)
• func Fatalf(format string, v ...interface{})
• func Fatalln(v ...interface{})
• func Hold()
• func Init(cfg Config)
• type Config
• type StackFrame
  • func (frame *StackFrame) Func() *runtime.Func
  • func (frame *StackFrame) SourceLine() (string, error)
  • func (frame *StackFrame) String() string

Variables

var (
	// DebugSignalSet is a predefined list of signals to watch for. Usually
	// these signals will terminate the app without executing the code in defer blocks.
	DebugSignalSet = []os.Signal{
		syscall.SIGINT,
		syscall.SIGHUP,
		syscall.SIGTERM,
	}
	// DefaultSignalSet will have syscall.SIGABRT that should be
	// opted out if user wants to debug the stacktrace.
	DefaultSignalSet = append(DebugSignalSet, syscall.SIGABRT)
)

var (
	// ExitCodeOK is a successfull exit code.
	ExitCodeOK = 0
	// ExitCodeErr is a failure exit code.
	ExitCodeErr = 1
	// ExitSignals is the active list of signals to watch for.
	ExitSignals = DefaultSignalSet
)

Functions

func Bind

func Bind(cleanup func())

Bind will register the cleanup function that will be called when closer will get a close request. All the callbacks will be called in the reverse order they were bound, that's similar to how `defer` works.

func Checked

func Checked(target func() error, logging bool)

Checked runs the target function and checks for panics and errors it may yield. In case of panic or error, closer will terminate the app with an error code, but either case it will call all the bound callbacks beforehand. One can use this instead of `defer` if you need to care about errors and panics that always may happen. This function optionally can emit log messages via standard `log` package.

func Close

func Close()

Close sends a close request. The app will be terminated by OS as soon as the first close request will be handled by closer, this function will return no sooner. The exit code will always be 0 (success).

func Exit

func Exit(code int)

Exit is the same as os.Exit but respects the closer's logic. It converts any error code into ExitCodeErr (= 1, by default).

func Fatalf

func Fatalf(format string, v ...interface{})

Fatalf works the same as log.Fatalf but respects the closer's logic.

func Fatalln

func Fatalln(v ...interface{})

Fatalln works the same as log.Fatalln but respects the closer's logic.

func Hold

func Hold()

Hold is a helper that may be used to hold the main from returning, until the closer will do a proper exit via `os.Exit`.

func Init

func Init(cfg Config)

Init allows user to override the defaults (a set of OS signals to watch for, for example).

Types

type Config

type Config struct {
	ExitCodeOK  int
	ExitCodeErr int
	ExitSignals []os.Signal
}

Config should be used with Init function to override the defaults.

type StackFrame

type StackFrame struct {
	File           string
	LineNumber     int
	Name           string
	Package        string
	ProgramCounter uintptr
}

A StackFrame contains all necessary information about to generate a line in a callstack.

func (*StackFrame) Func

func (frame *StackFrame) Func() *runtime.Func

Func returns the function that this stackframe corresponds to

func (*StackFrame) SourceLine

func (frame *StackFrame) SourceLine() (string, error)

SourceLine gets the line of code (from File and Line) of the original source if possible

func (*StackFrame) String

func (frame *StackFrame) String() string

String returns the stackframe formatted in the same way as go does in runtime/debug.Stack()