exiter

package module
v0.0.0-...-e6ef3c7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 19, 2025 License: Apache-2.0 Imports: 7 Imported by: 0

README

exiter

GoDoc

Go program clean exit handling.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var DefaultExiterConfig = ExiterConfig{
	ParentCtx: context.Background(),
	ExitSignals: []os.Signal{
		syscall.SIGINT,
		syscall.SIGTERM,
	},
}

DefaultExiterConfig is the ExiterConfig used when calling the NewExiter() factory.

Functions

func FullCodeMap 

func FullCodeMap() (m map[ExitCode]string)

FullCodeMap returns a map of all ExitCodes and their associated description strings.

func GetAllExitCodeDescriptions 

func GetAllExitCodeDescriptions() [^ExitCode(0)]string

GetAllExitCodeDescriptions returns an array of all possible ExitCode description strings (where the index is the exit code). Any unreserved ExitCodes are also included with empty string descriptions.

func UserCodeMap 

func UserCodeMap() (m map[ExitCode]string)

UserCodeMap returns a map of ExitCodes and their associated description strings with in the User-Definable range.

Types

type ExitCode 

type ExitCode exit.ExitT

ExitCode represents an unsigned 16 bit integer used to define exit statuses. 

const (
	ExitOK          ExitCode = ExitCode(exit.EX_OK)          // 0: successful termination
	ExitError       ExitCode = ExitCode(1)                   // 1: generic error
	ExitUsage       ExitCode = ExitCode(exit.EX_USAGE)       // 64: command line usage error
	ExitDataErr     ExitCode = ExitCode(exit.EX_DATAERR)     // 65: data format error
	ExitNoInput     ExitCode = ExitCode(exit.EX_NOINPUT)     // 66: cannot open input
	ExitNoUser      ExitCode = ExitCode(exit.EX_NOUSER)      // 67: addressee unknown
	ExitNoHost      ExitCode = ExitCode(exit.EX_NOHOST)      // 68: host name unknown
	ExitUnavailable ExitCode = ExitCode(exit.EX_UNAVAILABLE) // 69: service unavailable
	ExitSoftware    ExitCode = ExitCode(exit.EX_SOFTWARE)    // 70: internal software error
	ExitOSErr       ExitCode = ExitCode(exit.EX_OSERR)       // 71: system error (e.g., can't fork)
	ExitOSFile      ExitCode = ExitCode(exit.EX_OSFILE)      // 72: critical OS file missing
	ExitCantCreate  ExitCode = ExitCode(exit.EX_CANTCREAT)   // 73: can't create (user) output file
	ExitIOErr       ExitCode = ExitCode(exit.EX_IOERR)       // 74: input/output error
	ExitTempFail    ExitCode = ExitCode(exit.EX_TEMPFAIL)    // 75: temp failure; user is invited to retry
	ExitProtocol    ExitCode = ExitCode(exit.EX_PROTOCOL)    // 76: remote error in protocol
	ExitNoPerm      ExitCode = ExitCode(exit.EX_NOPERM)      // 77: permission denied
	ExitConfig      ExitCode = ExitCode(exit.EX_CONFIG)      // 78: configuration error
	ExitAbort       ExitCode = ExitCode(exit.EX_ABORT)       // 134: process was aborted
)

func RegisterNewExitCode 

func RegisterNewExitCode(num int, desc string) (ExitCode, error)

RegisterNewExitCode reserves an ExitCode and stores its corresponding description string for recall. It returns an error if the given integer is already in use or outside the usable range. And also if the description string is empty.

func RegisterNextExitCode 

func RegisterNextExitCode(desc string) (ExitCode, error)

RegisterNextExitCode find the next available ExitCode number and associates the given description string with it. It returns an error if there are no more available numbers to reserve.

func (ExitCode) Desc 

func (e ExitCode) Desc() string

Desc returns the description string for a given ExitCode.

type ExitTaskFn 

type ExitTaskFn sigar.TaskFn

ExitTaskFn (`func()`) is a closure represening something that should be executed right before exiting.

type Exiter 

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

Exiter is a tool for cleanly and consistently exiting the program. Instead of creating the struct directly, use the NewExiter() or NewExiterWithConfig() factories.

func NewExiter 

func NewExiter() *Exiter

NewExiter is an Exiter factory that uses the DefaultExiterConfig. Be sure to call (Exiter).ListenForSignals() once created to handle all exits properly.

func NewExiterWithConfig 

