# `BB.Camera.V4L.Reaper`
[🔗](https://github.com/beam-bots/bb_camera_v4l/blob/main/lib/bb/camera/v4l/reaper.ex#L5)

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/2`s 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.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `reap`

```elixir
@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`

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

Stop watching `os_pid`, because it is confirmed gone.

# `running?`

```elixir
@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`

```elixir
@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`

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

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
