process

Documentation

Index

• Variables
• type Child
  • func (c *Child) Command() string
  • func (c *Child) ExitCh() <-chan int
  • func (c *Child) Kill()
  • func (c *Child) Pid() int
  • func (c *Child) Signal(s os.Signal) error
  • func (c *Child) Start() error
  • func (c *Child) Stop()
  • func (c *Child) StopImmediately()
• type ChildExit
  • func (ce *ChildExit) Error() string
• type Manager
  • func NewManager(logger hclog.Logger) *Manager
  • func (m *Manager) Close()
  • func (m *Manager) Exec(cmd *exec.Cmd) error
• 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
)

var ErrClosing = errors.New("process manager is already closing")

ErrClosing is returned when the process manager is in the process of closing, meaning that no more child processes can be Exec'd, and existing, non-failed child processes will be stopped with this error.

Types

type Child

type Child struct {
	sync.RWMutex

	Label string
	// 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 (*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) 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 suppresses 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.

func (*Child) StopImmediately

func (c *Child) StopImmediately()

StopImmediately behaves almost identical to Stop except it does not wait for any random splay if configured. This is used for performing a fast shutdown of consul-template and its children when a kill signal is received.

type ChildExit

type ChildExit struct {
	ExitCode int
	Command  string
}

ChildExit is returned when a child process exits with a non-zero exit code

func (*ChildExit) Error

func (ce *ChildExit) Error() string

type Manager

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

Manager tracks all of the child processes that have been spawned

func NewManager

func NewManager(logger hclog.Logger) *Manager

NewManager creates a new properly-initialized Manager instance

func (*Manager) Close

func (m *Manager) Close()

Close sends SIGINT to all child processes if it hasn't been done yet, and in either case blocks until they all exit or timeout

func (*Manager) Exec

func (m *Manager) Exec(cmd *exec.Cmd) error

Exec spawns a child process to run the given command, then blocks until it completes. Returns a nil error if the child process finished successfully, ErrClosing if the manager closed during execution, and a ChildExit error if the child process exited with a non-zero exit code.

type NewInput

type NewInput struct {
	// Cmd is the unstarted, preconfigured command to run
	Cmd *exec.Cmd

	// 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

	// 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

	// Logger receives debug log lines about the process state and transitions
	Logger hclog.Logger
}

NewInput is input to the NewChild function.