Documentation
¶
Index ¶
- Variables
- func NewLog(path string) *os.File
- func SetSubreaper() error
- func WithArgs(s ...string) func(cfg *Config) error
- func WithGracefulTimeout(d time.Duration) func(cfg *Config) error
- func WithKillProcessGroup(b bool) func(cfg *Config) error
- func WithKillSignal(i int) func(cfg *Config) error
- func WithName(s string) func(cfg *Config) error
- func WithSTDIN(f *os.File) func(cfg *Config) error
- func WithStateDir(s string) func(cfg *Config) error
- func WithSubreaper(b bool) func(cfg *Config) error
- func WithTemporaryStateDir() func(cfg *Config) error
- func WithWorkDir(s string) func(cfg *Config) error
- type Config
- type Option
- type Process
- func (p *Process) CurrentPID() string
- func (p *Process) Done() <-chan struct{}
- func (p *Process) ExitCode() (string, error)
- func (p *Process) IsAlive() bool
- func (p *Process) Run() error
- func (p *Process) StateDir() string
- func (p *Process) StderrPath() string
- func (p *Process) StdoutPath() string
- func (p *Process) Stop() error
Constants ¶
This section is empty.
Variables ¶
var ErrProcessAlreadyRun = errors.New("command already started: a Process handle is single-use, construct a new one to start another process")
ErrProcessAlreadyRun is returned by Run when the handle has already started a process. A Process is single-use: it owns exactly one done channel and one monitor goroutine, and neither is recreated, so restarting through the same handle is not supported. Construct a new Process to start another one.
The message keeps the historical "command already started" prefix so callers matching on that text keep working.
Functions ¶
func SetSubreaper ¶
func SetSubreaper() error
SetSubreaper configures the calling process to be a subreaper. A subreaper fulfills the role of init(1) for its descendant processes. When a process becomes orphaned (its immediate parent terminates), it will be reparented to the nearest still living ancestor subreaper. This is useful in containerized environments to ensure proper cleanup of orphaned child processes.
func WithGracefulTimeout ¶
WithGracefulTimeout sets the duration to wait after SIGTERM before SIGKILL
func WithKillProcessGroup ¶
WithKillProcessGroup enables or disables killing the entire process group
func WithKillSignal ¶
WithKillSignal sets the given signal while attemping to stop. Defaults to 9
func WithStateDir ¶
func WithSubreaper ¶ added in v0.1.2
WithSubreaper makes the calling process a child subreaper for the lifetime of this process, and reaps any orphan reparented to it.
It is off by default, and should only be enabled by a program that is the init of its own PID namespace or container. Reaping orphans means calling wait(-1), which claims *any* child of the calling process, including children the Go runtime is waiting on. With this enabled, an unrelated exec.Command(...).Run() elsewhere in the program can lose its exit status and fail with "waitid: no child processes".
func WithTemporaryStateDir ¶
func WithWorkDir ¶
Types ¶
type Config ¶
type Config struct {
Name string
Args []string
Combined bool
StateDir string
KillSignal *int
Environment []string
Stdin *os.File
WorkDir string
GracefulTimeout time.Duration // Time to wait after SIGTERM before SIGKILL
KillProcessGroup bool // Whether to kill entire process group (default true)
Subreaper bool // Whether to become a child subreaper and reap orphans (default false)
}
func DefaultConfig ¶
func DefaultConfig() *Config
type Option ¶
func WithEnvironment ¶
type Process ¶
type Process struct {
// PID holds the process ID last written to the pidfile.
//
// Deprecated: read it through CurrentPID instead. The monitor goroutine
// clears this field when the process exits, so a direct field read races
// with the library's own bookkeeping. It is kept for backwards
// compatibility and will be unexported in a future release.
PID string
// contains filtered or unexported fields
}
func New ¶
New builds up a new process with options.
An option that fails to apply is remembered and returned by Run, which refuses to start. New keeps returning only *Process so existing callers still compile, but the failure is no longer lost: Apply stops at the first failing option, so the ones after it never reach the config, and a process started in that state would run without its arguments, environment or working directory.
func (*Process) CurrentPID ¶ added in v0.1.2
CurrentPID returns the process ID currently tracked by this handle, or an empty string if no process has been started or the process has exited.
func (*Process) Done ¶ added in v0.1.1
func (p *Process) Done() <-chan struct{}
Done returns a channel that is closed once the process has exited (whether cleanly or because Wait returned an error). It is safe to receive from before Run is called; the channel will not be closed until a process is actually started and exits.
After Done is closed, ExitCode reports the exit status. If the process exited because Wait returned an error, the "error" file in StateDir holds the message and ExitCode will return an error.
func (*Process) Run ¶
Run starts the process and returns any error.
A Process handle is single-use. Once Run has started a process, every later Run on the same handle returns ErrProcessAlreadyRun, whether or not that process has since exited or been stopped: the done channel and the monitor goroutine are created once and are not recreated. To start another process, build a new handle with New. A Run that fails before starting anything can be retried.
func (*Process) StderrPath ¶
StderrPath returns the file where the stderr of the process is appended to
func (*Process) StdoutPath ¶
StdoutPath returns the file where the stdout is appended to