Module: Mutineer::OrphanGuard

Defined in:
lib/mutineer/orphan_guard.rb

Overview

Ends a forked child's process group once the process that forked it is gone (#101). A mutant or capture child leads its own process group, so a parent that dies, or is killed by a client that gave up on it, does not take the child's tests with it; without this, a hung test would run on and keep its worker database open. Needs no other part of Mutineer, so the app-side daemon can load it.

Constant Summary collapse

POLL =

Seconds between checks. A forked child gets no signal on parent death.

0.5
TEMP_PID =

Tempfile.create([".mutineer_daemon", ".rb"]) names the file .mutineer_daemon<YYYYMMDD>-<pid>-<rand>.rb (without the dot before #253). An in-process .mutineer_mutant file has the same shape (#295). The pid is the child that is loading the mutant. An undotted name is a leftover of a version before 1.7.0, so its pid is not read: a reused pid must not keep a file that stops the next boot. A held file lock still protects it.

/\A\.mutineer_(?:daemon|mutant)\d{8}-(\d+)-/
TEMP_BASENAME =

Basename glob for the mutant files of both modes. Tempfile puts hyphens in the name, so it is not a constant name. The leading dot hides a new file from Zeitwerk (#253); a file an older version left behind has none, so the glob matches both. Each boot sweep removes an orphan of either mode, so an old file of the other mode does not stop the boot (#287). The date and hyphen after the prefix keep a project's own file, such as mutineer_mutant_helper.rb, out of the sweep.

"{.,}mutineer_{mutant,daemon}#{"[0-9]" * 8}-*.rb"

Class Method Summary collapse

Class Method Details

.creator_alive?(path) ⇒ Boolean (private)

True when the pid embedded in a mutant file name is still running. Pid 0 is this process group, so it is never treated as an owner.

Parameters:

  • path (String)

Returns:

  • (Boolean)


63
64
65
66
67
68
69
70
71
72
73
74
75
76
# File 'lib/mutineer/orphan_guard.rb', line 63

def self.creator_alive?(path)
  pid_text = File.basename(path)[TEMP_PID, 1]
  return false unless pid_text

  pid = Integer(pid_text, 10)
  return false if pid <= 0

  Process.kill(0, pid)
  !zombie?(pid)
rescue Errno::ESRCH, Errno::EINVAL, RangeError
  false
rescue SystemCallError
  true
end

.locked_by_another?(path) ⇒ Boolean (private)

True when another process holds an exclusive lock on path. A lock the kernel rejects as unsupported is not ownership: the pid check still applies. A file we cannot inspect is left in place.

Parameters:

  • path (String)

Returns:

  • (Boolean)


101
102
103
104
105
106
107
108
109
# File 'lib/mutineer/orphan_guard.rb', line 101

def self.locked_by_another?(path)
  File.open(path, File::RDONLY) do |file|
    file.flock(File::LOCK_EX | File::LOCK_NB) == false
  end
rescue Errno::ENOENT, Errno::ENOTSUP, Errno::EOPNOTSUPP
  false
rescue SystemCallError
  true
end

.mutant_file_in_use?(path) ⇒ Boolean

True when a mutant file still belongs to a live process. A boot sweep must leave it alone. The database lock is taken later, so the sweep is the step that used to delete another run's file.

The creating pid is in the file name. A process that still holds the file lock counts too, even when that pid is already gone. A dead pid and a free lock is an orphan a killed child left behind.

Parameters:

  • path (String) —

    absolute path of a .mutineer_daemon*.rb or .mutineer_mutant*.rb file.

Returns:

  • (Boolean)


54
55
56
# File 'lib/mutineer/orphan_guard.rb', line 54

def self.mutant_file_in_use?(path)
  creator_alive?(path) || locked_by_another?(path)
end

.start(parent) ⇒ Thread

Starts the watchdog in the current (child) process.

Parameters:

  • parent (Integer) —

    the parent's pid, read in the parent before fork, so a parent that dies before this call is still noticed.

Returns:

  • (Thread)


34
35
36
37
38
39
40
41
# File 'lib/mutineer/orphan_guard.rb', line 34

def self.start(parent)
  Thread.new do
    sleep(POLL) while Process.ppid == parent
    # Group 0 only when this child leads its own group: a failed setpgid
    # leaves it in the parent's group, which must not be killed.
    Process.kill(:KILL, Process.getpgrp == Process.pid ? 0 : Process.pid)
  end
end

.zombie?(pid) ⇒ Boolean (private)

True when pid has exited but nobody reaped it. A container whose pid 1 does not reap orphans keeps a dead mutant child as a zombie for good, and Process.kill(0) still finds it (#250). Linux only: elsewhere there is no /proc, so a zombie still counts as running.

Parameters:

  • pid (Integer)

Returns:

  • (Boolean)


85
86
87
88
89
90
91
92
93
# File 'lib/mutineer/orphan_guard.rb', line 85

def self.zombie?(pid)
  stat = File.read("/proc/#{pid}/stat")
  # The name before the state is in parentheses and may hold ") " itself.
  # An empty read (the process exited mid-read) has no ")": not a zombie.
  close = stat.rindex(")")
  !close.nil? && stat[close + 2] == "Z"
rescue SystemCallError
  false
end