process

package module
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 29, 2026 License: MIT Imports: 10 Imported by: 10

README

go-processmanager

Updated version for 2024

  • Updated gopsutils to v4
    • bumps module target to golang 1.18+
  • Allows setting working directory
  • Breaking Change config.KillSignal is now an *int - avoids the need to parse at runtime. options.WithKillSignal will need to be updated.

Documentation

Index

Constants

This section is empty.

Variables

View Source
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 NewLog

func NewLog(path string) *os.File

Create a new file for logging

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 WithArgs

func WithArgs(s ...string) func(cfg *Config) error

func WithGracefulTimeout

func WithGracefulTimeout(d time.Duration) func(cfg *Config) error

WithGracefulTimeout sets the duration to wait after SIGTERM before SIGKILL

func WithKillProcessGroup

func WithKillProcessGroup(b bool) func(cfg *Config) error

WithKillProcessGroup enables or disables killing the entire process group

func WithKillSignal

func WithKillSignal(i int) func(cfg *Config) error

WithKillSignal sets the given signal while attemping to stop. Defaults to 9

func WithName

func WithName(s string) func(cfg *Config) error

func WithSTDIN

func WithSTDIN(f *os.File) func(cfg *Config) error

func WithStateDir

func WithStateDir(s string) func(cfg *Config) error

func WithSubreaper added in v0.1.2

func WithSubreaper(b bool) func(cfg *Config) error

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 WithTemporaryStateDir() func(cfg *Config) error

func WithWorkDir

func WithWorkDir(s string) func(cfg *Config) error

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

func (*Config) Apply

func (cfg *Config) Apply(opts ...Option) error

Apply applies the given options to the config, returning the first error encountered (if any).

type Option

type Option func(cfg *Config) error

func WithEnvironment

func WithEnvironment(s ...string) Option

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

func New(p ...Option) *Process

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

func (p *Process) CurrentPID() string

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) ExitCode

func (p *Process) ExitCode() (string, error)

ExitCode returns the exitcode associated with the process

func (*Process) IsAlive

func (p *Process) IsAlive() bool

IsAlive checks if the process is running or not

func (*Process) Run

func (p *Process) Run() error

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) StateDir

func (p *Process) StateDir() string

StateDir returns the process state directory

func (*Process) StderrPath

func (p *Process) StderrPath() string

StderrPath returns the file where the stderr of the process is appended to

func (*Process) StdoutPath

func (p *Process) StdoutPath() string

StdoutPath returns the file where the stdout is appended to

func (*Process) Stop

func (p *Process) Stop() error

Stop stops the running process by sending KillSignal to the PID annotated in the pidfile

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL