sigmon

README

sigmon

go get -u github.com/codemodus/sigmon

Package sigmon simplifies os.Signal handling.

The benefits of this over a more simplistic approach are eased signal bypassability, eased signal handling replaceability, the rectification of system signal quirks, and operating system portability (Windows will ignore USR1 and USR2 signals, and some testing is bypassed).

Usage

type HandlerFunc
type Signal
type SignalMonitor
    func New(fn HandlerFunc) *SignalMonitor
    func (m *SignalMonitor) Set(fn HandlerFunc)
    func (m *SignalMonitor) Start()
    func (m *SignalMonitor) Stop()
type State
    func (s *State) Signal() Signal

Setup

import (
    "github.com/codemodus/sigmon/v2"
)

func main() {
    sm := sigmon.New(nil)
    sm.Start()

    // Do things which cannot be affected by OS signals other than SIGKILL...

    sm.Set(handle)

    // Do things which can be affected by handled OS signals...

    sm.Stop()
    // OS signals will be handled normally.
}

HandlerFunc

func handle(s *sigmon.State) {
    switch s.Signal() {
    case sigmon.SIGHUP:
        // reload
    case sigmon.SIGINT, sigmon.SIGTERM:
        // stop
    case sigmon.SIGUSR1, sigmon.SIGUSR2:
        // more
    }
}

Setup Elaborated

func main() {
    sm := sigmon.New(nil)
    sm.Start()

    db := newDataBase(creds)
    db.Migrate()

    app := newWebApp(db)
    app.ListenAndServe()

    sm.Set(func(s *sigmon.State) {
        switch s.Signal() {
        case sigmon.SIGHUP:
            app.Restart()
        default:
            app.Shutdown()
        }
    })

    app.Wait()
}

HandlerFunc Using syscall Signal Constants

func handle(s *sigmon.State) {
    switch syscall.Signal(s.Signal()) {
    case syscall.SIGHUP:
        // reload
    default:
        // stop
    }
}

More Info

Windows Compatibility

sigmon will run on Windows systems without error. In order for this to be, notifications of USR1 and USR2 signals are not wired up as they are not supported whatsoever in Windows. All tests work on *nix systems, but are not run on Windows. It is up to the user to assess whether their application is receiving INT, TERM, and, HUP signals properly along with what that may mean for the design of the affected system.

Documentation

View the GoDoc

Benchmarks

N/A

Documentation

Overview

Package sigmon simplifies os.Signal handling.

The benefits of this over a more simplistic approach are eased signal bypassability, eased signal handling replaceability, the rectification of system signal quirks, and operating system portability (Windows will ignore USR1 and USR2 signals, and some testing is bypassed).

Example

sm := sigmon.New(nil)
sm.Start()

// Do things which cannot be affected by OS signals other than SIGKILL...

sm.Set(handle)

// Do things which can be affected by handled OS signals...

sm.Stop()
// OS signals will be handled normally.

Example (Elaborated)

sm := sigmon.New(nil)
sm.Start()

db := newDataBase(creds)
db.Migrate()

app := newWebApp(db)
app.ListenAndServe()

sm.Set(func(s *sigmon.State) {
	switch s.Signal() {
	case sigmon.SIGHUP:
		app.Restart()
	default:
		app.Shutdown()
	}
})

app.Wait()

Example (HandlerFunc)

handle = func(s *sigmon.State) {
	switch s.Signal() {
	case sigmon.SIGHUP:
		server.Restart()
	default:
		server.Shutdown()
	}
}

Example (HandlerFuncSyscall)

handle = func(s *sigmon.State) {
	switch syscall.Signal(s.Signal()) {
	case syscall.SIGHUP:
		server.Restart()
	default:
		server.Shutdown()
	}
}

Index

• Constants
• type HandlerFunc
• type Signal
  • func (s Signal) String() string
• type SignalMonitor
  • func New(fn HandlerFunc) *SignalMonitor
  • func (m *SignalMonitor) Set(fn HandlerFunc)
  • func (m *SignalMonitor) Start()
  • func (m *SignalMonitor) Stop()
• type State
  • func (s *State) Signal() Signal

Examples

• Package
• Package (Elaborated)
• Package (HandlerFunc)
• Package (HandlerFuncSyscall)

Constants

const (
	SIGHUP  = Signal(syscall.SIGHUP)
	SIGINT  = Signal(syscall.SIGINT)
	SIGTERM = Signal(syscall.SIGTERM)
	SIGUSR1 = Signal(syscall.SIGUSR1)
	SIGUSR2 = Signal(syscall.SIGUSR2)
)

Signal constants define handled system signals.

Types

type HandlerFunc

type HandlerFunc func(*State)

HandlerFunc is used to communicate system signal handling behavior.

type Signal

type Signal syscall.Signal

Signal represents handled system signals.

func (Signal) String

func (s Signal) String() string

type SignalMonitor

type SignalMonitor struct {
	sync.Mutex
	// contains filtered or unexported fields
}

SignalMonitor helps manage system signal handling.

func New

func New(fn HandlerFunc) *SignalMonitor

New allocates a new SignalMonitor and related helper types, and returns the SignalMonitor. When a nil arg is provided, no action will be taken during signal handling. Start must be called in order to begin intercepting or ignoring system signals.

func (*SignalMonitor) Set

func (m *SignalMonitor) Set(fn HandlerFunc)

Set stores a HandlerFunc to be called when a system signal is received. If a nil arg is provided, no action will be taken during signal handling. Only the most recently set HandlerFunc will be used.

func (*SignalMonitor) Start

func (m *SignalMonitor) Start()

Start establishes system signal awareness.

func (*SignalMonitor) Stop

func (m *SignalMonitor) Stop()

Stop disestablishes system signal awareness. Subsequently called system signals are handled normally.

type State

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

State holds information set by a corresponding signal.

func (*State) Signal

func (s *State) Signal() Signal

Signal returns a representation of the system signal which spawned the creation of the State instance.