func NewExiterWithConfig(config ExiterConfig) (e *Exiter)

NewExiterWithConfig is an Exiter factory that allows you to customize the configuration. Be sure to call (Exiter).ListenForSignals() once created to handle all exits properly.

func SpawnExiter 

func SpawnExiter() (e *Exiter)

SpawnExiter is a convenience function that calls both NewExiter() and (Exiter).ListenForSignals().

func SpawnExiterWithConfig 

func SpawnExiterWithConfig(config ExiterConfig) (e *Exiter)

SpawnExiterWithConfig is a convenience function that calls both NewExiterWithConfig() and (Exiter).ListenForSignals().

func (*Exiter) Exit 

func (e *Exiter) Exit(code ExitCode, err ...error)

ExitWithConfigErr exits with the given ExitCode, and prints the first error provided (if any).

func (*Exiter) ExitOnPanic 

func (e *Exiter) ExitOnPanic()

ExitOnPanic is a convenience function that is meant to be defered as a means to gracefully exit in the event of a panic.

func (*Exiter) ExitWithCantCreateErr 

func (e *Exiter) ExitWithCantCreateErr(err ...error)

ExitWithCantCreateErr calls (Exiter).Exit() with ExitCantCreate (73).

It is recommended to use this only when the creation of a user output file is impossible for any reason and the program is unable to continue.

func (*Exiter) ExitWithConfigErr 

func (e *Exiter) ExitWithConfigErr(err ...error)

ExitWithConfigErr calls (Exiter).Exit() with ExitConfig (78).

It is recommended to use this whenever a schema validation is encountered in a config file or other serialiezed configuarion source.

func (*Exiter) ExitWithDataErr 

func (e *Exiter) ExitWithDataErr(err ...error)

ExitWithDataErr calls (Exiter).Exit() with ExitDataErr (65).

It is recommended to use this when data provided through any means is invalid but NOT when an argument fails basic validation (though schema errors in complex arguments could be appropriate UNLESS they are configuartion settings, in which case you should use (Exiter).ExitWithConfigErr()).

func (*Exiter) ExitWithError 

func (e *Exiter) ExitWithError(err ...error)

ExitWithError calls (Exiter).Exit() with ExitError (1).

It is recommended to use this when no other exit code makes sense.

func (*Exiter) ExitWithIOErr 

func (e *Exiter) ExitWithIOErr(err ...error)

ExitWithIOErr calls (Exiter).Exit() with ExitIOErr (74).

It is recommended to use this only when unable to interact with I/O hardware, failure to open or write to an output stream, or when encountering an interuption from an already open input stream (otherwise use (Exiter).ExitWithNoInputErr()). Permissions errors should use (Exiter).ExitWithNoPermErr() instead.

func (*Exiter) ExitWithNoHostErr 

func (e *Exiter) ExitWithNoHostErr(err ...error)

ExitWithNoHostErr calls (Exiter).Exit() with ExitNoHost (68).

It is recommended to use this when a provided hostname cannot be resolved.

func (*Exiter) ExitWithNoInputErr 

func (e *Exiter) ExitWithNoInputErr(err ...error)

ExitWithNoInputErr calls (Exiter).Exit() with ExitNoInput (66).

It is recommended to use this only when an input channel (such as a pipe, os.STDIN, or virtual device) cannot be opened or read when needed. Permissions errors should use (Exiter).ExitWithNoPermErr() instead.

func (*Exiter) ExitWithNoPermErr 

func (e *Exiter) ExitWithNoPermErr(err ...error)

ExitWithNoPermErr calls (Exiter).Exit() with ExitNoPerm (77).

It is recommended to use this whenever user or credential Permissions do not allow you to continue.

func (*Exiter) ExitWithNoUserErr 

func (e *Exiter) ExitWithNoUserErr(err ...error)

ExitWithNoUserErr calls (Exiter).Exit() with ExitNoUser (67).

It is recommended to use this only when attempting to address data to a local or network user, and no suitable match can be found. Mostly useful for multi-user machines or intranet communication not using a protocol that has its own suitable statuses for this.

func (*Exiter) ExitWithOK 

func (e *Exiter) ExitWithOK()

ExitWithOK calls (Exiter).Exit() with ExitOK (0).

It is recommended to use this for all normal exit conditions.

func (*Exiter) ExitWithOSErr 

func (e *Exiter) ExitWithOSErr(err ...error)

