process

package
v0.22.8 Latest Latest
Warning

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

 Go to latest Published: Feb 26, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// A valid exit code of a process is a non-negative number. We use UnknownExitCode to indicate that we have not obtained the exit code yet.
	UnknownExitCode int32 = -1

	// Unknown PID code is used when replica is not started (or fails to start)
	UnknownPID Pid_t = -1
)
View Source 
const ProcessIdentityTimeMaximumDifference = 2 * time.Millisecond

We serialize timestamps with millisecond precision, so a maximum couple of milliseconds of difference works well.

Variables

View Source 
var (
	This func() (ProcessTreeItem, error)

	// Essentially the same as ps.ErrorProcessNotRunning, but we do not want to
	// expose the ps package outside of this package.
	ErrorProcessNotFound = errors.New("process does not exist")
)
View Source 
var (
	ErrDisposed = errors.New("the process executor has been disposed")
)
View Source 
var (
	ErrTimedOutWaitingForProcessToStop = errors.New("timed out waiting for process to stop")
)

Functions

func DecoupleFromParent 

func DecoupleFromParent(cmd *exec.Cmd)

Use separate process group so this process exit will not affect the children.

func FindProcess 

func FindProcess(pid Pid_t, expectedStartTime time.Time) (*os.Process, error)

Returns the process with the given PID. If the expectedStartTime is not zero, the process start time is checked to match the expected start time.

func ForkFromParent 

func ForkFromParent(cmd *exec.Cmd)

Use separate process group so this process exit will not affect the children. This is the same as DecoupleFromParent on Unix systems.

func HasExpectedIdentityTime 

func HasExpectedIdentityTime(proc *ps.Process, expectedIdentityTime time.Time) bool

func IsEarlyProcessExitError 

func IsEarlyProcessExitError(err error) bool

Checks if the error is associated with early exit of a process, which is often expected.

func PidT_ToInt 

func PidT_ToInt(val Pid_t) (int, error)

func PidT_ToUint32 

func PidT_ToUint32(val Pid_t) (uint32, error)

func ProcessIdentityTime 

func ProcessIdentityTime(pid Pid_t) time.Time

Gets the raw start time for the process, used to verify process identity. This time may not match the wall clock time returned by StartTimeForProcess() on all OS platforms and should not be used for display purposes, but is stable across system clock changes.

func RunToCompletion 

func RunToCompletion(ctx context.Context, executor Executor, cmd *exec.Cmd) (int32, error)

Runs the command as a child process to completion. Returns exit code, or error if the process could not be started/tracked for some reason.

The context parameter is used to request cancellation of the process, but the call to RunToCompletion() will not return until the process exits and all its output is captured. Do not assume the call will end quickly if the context is cancelled.

func RunWithTimeout 

func RunWithTimeout(ctx context.Context, executor Executor, cmd *exec.Cmd) (int32, error)

Runs the command as a child process to completion, unless the passed context is cancelled, or its deadline is exceeded.

func StartTimeForProcess 

func StartTimeForProcess(pid Pid_t) time.Time

Returns the creation time as a time.Time for a process. This time is intended for display purposes and may differ from the raw start time used to verify process identity and the value returned can change due to clock adjustments etc.

Types

type ChannelProcessExitHandler 

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

A simple process exit handler that writes the finished process status to a channel

func NewChannelProcessExitHandler 

func NewChannelProcessExitHandler(c chan ProcessExitInfo) *ChannelProcessExitHandler

func (*ChannelProcessExitHandler) OnProcessExited 

func (eh *ChannelProcessExitHandler) OnProcessExited(pid Pid_t, exitCode int32, err error)

type ErrProcessNotFound 

type ErrProcessNotFound struct {
	Pid   Pid_t
	Inner error
}

func (ErrProcessNotFound) Error 

func (e ErrProcessNotFound) Error() string

type Executor 

type Executor interface {
	// Starts the process described by given command instance.
	// When the passed context is cancelled, the process is automatically terminated.
	// Returns the process PID, process start time, and a function that enables process exit notifications
	// delivered to the exit handler.
	StartProcess(
		ctx context.Context,
		cmd *exec.Cmd,
		exitHandler ProcessExitHandler,
		creationFlags ProcessCreationFlag,
	) (pid Pid_t, startTime time.Time, startWaitForProcessExit func(), err error)

	// Stops the process with a given PID.
	// The processStartTime, if provided (time.IsZero() returns false), is used to further validate the process to be stopped.
	// (to protect against stopping a wrong process, if the PID was reused).
	StopProcess(pid Pid_t, processStartTime time.Time) error

	// Starts a process that does not need to be tracked (the caller is not interested in its exit code),
	// minimizing resource usage. An error is returned if the process could not be started.
	StartAndForget(cmd *exec.Cmd, creationFlags ProcessCreationFlag) (pid Pid_t, startTime time.Time, err error)

	// Disposes the executor. Processes started with CreationFlagEnsureKillOnDispose will be terminated.
	// Other processes will be waited on (so that they do not become zombies), but not terminated.
	Dispose()
}

