pexec

Documentation

Overview

Package pexec defines process management utilities to be used as a library within a go process wishing to own sub-processes.

It helps manage the lifecycle of processes by keeping them up as long as possible when configured.

Index

• Variables
• type ManagedProcess
  • func MergeAddProcessManagers(dst, src ProcessManager) ([]ManagedProcess, error)
  • func MergeRemoveProcessManagers(dst, src ProcessManager) []ManagedProcess
  • func NewManagedProcess(config ProcessConfig, logger golog.Logger) ManagedProcess
• type ProcessConfig
  • func (config ProcessConfig) MarshalJSON() ([]byte, error)
  • func (config *ProcessConfig) UnmarshalJSON(data []byte) error
  • func (config *ProcessConfig) Validate(path string) error
• type ProcessManager
  • func NewProcessManager(logger golog.Logger) ProcessManager

Variables

var NoopProcessManager = &noopProcessManager{}

NoopProcessManager does nothing and is useful for places that need to return some ProcessManager.

Types

type ManagedProcess

type ManagedProcess interface {
	// ID returns the unique ID of the process.
	ID() string

	// Start starts the process. The given context is only used for one shot processes.
	Start(ctx context.Context) error

	// Stop signals and waits for the process to stop. An error is returned if
	// there's any system level issue stopping the process.
	Stop() error
}

A ManagedProcess controls the lifecycle of a single system process. Based on its configuration, it will ensure the process is revived if it every unexpectedly perishes.

func MergeAddProcessManagers

func MergeAddProcessManagers(dst, src ProcessManager) ([]ManagedProcess, error)

MergeAddProcessManagers merges in another process manager and takes ownership of its processes. This may replace existing processes and it's the callers responsibility to stop what has been replaced.

func MergeRemoveProcessManagers

func MergeRemoveProcessManagers(dst, src ProcessManager) []ManagedProcess

MergeRemoveProcessManagers merges in another process manager and removes ownership of its own processes. It does not stop the processes.

func NewManagedProcess

func NewManagedProcess(config ProcessConfig, logger golog.Logger) ManagedProcess

NewManagedProcess returns a new, unstarted, from the given configuration.

type ProcessConfig

type ProcessConfig struct {
	ID          string
	Name        string
	Args        []string
	CWD         string
	OneShot     bool
	Log         bool
	LogWriter   io.Writer
	StopSignal  syscall.Signal
	StopTimeout time.Duration
	// OnUnexpectedExit will be called when the manage goroutine detects an
	// unexpected exit of the process. The exit code of the crashed process will
	// be passed in. If the returned bool is true, the manage goroutine will
	// attempt to restart the process. Otherwise, the manage goroutine will
	// simply return.
	//
	// NOTE(benjirewis): use `jsonschema:"-"` struct tag to avoid issues with
	// jsonschema reflection (go functions cannot be encoded to JSON).
	OnUnexpectedExit func(int) bool `jsonschema:"-"`
}

A ProcessConfig describes how to manage a system process.

func (ProcessConfig) MarshalJSON

func (config ProcessConfig) MarshalJSON() ([]byte, error)

MarshalJSON converts to json.

func (*ProcessConfig) UnmarshalJSON

func (config *ProcessConfig) UnmarshalJSON(data []byte) error

UnmarshalJSON parses incoming json.

func (*ProcessConfig) Validate

func (config *ProcessConfig) Validate(path string) error

Validate ensures all parts of the config are valid.

type ProcessManager

type ProcessManager interface {
	// ProcessIDs returns the IDs of all managed processes.
	ProcessIDs() []string

	// ProcessByID fetches the process by the given ID if it exists.
	ProcessByID(id string) (ManagedProcess, bool)

	// RemoveProcessByID removes a managed process by the given ID if it exists.
	// It does not stop it it.
	RemoveProcessByID(id string) (ManagedProcess, bool)

	// Start starts all added processes and errors if any fail to start. The
	// given context is only used for one shot processes.
	Start(ctx context.Context) error

	// AddProcess manages the given process and potentially starts it depending
	// on the state of the ProcessManager and if it's requested. The same context
	// semantics in Start apply here. If the process is replaced by its ID, the
	// replaced process will be returned.
	AddProcess(ctx context.Context, proc ManagedProcess, start bool) (ManagedProcess, error)

	// AddProcess manages a new process from the given configuration and
	// potentially starts it depending on the state of the ProcessManager.
	// The same context semantics in Start apply here. If the process is
	// replaced by its ID, the replaced process will be returned.
	AddProcessFromConfig(ctx context.Context, config ProcessConfig) (ManagedProcess, error)

	// Stop signals and waits for all managed processes to stop and returns
	// any errors from stopping them.
	Stop() error

	// Clone gives a copy of the processes being managed but provides
	// no guarantee of the current state of the processes.
	Clone() ProcessManager
}

A ProcessManager is responsible for controlling the lifecycle of processes added to it.

func NewProcessManager

func NewProcessManager(logger golog.Logger) ProcessManager

NewProcessManager returns a new ProcessManager.