process

Documentation

Overview

Package process is the single home for discovering and terminating the processes that hold gtl's TCP ports. It replaces three near-identical copies of the same lsof/ps/kill logic that had drifted across cmd and internal/service.

Index

• func Alive(pid int) bool
• func CommandName(pid int) string
• func KillGracefully(pid int, timeout time.Duration) bool
• func KillGroup(pgid int) bool
• func ReapStale(dir string) int
• func StartTime(pid int) (time.Time, bool)
• func WaitPortFree(port int, timeout time.Duration) bool
• func WithTracker(ctx context.Context, t *Tracker) context.Context
• type Listener
  • func ListenersOnPort(port int) []Listener
• type Tracker
  • func NewTracker(dir string) *Tracker
  • func TrackerFrom(ctx context.Context) *Tracker
  • func (t *Tracker) Add(pgid int)
  • func (t *Tracker) Close()

Functions

func Alive

func Alive(pid int) bool

Alive reports whether the process exists (signal 0 probe). A permission error still means the process is there, so only ESRCH counts as gone.

func CommandName

func CommandName(pid int) string

CommandName returns the short command name for a PID via ps, or "" on error.

func KillGracefully

func KillGracefully(pid int, timeout time.Duration) bool

KillGracefully sends SIGTERM, waits up to timeout for the process to exit, then escalates to SIGKILL. It signals the whole process group (negative pid) so children spawned via `sh -c` die too, falling back to the single pid when the group signal is rejected. Returns true once the process is gone.

func KillGroup

func KillGroup(pgid int) bool

KillGroup SIGKILLs the process group led by pgid, falling back to the single pid when the group signal is rejected. Returns true if a signal was delivered to something.

func ReapStale

func ReapStale(dir string) int

ReapStale kills process groups recorded by runs that are no longer alive, and removes their sidecars. Sidecars belonging to a live process are left alone: that run is still using them. Returns the number of groups killed.

func StartTime

func StartTime(pid int) (time.Time, bool)

StartTime returns when the process began, via ps. The second return is false when the process is gone or ps could not be read. Used to tell a process apart from a later one that happens to reuse its pid.

func WaitPortFree

func WaitPortFree(port int, timeout time.Duration) bool

WaitPortFree polls the port until a loopback dial fails (nothing accepting) or timeout elapses. Returns true when the port is free. Callers use this rather than watching a pid because a graceful stop frees the port slightly before the process fully exits.

func WithTracker

func WithTracker(ctx context.Context, t *Tracker) context.Context

WithTracker attaches a Tracker to ctx so that process-spawning helpers deeper in the call stack can record what they start without every layer having to thread it through explicitly.

Types

type Listener

type Listener struct {
	PID  int
	Name string
}

Listener is a process listening on a TCP port.

func ListenersOnPort

func ListenersOnPort(port int) []Listener

ListenersOnPort returns every process listening on the given TCP port, in the order lsof reports them. Empty if lsof is unavailable, errors, or the platform isn't supported.

type Tracker

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

Tracker records the process groups spawned by the current run so that a later run can reap them if this one dies before cleaning up. It is safe for concurrent use.

func NewTracker

func NewTracker(dir string) *Tracker

NewTracker creates a sidecar file under dir keyed by this process's pid. A nil Tracker is usable and does nothing, so callers need not special-case a failure to create one.

func TrackerFrom

func TrackerFrom(ctx context.Context) *Tracker

TrackerFrom returns the Tracker attached to ctx, or nil.

func (*Tracker) Add

func (t *Tracker) Add(pgid int)

Add records a process group id. Callers invoke it immediately after starting a child, which narrows — but cannot close — the window in which a kill would orphan a child that was never recorded.

func (*Tracker) Close

func (t *Tracker) Close()

Close removes the sidecar. Reaching it means this run cleaned up after itself, so there is nothing for a later run to reap.