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 ¶
Constants ¶
This section is empty.
Variables ¶
var NoopProcessManager = &noopProcessManager{}
NoopProcessManager does nothing and is useful for places that need to return some ProcessManager.
Functions ¶
This section is empty.
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
// Status return nil when the process is both alive and owned.
// If err is non-nil, process may be a) alive but not owned or b) dead.
Status() 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 utils.ZapCompatibleLogger) 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
// Optional. When present, we will try to look up the Uid of the named user
// and run the process as that user.
Username string
// Environment variables to pass through to the process.
// Will overwrite existing environment variables.
Environment map[string]string
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:"-"`
// contains filtered or unexported fields
}
A ProcessConfig describes how to manage a system process.
func (ProcessConfig) Equals ¶ added in v0.1.38
func (config ProcessConfig) Equals(other ProcessConfig) bool
Equals checks if the two configs are deeply equal to each other.
func (ProcessConfig) MarshalJSON ¶ added in v0.1.7
func (config ProcessConfig) MarshalJSON() ([]byte, error)
MarshalJSON converts to json.
func (*ProcessConfig) UnmarshalJSON ¶ added in v0.1.7
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 utils.ZapCompatibleLogger) ProcessManager
NewProcessManager returns a new ProcessManager.
Source Files