ExitWithOSErr calls (Exiter).Exit() with ExitOSErr (71).

It is recommended to use this only when unable to continue due to encountering a generalized system error.

func (*Exiter) ExitWithOSFile 

func (e *Exiter) ExitWithOSFile(err ...error)

ExitWithOSFile calls (Exiter).Exit() with ExitOSFile (72).

It is recommended to use this only when unable to find a file or directory not owned by this or any othe program but is part of the general system configuration. Such as a standard FHS directory, or a device file in /dev.

func (*Exiter) ExitWithProtocolErr 

func (e *Exiter) ExitWithProtocolErr(err ...error)

ExitWithProtocolErr calls (Exiter).Exit() with ExitProtocol (76).

It is recommended to use this only when some communication with a process or network location fails due to a protocol violation from the other communication participant. And example would be receiving a response that is not inline with the protocol (like a SYN or ACK in response to the same instead of a SYN/ACK when performing a TCP handshake).

func (*Exiter) ExitWithSoftwareErr 

func (e *Exiter) ExitWithSoftwareErr(err ...error)

ExitWithSoftwareErr calls (Exiter).Exit() with ExitSoftware (70).

It is recommended to use this as a more meaningful alternative to ExitWithError() or for more graceful exits in the event of a Panic. For the later case consider deferring (Exiter).ExitOnPanic() which will call this function in that event.

func (*Exiter) ExitWithTempFailErr 

func (e *Exiter) ExitWithTempFailErr(err ...error)

ExitWithTempFailErr calls (Exiter).Exit() with ExitTempFail (75).

It is recommended to use this when the program chooses (by design) to terminate instead of retrying some operation that is expected to have failed merely intermittently.

func (*Exiter) ExitWithUnavailableErr 

func (e *Exiter) ExitWithUnavailableErr(err ...error)

ExitWithUnavailableErr calls (Exiter).Exit() with ExitUnavailable (69) (nice).

It is recommended to use this for client programs which cannot communicate with another process or remote service.

func (*Exiter) ExitWithUsageErr 

func (e *Exiter) ExitWithUsageErr(err ...error)

ExitWithUsageErr prints the help/usage and calls (Exiter).Exit() with ExitUsage (64). If no UsageFunc was set, it will not print anything.

It is recommended to use this when bad arguments are passed.

func (*Exiter) ExitWithUsageOK 

func (e *Exiter) ExitWithUsageOK()

ExitWithUsageOK prints the help/usage and calls (Exiter).Exit() with ExitOK (0). If no UsageFunc was set, it will not print anything.

It is recommended to use this when responding to help arguments.

func (*Exiter) GetCancelableContext 

func (e *Exiter) GetCancelableContext() context.Context

GetCancelableContext returns the underlying cancelable context used by the Exiter.

func (*Exiter) GetSignalCatcher 

func (e *Exiter) GetSignalCatcher() *sigar.SignalCatcher

GetSignalCatcher returns the underlying *sigar.SignalCatcher used by the Exiter.

func (*Exiter) ListenForSignals 

func (e *Exiter) ListenForSignals()

ListenForSignals spawns a goroutine to catch signals so that the Exiter can gracefully shutdown the program.

func (*Exiter) RegisterPostTask 

func (e *Exiter) RegisterPostTask(fn ExitTaskFn)

RegisterPostTask adds a task to the queue that will be executed after unblocking goroutines blocked at (Exiter).Wait().

func (*Exiter) RegisterPreTask 

func (e *Exiter) RegisterPreTask(fn ExitTaskFn)

RegisterPreTask adds a task to the queue that will be executed prior to unblocking goroutines blocked at (Exiter).Wait().

func (*Exiter) SetUsageFunc 

func (e *Exiter) SetUsageFunc(usage ExitTaskFn)

SetUsageFunc tells the Exiter what function to call to print the program's help/usage information.

func (*Exiter) Wait 

func (e *Exiter) Wait()

Wait blocks till (Exiter).Exit() is called. It is recommended to call this function in a select block case in all goroutines to ensure they are properly terminated.

type ExiterConfig 

type ExiterConfig struct {
	ParentCtx          context.Context
	ExitSignals        []os.Signal
	SuppressAllExitMsg bool
	ShowOKExitMsg      bool
}

ExiterConfig contains options for the creation of an Exiter.

type WriteFn 

type WriteFn func(format string, a ...interface{})

WriteFn is a format function that will write output somewhere. This could be a custom function or simply a logger function pointer.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.