func NewOSExecutor 

func NewOSExecutor(log logr.Logger) Executor

type OSExecutor 

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

func (*OSExecutor) Dispose 

func (e *OSExecutor) Dispose()

Disposes the process executor.

func (*OSExecutor) StartAndForget 

func (e *OSExecutor) StartAndForget(cmd *exec.Cmd, flags ProcessCreationFlag) (Pid_t, time.Time, error)

func (*OSExecutor) StartProcess 

func (e *OSExecutor) StartProcess(
	ctx context.Context,
	cmd *exec.Cmd,
	handler ProcessExitHandler,
	flags ProcessCreationFlag,
) (Pid_t, time.Time, func(), error)

func (*OSExecutor) StopProcess 

func (e *OSExecutor) StopProcess(pid Pid_t, processStartTime time.Time) error

type Pid_t 

type Pid_t int64

Pid_t is a type used to represent process IDs. The domain is all unsigned 32-bit integers, but we use a signed type to align with Kubernetes API conventions.

func Int64_ToPidT 

func Int64_ToPidT(val int64) (Pid_t, error)

func StringToPidT 

func StringToPidT(val string) (Pid_t, error)

func Uint32_ToPidT 

func Uint32_ToPidT(val uint32) Pid_t

type ProcessCreationFlag 

type ProcessCreationFlag uint32
const (
	CreationFlagsNone ProcessCreationFlag = 0

	// Ensures that the process is killed when process executor is disposed.
	// This has currently no effect on Mac/Linux, but on Windows the process started with this flag
	// will be added to the "killer job" object that terminates all processes assigned to it.
	CreationFlagEnsureKillOnDispose = 0x1
)

type ProcessExitHandler 

type ProcessExitHandler interface {
	// Indicates that process with a given PID has finished execution
	// If err is nil, the process exit code was properly captured and the exitCode value is valid.
	// Note that if the process was terminated by a signal, the exit code will be UnknownExitCode (-1).
	// if err is not nil, there was a problem tracking the process and the exitCode value is not valid
	OnProcessExited(pid Pid_t, exitCode int32, err error)
}

type ProcessExitHandlerFunc 

type ProcessExitHandlerFunc func(Pid_t, int32, error)

Make it easy to supply a function as a process exit handler.

func (ProcessExitHandlerFunc) OnProcessExited 

func (f ProcessExitHandlerFunc) OnProcessExited(pid Pid_t, exitCode int32, err error)

type ProcessExitInfo 

type ProcessExitInfo struct {
	PID      Pid_t
	ExitCode int32
	Err      error
}

func NewProcessExitInfo 

func NewProcessExitInfo() ProcessExitInfo

type ProcessTreeItem 

type ProcessTreeItem struct {
	Pid          Pid_t
	IdentityTime time.Time // Used to distinguish between different instances of processes with the same PID, may not be a valid wall-clock time.
}

func GetProcessTree 

func GetProcessTree(rootP ProcessTreeItem) ([]ProcessTreeItem, error)

Returns the list of ID for a given process and its children The list is ordered starting with the root of the hierarchy, then the children, then the grandchildren etc.

type WaitKey 

type WaitKey struct {
	Pid       Pid_t
	StartedAt time.Time
}

type Waitable 

type Waitable interface {
	Wait() error
	Info() string
	Flags() ProcessCreationFlag
}

type WaitableProcess 

type WaitableProcess struct {
	WaitPollInterval time.Duration
	// contains filtered or unexported fields
}

func FindWaitableProcess 

func FindWaitableProcess(pid Pid_t, processStartTime time.Time) (*WaitableProcess, error)

func (*WaitableProcess) Kill 

func (p *WaitableProcess) Kill() error

func (*WaitableProcess) Signal 

func (p *WaitableProcess) Signal(signal syscall.Signal) error

func (*WaitableProcess) Wait 

func (p *WaitableProcess) Wait(ctx context.Context) error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.