BB.Camera.V4L.Reaper (bb_camera_v4l v0.1.0)

Copy Markdown View Source

Kills the ffmpeg process when the Elixir process that owned it goes away.

Closing a port does not kill the program behind it, and neither does killing the port's owner. Measured on OTP 29: a sleep spawned with Port.open/2 survives both Port.close/1 and Process.exit(owner, :kill), reparented to init and running happily.

Most of the time this does not show up, because a capture is writing to a pipe nobody is reading any more and dies of SIGPIPE on its next write. But "its next write" is precisely the thing that does not happen when a camera has wedged — which is one of the main reasons the owning process died in the first place. The result is an ffmpeg holding /dev/video0 open forever, and a camera that cannot be reopened until someone finds it by hand.

So the reaper runs outside every robot, outside every camera, and outside the supervision tree that might be restarting around it. A capture registers its OS pid with watch/2 before it does anything else and release/2s it once the process is confirmed dead. If the owner dies in between — crash, brutal kill, supervisor shutdown — the reaper notices and terminates the process.

Not killing the wrong process

A pid alone is not an identity: the OS reuses them, and the window between an owner dying and the reaper acting is exactly when ffmpeg is likely to be exiting on its own. Killing a recycled pid would be far worse than leaking the original.

The reaper therefore records /proc/<pid>'s start time when it starts watching, and re-checks it immediately before every signal. A pid whose start time has changed is a different process and is left alone; so is one that has already become a zombie. This is Linux-specific, which is fine in a driver whose entire reason to exist is Linux's video API.

It will only signal a process it has an identity for — one registered through watch/2 while it was still alive. reap/2 on anything else does nothing, rather than reading an identity out of /proc at the moment it is asked to kill something, which would be reading the identity of whatever holds the pid now. That is the question being asked, not evidence toward answering it.

The residual race

Checking /proc and then sending a signal are two operations, and the process can exit between them. If the kernel then hands the pid to something else inside that window, the signal lands on the wrong process. The window is a few microseconds and crossing it needs a pid to be recycled within it, which on Linux's sequential pid allocation means wrapping the whole pid space first — but it is not zero, and nothing here can close it.

Closing it properly needs pidfd_open(2), which holds a reference to the process itself rather than to its number. The BEAM has no interface to it, and a NIF to get one is a larger change than this spike justifies.

Summary

Functions

Returns a specification to start this module under a supervisor.

Terminate os_pid now: SIGTERM, then SIGKILL after the grace period.

Stop watching os_pid, because it is confirmed gone.

Is this OS pid a live process that started when we think it did?

Start a reaper. The package's application starts one named BB.Camera.V4L.Reaper.

Terminate os_pid if the calling process dies before calling release/2.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

reap(reaper \\ __MODULE__, os_pid)

@spec reap(GenServer.server(), pos_integer()) :: :ok

Terminate os_pid now: SIGTERM, then SIGKILL after the grace period.

Does nothing unless os_pid is being watched, because only then is there a recorded identity to check the pid against. Returns once the SIGTERM has been sent, not once the process is gone — nothing here can tell you that; the owner of the port sees the exit status.

release(reaper \\ __MODULE__, os_pid)

@spec release(GenServer.server(), pos_integer()) :: :ok

Stop watching os_pid, because it is confirmed gone.

running?(os_pid, started_at \\ nil)

@spec running?(pos_integer(), integer() | nil) :: boolean()

Is this OS pid a live process that started when we think it did?

nil for started_at asks only whether something holds that pid, which is a question about the number rather than about the process. Never signal on the strength of it.

start_link(opts)

@spec start_link(keyword()) :: GenServer.on_start()

Start a reaper. The package's application starts one named BB.Camera.V4L.Reaper.

Options

  • :name — registered name. Default BB.Camera.V4L.Reaper.
  • :grace_ms — how long a process gets to exit on SIGTERM before it is sent SIGKILL. Default 2000.
  • :signaller — a 2-arity function taking the OS pid and :sigterm or :sigkill. Default sends the real signal. Tests replace it.

watch(reaper \\ __MODULE__, os_pid)

@spec watch(GenServer.server(), pos_integer()) :: :ok

Terminate os_pid if the calling process dies before calling release/2.