# `Expresso.LauncherWatch`
[🔗](https://github.com/rellen/expresso/blob/main/lib/expresso/launcher_watch.ex#L1)

The watch that halts the VM of the binary when the launcher of Burrito stops

The binary that Burrito makes is a launcher. The launcher starts the VM as
its child process, and it waits for the VM. The launcher of Burrito 1.6 does
not send SIGTERM or SIGINT on to the VM. Thus a SIGTERM to the binary stopped
only the launcher, and the VM continued with no parent. In the watch mode,
the VM then kept the port. In `--check`, the VM waited for ever on the closed
standard output.

`start/0` reads the process id of the parent of the VM, which is the
launcher. It opens a port to a shell loop. The loop reads the parent of the
VM with `ps`, and it exits when the parent is different. The VM halts when
the port closes.

The operating system gives a new parent to a process at once when its
parent stops. A test of the launcher with `kill -0` is not sufficient,
because `kill -0` succeeds for a zombie process. A launcher that stopped is a
zombie until its own parent waits for it.

The shell loop also stops after the VM halts, because `ps` then finds no VM.
The VM sees the stop of the launcher in less than one second.

# `parent`

```elixir
@spec parent(String.t()) :: {:ok, String.t()} | {:error, term()}
```

Return the process id of the parent of the operating system process `os_pid`

The function runs `ps`, which Linux and macOS give.

# `start`

```elixir
@spec start() :: {:ok, pid()} | {:error, term()}
```

Watch the parent process of the VM, and halt the VM when it stops

The function returns `{:error, reason}` and starts no watch when it cannot
read the parent process, and on Windows.

# `watch`

```elixir
@spec watch(String.t(), String.t(), (-> term())) :: {:ok, pid()} | {:error, term()}
```

Call `on_stop` when the parent of the process `os_pid` is not `parent`

The parent changes when the process `parent` stops, and also when the process
`os_pid` stops. The process that the function returns owns the port of the
shell loop. It calls `on_stop` when the port closes, and then it stops.

---

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