Documentation
¶
Overview ¶
Package procgroup signals a spawned command's whole process group instead of just its head.
Every consumer must pair Kill with SysProcAttr{Setpgid: true} on the command it spawns (OwnGroup does both for a one-shot). Without that the child inherits marotte's OWN process group, and Kill's leader guard is all that stands between a teardown and marotte signalling itself.
Index ¶
- func AlreadyGone(err error) bool
- func GroupOf(p *os.Process) (pgid int, ok bool)
- func Kill(p *os.Process, sig syscall.Signal) error
- func KillGroup(g Group, sig syscall.Signal) error
- func LiveMembers(pgid int) int
- func OwnGroup(cmd *exec.Cmd, waitDelay time.Duration)
- func WaitGone(pgid int, budget time.Duration) bool
- type Group
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AlreadyGone ¶
AlreadyGone reports whether err says the signal target had already been reaped, which for a kill is success under another name. Two spellings, one condition: a raw syscall reports ESRCH, (*os.Process).Signal translates it to os.ErrProcessDone. EPERM and EINVAL are excluded — real failures a caller must still report.
func GroupOf ¶
GroupOf reports the process group p leads, and false when it leads none. Read it BEFORE the signal that empties the group: the head can be reaped the instant it dies and getpgid(2) then answers ESRCH, leaving nothing to wait on in exactly the case where teardown worked.
func Kill ¶
Kill signals p's whole process group, falling back to the head alone when p is not its own group leader. A command that setsid()s still escapes the group.
The head alone leaks the tree: an agent-chosen command need never read stdin, and kiro-cli 2.18.0 leaves its node child reparented to init even with stdin closed. The pgid == pid guard is load-bearing — without Setpgid the child inherits marotte's own group, so Kill(-pgid, sig) would signal marotte itself.
func KillGroup ¶ added in v0.15.0
KillGroup signals every member of g, a group the caller does not lead (GroupsBelow's result). It refuses ids at or below 1, the caller's own group, a group with no live member, and a Stale g.
func LiveMembers ¶ added in v0.15.0
LiveMembers counts pgid's members in a state other than zombie, 0 for an id at or below 1. An unreadable /proc counts 0: "still alive" would burn every waiter's whole budget for no information.
func OwnGroup ¶ added in v0.15.0
OwnGroup makes an unstarted cmd lead its own process group, has its context's cancel SIGKILL that group, and bounds Wait to waitDelay after the cancel. A head-only kill leaves a child holding the output pipes, so Wait would outlive the deadline by as long as that child runs.
func WaitGone ¶
WaitGone blocks until pgid's process group holds no LIVE member, bounded by budget. A false return is worth a log line and nothing more; the signal has already been sent.
A ZOMBIE counts as gone, which is why this reads /proc rather than polling kill(-pgid, 0): an unreaped member is still signallable, and a caller's own child stays a zombie until the caller's Wait, which runs after this wait, so that probe would burn the budget on every teardown that WORKED.
Types ¶
type Group ¶ added in v0.15.0
type Group struct {
ID int
// contains filtered or unexported fields
}
Group is a process group GroupsBelow found. leader is its leader's start time (/proc stat field 22), 0 when that stat could not be read, commonly because the leader was already reaped: Stale uses it to tell the group from a later one that reuses the id once this one empties.
func GroupsBelow ¶ added in v0.15.0
GroupsBelow reports the distinct process groups of root's live descendants, leaving out root's own group, the caller's group and any id at or below 1, so every group it returns is safe to hand to KillGroup. kiro-cli's node engine leads its own group and the stdio MCP servers it spawns join that group, so a signal to the wrapper's group never reaches them.
func (Group) LedBy ¶ added in v0.16.0
LedBy reports whether g's leader is still the live process GroupsBelow stamped and a child of parent, so its pid names that child and no later process.
func (Group) Stale ¶ added in v0.15.0
Stale reports whether g's id now names a later group: a process exists at that pid with another start time. The kernel reserves a group's id while any member lives, so such a process cannot be one of g's. No process at the id is not stale: that is a group whose leader was reaped.