Documentation
¶
Overview ¶
Package owner labels the docker objects a run creates with the process that created them, and tells a live owner from a dead one, so a later run on the same host can remove what a crashed run left behind without touching a sibling run that is still going.
Every run-scoped object is keyed by a random run id and nothing else, and several `agentry run` processes can share one docker daemon at once (a person's two terminals, a sandbox host taking several hosted runs). So "not this process's run id" is no test of abandonment; "its owner is dead" is, provided the owner can be identified across pid reuse — a pid and its start time, judged only by a process in the same boot, pid namespace and uid (Identity). Where that cannot be established (off Linux, an unreadable /proc), nothing is labelled and nothing is swept: a leftover is litter, a sibling's container removed mid-turn is a broken run.
Index ¶
Constants ¶
const ( LabelHost = "agentry.owner.host" // Identity() of the creating process LabelPID = "agentry.owner.pid" // its pid LabelStart = "agentry.owner.start" // its StartTime )
The labels an owned object carries.
Variables ¶
var Identity = sync.OnceValues(func() (string, bool) { if self, err := os.Readlink("/proc/self"); err != nil || self != strconv.Itoa(os.Getpid()) { return "", false } boot, err := os.ReadFile("/proc/sys/kernel/random/boot_id") if err != nil { return "", false } b := strings.TrimSpace(string(boot)) pidNS, ok := nsInode("pid") if b == "" || !ok { return "", false } timeNS, ok := nsInode("time") if !ok { if _, err := os.Lstat("/proc/self/ns/time"); !errors.Is(err, fs.ErrNotExist) { return "", false } timeNS = "-" } return b + "." + pidNS + "." + timeNS + "." + strconv.Itoa(os.Getuid()), true })
Identity names the scope inside which a pid and a start time identify a process: the kernel's boot id (pids and start times restart at boot), the pid namespace (a container's pids are its own), the time namespace (the start time is reported as the reader's time namespace sees it), and the uid (a /proc mounted with hidepid shows a process only its own user's processes). Two processes with the same Identity can judge each other's liveness by pid and start time; nothing else can. ok is false where any part cannot be read, or where /proc is not this process's own (a pid namespace entered without remounting /proc), and then nothing is labelled.
var Labels = func() func() map[string]string { once := sync.OnceValue(func() map[string]string { id, ok := Identity() if !ok { return nil } pid := os.Getpid() start, ok := StartTime(pid) if !ok { return nil } return map[string]string{ LabelHost: id, LabelPID: strconv.Itoa(pid), LabelStart: strconv.FormatUint(start, 10), } }) return func() map[string]string { return maps.Clone(once()) } }()
Labels are this process's owner labels, or nil where Identity or the process's own start time cannot be read. Read once: none of it changes for the life of the process.
Functions ¶
func CommandLine ¶
CommandLine reads a process's own argv from /proc/<pid>/cmdline. ok is false when the process is gone or the record cannot be read; a sweep that would signal the process treats that as "not the one it expects".
func Dead ¶
Dead reports whether the owner a set of labels names is provably gone: labelled from this process's Identity, with a pid and start time that parse, and either no process with that pid or one with another start time. Anything it cannot prove — another identity, a missing or malformed label, a process record that exists but cannot be read, a pid that is still the same process — is not dead.
func StartTime ¶
StartTime reads a process's start time in clock ticks since boot — field 22 of /proc/<pid>/stat. With the pid it identifies a process across a pid reuse, which is what makes signalling a process group by id safe to attempt at all (the engine's host_unix.go). ok is false when the process is gone or the record cannot be read.
Types ¶
This section is empty.