proc

Documentation

Overview

* Copyright (C) 2020-2024 Arm Limited or its affiliates and Contributors. All rights reserved. * SPDX-License-Identifier: Apache-2.0

* Copyright (C) 2020-2024 Arm Limited or its affiliates and Contributors. All rights reserved. * SPDX-License-Identifier: Apache-2.0

Index

• func CancelExecCommand(cmd *exec.Cmd) (err error)
• func ConvertProcessError(err error) error
• func DefineCmdCancel(cmd *exec.Cmd) (*exec.Cmd, error)
• func InterruptProcess(ctx context.Context, pid int, signal InterruptType) (err error)
• func IsProcessRunning(ctx context.Context, pid int) (running bool, err error)
• func TerminateGracefully(ctx context.Context, pid int, gracePeriod time.Duration) (err error)
• func TerminateGracefullyWithChildren(ctx context.Context, pid int, gracePeriod time.Duration) (err error)
• func WaitForCompletion(ctx context.Context, pid int) (err error)
• func WaitForCompletionWithKill(ctx context.Context, pid int) (err error)
• type IProcess
  • func FindProcess(ctx context.Context, pid int) (p IProcess, err error)
  • func NewProcess(ctx context.Context, pid int) (pr IProcess, err error)
  • func Ps(ctx context.Context) (processes []IProcess, err error)
• type InterruptType

Functions

func CancelExecCommand

func CancelExecCommand(cmd *exec.Cmd) (err error)

CancelExecCommand defines a more robust way to cancel subprocesses than what is done per default by [CommandContext](https://pkg.go.dev/os/exec#CommandContext)

func ConvertProcessError

func ConvertProcessError(err error) error

func DefineCmdCancel

func DefineCmdCancel(cmd *exec.Cmd) (*exec.Cmd, error)

DefineCmdCancel sets and overwrites the cmd.Cancel function with CancelExecCommand so that it is more robust and thorough.

func InterruptProcess

func InterruptProcess(ctx context.Context, pid int, signal InterruptType) (err error)

func IsProcessRunning

func IsProcessRunning(ctx context.Context, pid int) (running bool, err error)

IsProcessRunning states whether a process is running or not. An error is returned if the context is Done while looking for the process state.

func TerminateGracefully

func TerminateGracefully(ctx context.Context, pid int, gracePeriod time.Duration) (err error)

TerminateGracefully follows the pattern set by [kubernetes](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination) and terminates processes gracefully by first sending a SIGTERM and then a SIGKILL after the grace period has elapsed.

func TerminateGracefullyWithChildren

func TerminateGracefullyWithChildren(ctx context.Context, pid int, gracePeriod time.Duration) (err error)

TerminateGracefullyWithChildren follows the pattern set by [kubernetes](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination) and terminates processes gracefully by first sending a SIGTERM and then a SIGKILL after the grace period has elapsed. It does not attempt to terminate the process group. If you wish to terminate the process group directly then send -pgid to TerminateGracefully but this does not guarantee that the group will be terminated gracefully. Instead, this function lists each child and attempts to kill them gracefully concurrently. It will then attempt to gracefully terminate itself. Due to the multi-stage process and the fact that the full grace period must pass for each stage specified above, the total maximum length of this function will be 2*gracePeriod not gracePeriod.

func WaitForCompletion

func WaitForCompletion(ctx context.Context, pid int) (err error)

WaitForCompletion will wait for a given process to complete. This allows check to work if the underlying process was stopped without needing the os.Process that started it.

func WaitForCompletionWithKill

func WaitForCompletionWithKill(ctx context.Context, pid int) (err error)

WaitForCompletionWithKill will wait for a process to complete and if the context elapses then it will kill it and its children

Types

type IProcess

type IProcess interface {
	// Pid is the process ID for this process.
	Pid() int

	// PPid is the parent process ID for this process.
	PPid() int

	// Executable name running this process. This is not a path to the
	// executable.
	Executable() string

	// Name returns name of the process.
	Name() string

	Environ(ctx context.Context) ([]string, error)

	// Cmdline returns the command line arguments of the process as a string with
	// each argument separated by 0x20 ascii character.
	Cmdline() string

	// Cwd returns current working directory of the process.
	Cwd() string

	// Parent returns parent Process of the process.
	Parent() IProcess

	// Children returns the children of the process if any.
	Children(ctx context.Context) ([]IProcess, error)

	// IsAZombie returns whether the process is a zombie process. See https://en.wikipedia.org/wiki/Zombie_process
	IsAZombie() bool

	// IsRunning returns whether the process is still running or not.
	IsRunning() bool

	// Terminate sends SIGTERM to the process.
	Terminate(context.Context) error

	// Interrupt sends SIGINT to the process.
	Interrupt(context.Context) error

	// KillWithChildren sends SIGKILL to the process but also ensures any children of the process are also killed.
	// see https://medium.com/@felixge/killing-a-child-process-and-all-of-its-children-in-go-54079af94773
	// This method was introduced to avoid getting the following due to a poor cleanup:
	// - Orphan processes (https://en.wikipedia.org/wiki/Orphan_process)
	// - Zombies processes (https://en.wikipedia.org/wiki/Zombie_process)
	KillWithChildren(context.Context) error
}

IProcess is the generic interface that is implemented on every platform and provides common operations for processes. Inspired from https://github.com/mitchellh/go-ps/blob/master/process.go

func FindProcess

func FindProcess(ctx context.Context, pid int) (p IProcess, err error)

FindProcess looks up a single process by pid.

Process will be nil and error will be commonerrors.ErrNotFound if a matching process is not found.

func NewProcess

func NewProcess(ctx context.Context, pid int) (pr IProcess, err error)

NewProcess creates a new Process instance, it only stores the pid and checks that the process exists. Other method on Process can be used to get more information about the process. An error will be returned if the process does not exist.

func Ps

func Ps(ctx context.Context) (processes []IProcess, err error)

Ps returns all processes in a similar fashion to `ps` command on Unix.

This of course will be a point-in-time snapshot of when this method was called. Some operating systems don't provide snapshot capability of the process table, in which case the process table returned might contain ephemeral entities that happened to be running when this was called.

type InterruptType

type InterruptType int

const (
	SigInt                           InterruptType = 2
	SigKill                          InterruptType = 9
	SigTerm                          InterruptType = 15
	SubprocessTerminationGracePeriod               = 10 * time.Millisecond
)