child

Documentation

Index

• Variables
• type Child
  • func New(i *NewInput) (*Child, error)
  • func (c *Child) Command() string
  • func (c *Child) ExitCh() <-chan int
  • func (c *Child) Kill()
  • func (c *Child) Pid() int
  • func (c *Child) Reload() error
  • func (c *Child) Signal(s os.Signal) error
  • func (c *Child) Start() error
  • func (c *Child) Stop()
• type NewInput

Variables

var (
	// ErrMissingCommand is the error returned when no command is specified
	// to run.
	ErrMissingCommand = errors.New("missing command")

	// ExitCodeOK is the default OK exit code.
	ExitCodeOK = 0

	// ExitCodeError is the default error code returned when the child exits with
	// an error without a more specific code.
	ExitCodeError = 127
)

Types

type Child

type Child struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Child is a wrapper around a child process which can be used to send signals and manage the processes' lifecycle.

func New

func New(i *NewInput) (*Child, error)

New creates a new child process for management with high-level APIs for sending signals to the child process, restarting the child process, and gracefully terminating the child process.

func (*Child) Command

func (c *Child) Command() string

Command returns the human-formatted command with arguments.

func (*Child) ExitCh

func (c *Child) ExitCh() <-chan int

ExitCh returns the current exit channel for this child process. This channel may change if the process is restarted, so implementers must not cache this value.

func (*Child) Kill

func (c *Child) Kill()

Kill sends the kill signal to the child process and waits for successful termination. If no kill signal is defined, the process is killed with the most aggressive kill signal. If the process does not gracefully stop within the provided KillTimeout, the process is force-killed. If a splay was provided, this function will sleep for a random period of time between 0 and the provided splay value to reduce the thundering herd problem. This function does not return any errors because it guarantees the process will be dead by the return of the function call.

func (*Child) Pid

func (c *Child) Pid() int

Pid returns the pid of the child process. If no child process exists, 0 is returned.

func (*Child) Reload

func (c *Child) Reload() error

Reload sends the reload signal to the child process and does not wait for a response. If no reload signal was provided, the process is restarted and replaces the process attached to this Child.

func (*Child) Signal

func (c *Child) Signal(s os.Signal) error

Signal sends the signal to the child process, returning any errors that occur.

func (*Child) Start

func (c *Child) Start() error

Start starts and begins execution of the child process. A buffered channel is returned which is where the command's exit code will be returned upon exit. Any errors that occur prior to starting the command will be returned as the second error argument, but any errors returned by the command after execution will be returned as a non-zero value over the exit code channel.

func (*Child) Stop

func (c *Child) Stop()

Stop behaves almost identical to Kill except it supresses future processes from being started by this child and it prevents the killing of the child process from sending its value back up the exit channel. This is useful when doing a graceful shutdown of an application.

type NewInput

type NewInput struct {
	// Stdin is the io.Reader where input will come from. This is sent directly to
	// the child process. Stdout and Stderr represent the io.Writer objects where
	// the child process will send output and errorput.
	Stdin          io.Reader
	Stdout, Stderr io.Writer

	// Command is the name of the command to execute. Args are the list of
	// arguments to pass when starting the command.
	Command string
	Args    []string

	// Timeout is the maximum amount of time to allow the command to execute. If
	// set to 0, the command is permitted to run infinitely.
	Timeout time.Duration

	// Env represents the condition of the child processes' environment
	// variables. Only these environment variables will be given to the child, so
	// it is the responsibility of the caller to include the parent processes
	// environment, if required. This should be in the key=value format.
	Env []string

	// ReloadSignal is the signal to send to reload this process. This value may
	// be nil.
	ReloadSignal os.Signal

	// KillSignal is the signal to send to gracefully kill this process. This
	// value may be nil.
	KillSignal os.Signal

	// KillTimeout is the amount of time to wait for the process to gracefully
	// terminate before force-killing.
	KillTimeout time.Duration

	// Splay is the maximum random amount of time to wait before sending signals.
	// This option helps reduce the thundering herd problem by effectively
	// sleeping for a random amount of time before sending the signal. This
	// prevents multiple processes from all signaling at the same time. This value
	// may be zero (which disables the splay entirely).
	Splay time.Duration
}

NewInput is input to the NewChild function.