# Process model

Every ordinary command runs in a fresh private wasm64 memory and Worker. The
kernel ([`process-kernel.c`](../kernel/process-kernel.c)) owns files, open-file
descriptions, pipes, local sockets, pseudo-terminals, process records, signals and the terminal; processes
inherit handles and values, never another address space. The call path is in
[architecture](architecture.md#system-calls); packet layouts are in
[`process.h`](../include/dolly/process.h) and each [host module](../host/README.md)'s header.

```mermaid
sequenceDiagram
  participant Sh as Parent (Slop)
  participant K as Kernel
  participant S as Supervisor
  participant C as Child Worker
  Sh->>K: SPAWN path, argv, env, fd mappings
  K-->>Sh: child pid
  S->>K: next event: launch
  K-->>S: executable bytes
  S->>C: new Worker, which makes its memory and gate
  Sh->>K: WAIT pid (deferred)
  Note over K,C: Ctrl+C or kill: SIGINT is pending
  K-->>C: next call returns -EINTR
  C->>K: INTERRUPT_POLL, run handler, SIGNAL_ACKNOWLEDGE
  Note over K,C: handler unfinished 500 ms later: the kernel ends it, the supervisor stops its Worker
  C->>K: EXIT status, or signal termination
  S->>K: Worker retired
  K-->>Sh: WAIT returns exit status or signal
```

## Executables

- Import one private shared memory64 and one function,
  `dolly_process_0.call`; export `_start`; carry `dolly.process` stamps
  ([`dolly-process-0.wat`](../abi/dolly-process-0.wat)) and a `dolly.host`
  record with the ABI digest of each host module they link
  ([`dolly-host-0.wat`](../abi/dolly-host-0.wat)). Memory is at most 8 GiB,
  and the file at most 512 MiB: a larger one fails the spawn with `ENOEXEC`.
- A start section may initialize memory/TLS but must not call the kernel.
- Found through `PATH`; `#!` lines name an absolute in-Wasm interpreter, nested at most 4 deep.
- `readlink("/proc/self/exe")` returns the loaded image's canonical path, and
  `readlink("/proc/PID/cwd")` the directory a process that has not exited
  stands in; there is no general `/proc`. `dladdr` names that path for the
  program's own functions and static data, and nothing for the heap, the stack
  or a module `dlopen` loaded.
- Opening `/proc/processes` for reading gives the processes that have not
  exited, a line each in PID order, `PID PARENT STATE ARGUMENTS`: the state is
  `starting` until the program runs and `running` from then, the arguments
  are joined by spaces with each control character as `?`, and a line ends
  after 1023 bytes. It is the kernel's answer: the file is empty, so that
  `ls /proc` lists it and `stat` finds it, as on Linux, and each open of it,
  by any path, is its own copy of the table in a pipe; neither the file nor
  its descriptor takes a write, and sessions do not save `/proc`.
  [`ps`](../Dollyfile-ps) prints it under a heading.
- The target's identity: a program sees `__dolly__`, `__unix__` and
  `__wasm64__`, and no macro of Emscripten, Linux or WASI; `cc -dumpmachine`
  prints `wasm64-unknown-dolly` and `uname` `Dolly wasm64`. The libc is a
  bootstrap whose headers test `__dolly__`; LLVM and Zig still generate
  code under its Emscripten name, which no program can test.
- The compiler is itself a private process behind `cc`, `c++`, `ld` and `ar`
  ([`compiler.cpp`](../programs/compiler.cpp)). It defaults to Clang's `-std=gnu17` and
  `-std=gnu++17` but to `-O2`, and follows Clang's suffix rules; objects are always position
  independent, `-m64` is the only target, `-lc -lm -ldl -lrt -lpthread -lutil`
  add nothing, and `-Wl,--no-undefined`, `--allow-shlib-undefined` and
  `--as-needed` are accepted and ignored: Dolly links no ELF shared libraries,
  and the exact typed import validation after linking decides.
- The supervisor caches compiled modules by SHA-256 (64 entries, 256 MiB), never
  instances. It admits a spawn while fewer than 56 processes exist and either
  their committed Wasm memory is under 4 GiB or the spawning process has no
  live child: the budget bounds fan-out such as `make -j`, and a chain of
  processes each waiting for the next always progresses. A spawn over the
  budget waits until a process ends, however long, since make and Cargo end a
  build at a spawn's `EAGAIN`; one past the count waits up to 5 s, then fails
  `EAGAIN`. Either wait is a blocking call a signal interrupts. So a pipeline
  started over the budget waits forever if its first stage fills the pipe
  before the next stage is admitted; Ctrl+C ends it.
- Which limits are the contract: the kernel's tables, which every host runs —
  56 processes (`RLIMIT_NPROC`), 1024 descriptors a process (`RLIMIT_NOFILE`),
  64 pipes — and what executables are linked with, an 8 GiB memory ceiling
  (`RLIMIT_AS`) and an 8 MiB stack. The rest is the browser host's own, chosen
  for a tab's Workers and memory: the 4 GiB budget, the 5 s wait at the count,
  the module cache and threads@0's 32 threads a process and 64 in all. Another
  host sets its own; programs meet them only as waits and `EAGAIN`, which any
  spawn or `pthread_create` may return.
  A start does not read an executable whose module is cached: the kernel opens the
  file and gives its version (`dolly_process_image_version`, a number every write and
  size change of the file renews), and only a version the supervisor has not compiled
  is copied out of the file's own blocks (`dolly_process_image_block`; the kernel makes
  no copy of its own) and hashed.
- A refusal is reported to the program that asked, not to the person at the
  page. An executable the loader refuses (a wrong stamp or import, a host module
  the session does not have or whose layout differs, a thread client without
  `dolly_thread_start`) and a Worker that fails while running exit with status
  126 after one line on the process's own descriptor 2 that names the cause
  ([`process-supervisor.mjs`](../page/process-supervisor.mjs)); unrelated
  processes are unaffected. Only `cc -pthread` links the thread client, and it
  exports the thread entry, so what it links the loader runs.
- A malformed call returns an errno and the process keeps running: `EFAULT` for
  a packet outside its memory, `E2BIG` over 1 MiB, `ENOSYS` for an unknown
  operation, `EINVAL` for a wrong layout
  ([`process-worker.mjs`](../page/process-worker.mjs)). FFI packets (`dso@0`) carry
  pointers of the process itself; a wild one is `EFAULT` too, while a trap in
  the function an FFI call reaches ends the process like any other trap.
- Wasm calls nest on a browser stack that a page cannot size; a program that
  exhausts it fails with 126 like any other trap. The Worker enters an
  executable that asks for it, as the compiler and Emacs do, through
  `WebAssembly.promising` where that stack is measured half again as deep:
  in Chrome, not in Firefox ([browser stack](browser-stack.md)). A program
  `stack-wrap` rewrote records `stack@0` and continues on fresh stacks
  instead of ending.
  `RLIMIT_STACK` describes only the stack inside the process's memory.
- `cc`, `c++`, `ld` and `ar` retry status 126 up to twice
  ([`runtime-adapter.c`](../process/runtime-adapter.c)), so long
  source builds survive a transient browser Worker allocation failure without
  hiding deterministic source errors.

## Descriptors and files

- 1024 descriptors per process, Linux's default soft limit: Zig compiling
  Ghostty holds more than 256. Descriptor flags are per handle; offsets and status
  flags belong to the shared open description. `FD_CLOEXEC` works everywhere.
  `getrlimit` reports the fixed limits (`RLIMIT_NOFILE` 1024, `RLIMIT_NPROC` 56,
  `RLIMIT_AS` 8 GiB, `RLIMIT_STACK` 8 MiB), and `setrlimit` to anything else
  fails with `EPERM`; `sysconf(_SC_OPEN_MAX)` is still libc's constant 1024.
  So is the one scheduling priority, nice 0: `nice` and `setpriority` to
  another fail with `EPERM`.
- Pipes hold 64 KiB, and the kernel at most 64 of them (an open of
  `/proc/processes` among them); one more fails with `ENFILE`. Empty reads
  and full writes return `EAGAIN` when
  nonblocking; closing all writers gives EOF, also to a reader that was
  waiting. Writing with no reader, or waiting to write when the last reader
  closes, returns `EPIPE`, and libc raises `SIGPIPE` in the writer before
  `write` returns ([`libc-adapter.c`](../process/libc-adapter.c)): the
  process ends with that signal unless it ignores, handles or blocks it. A
  process's descriptors close when it exits, before it is waitable.
- Opening `/dev/stdin`, `/dev/stdout` or `/dev/stderr` duplicates the caller's
  descriptor 0, 1 or 2.
- The terminal is the boot terminal ([`dolly.c`](../kernel/dolly.c)): a
  [pseudo-terminal](#pseudo-terminals) the kernel opens with its first write
  and holds the master of. The page's root processes start with its slave as
  descriptors 0, 1 and 2, one open file for all of them. What they write
  reaches the [display](display.md#terminal), or the bootstrap log while no
  display is attached; what the input module decodes is typed into it when a
  reader asks. Its size is the display's: `TIOCSWINSZ` on it fails with
  `EPERM`, and a new grid is `SIGWINCH` for the processes that hold it.
- `/dev/tty` opens the terminal a process stands on, the first of its
  descriptors 0, 1 and 2 that is one, or else the boot terminal.
  `ttyname` fails: a terminal has no name of its own. Every process is its
  own group: `tcgetpgrp` on a terminal gives the caller's PID while it is in
  the terminal's foreground (the foreground owner and what descends from it,
  every process that holds a pseudo-terminal's slave), the owner's PID to
  another, and `ENOTTY` for any other file. Nothing gives the terminal to
  another group: `tcsetpgrp` fails `ENOTTY`, which a shell such as zsh takes,
  without a word, for running without job control.
- `poll` covers files, pipes, sockets, pseudo-terminals and the terminal; signals wake it with `EINTR`.
- A terminal starts in the mode `stty sane` leaves: `ICANON`, `ECHO`, `ICRNL`,
  `OPOST` with `ONLCR`, and `ISIG`. It edits a line while `ICANON` is set: a
  read waits for Enter, which arrives as LF, and returns one line; Backspace
  and Ctrl+U erase, Ctrl+D ends a line without LF or, on an empty one, is end
  of file; `ECHO` shows what is typed. With `ICANON` clear a read returns the
  bytes as typed. The raw read of `runtime.h` (`dolly_terminal_read_raw_timeout`),
  Slop's and Janis's, takes one byte unedited in either mode. `OPOST`/`ONLCR`
  map LF to CRLF on output. While `ISIG` is set, the interrupt key, `VINTR`,
  sends SIGINT to the foreground: Ctrl+C unless a program sets another (Emacs
  sets C-g, and `VQUIT` to the same key); a program that clears `ISIG` (raw
  mode) reads that key as its byte. Under `ISIG` there is always a key, no quit
  key of its own and no job control, so `VINTR` is on, `VQUIT` off or `VINTR`'s
  key and `VSUSP` off.
  `ICRNL` reads an input CR as LF, so Enter arrives as LF until a program
  clears it (raw mode does), and `INLCR` an LF as CR. A non-canonical read
  returns the bytes queued, at least one (`VMIN` 1), or with `VMIN` 0 returns
  without a byte, at once or after `VTIME` tenths of a second (kilo's raw
  mode). termios reports no other input mapping, no flow control or other
  signal keys, and no `VMIN` above 1; `tcsetattr` rejects anything else with
  `EINVAL`. `TCSAFLUSH` and `tcflush` discard unread input; break and flow
  control fail with `ENOTSUP`.
- There is one user and no permission bits: `chmod`, `chown` and `access` only
  check that the file exists, and nothing changes a file's mode
  ([why](architecture.md#decisions)).
- Files keep no extended attributes: `getxattr`, `setxattr`, `listxattr`,
  `removexattr` and their `l` and `f` forms fail with `ENOTSUP`.
- An image holds no times: at every boot each of its paths is dated
  1980-01-02 UTC, older than anything a session makes, so make never rebuilds
  for an image file, after a [session](sessions.md) restores its own times too
  ([`system-snapshot.c`](../kernel/system-snapshot.c)).
- `statvfs` reports kernel memory: its maximum as capacity, unallocated memory
  as free, and no inode limit (zero files).
- The cwd is an open directory handle: it follows renames, `getcwd` fails with
  `ENOENT` after unlink, `fchdir` works.
- `mmap` makes private copies; `MAP_SHARED` writes back on `msync` and whole
  `munmap` ([`mmap.c`](../process/mmap.c)). Mappings are not coherent with
  other writers, do not extend the file past EOF, and cannot trap there: Wasm
  cannot protect or revoke part of linear memory. So `mprotect` grants read
  and write, which memory always is (a shared mapping made without write then
  writes back, `EACCES` if its descriptor is read-only), and any other
  protection fails `ENOTSUP`, as `mmap` with `PROT_EXEC` does. `munmap` takes
  a whole mapping, or a range that holds none; part of one is `EINVAL`.
- Advisory locks live in one kernel table of 1024 for all processes; a request
  that needs one more fails with `ENOLCK`. `flock` locks the whole file for an
  open file description: descriptors made by `dup` or inherited by a spawned
  child share the lock, and it goes with the last of them. Converting gives
  the held lock up first, as on Linux, so a refused `LOCK_NB` conversion leaves
  none. `fcntl` `F_SETLK`, `F_SETLKW` and `F_GETLK` (and `lockf`) lock byte
  ranges for the process, splitting and merging what it holds; as POSIX says,
  closing **any** descriptor of a file drops all the process's locks on that
  file. Not the descriptors libc keeps for itself, for a shared mapping or
  inside `truncate`: those are marked `DOLLY_PROCESS_FD_KEEP_LOCKS`. The two
  kinds do not see each other, and neither stops `read` or `write`. A waiting request is parked like a pipe read: a release wakes it at
  once and a signal interrupts it. Waiters are not ordered and deadlocks are
  not detected (no `EDEADLK`). Exit, a kill and a failed Worker release every
  lock of the process. `F_OFD_*` is `EINVAL`; a pipe or socket cannot be
  locked (`ENOTSUP`).

## Local sockets

`sockets@0` ([`host/sockets/dolly-sockets-0.wat`](../host/sockets/dolly-sockets-0.wat),
[`host/sockets/kernel.c`](../host/sockets/kernel.c)): stream sockets between
processes of this kernel. The bytes stay in kernel memory, as a pipe's do, and
the module has no browser import: nothing here reaches a network.

A program asks for them when it links: `cc ... -ldolly-sockets` takes the
socket calls from the module's client, which records `sockets@0`, and the
image that keeps the program declares `REQUIRES HOST sockets@0`. A program
that does not ask is unchanged: every socket call is libc's refusal,
`ENOSYS`, and nothing is recorded, so a tool with a network path it never
takes here needs no line. The rest of this section is what a program gets
that asked.

- `socketpair(AF_UNIX, SOCK_STREAM)` gives two connected descriptors, which
  spawn inherits like any other. A server binds a path, listens and accepts;
  a client that shares no descriptor with it connects to the path.
- A socket reads, writes, polls, duplicates and closes like a pipe, 64 KiB
  each way; `send` and `recv` take `MSG_DONTWAIT`, `send` also `MSG_NOSIGNAL`.
  A stream has no record boundaries: a write takes what fits and a blocking
  one waits for the rest. A closed, shut down or dead peer is end of file to
  a reader, also one that was waiting, and `EPIPE` to a writer, with `SIGPIPE`
  as for a pipe. `poll` reports a pending connection as readable and a closed
  peer as hung up; `shutdown` ends one direction.
- A bound path is an empty file that `stat` reports as a socket; `bind` fails
  with `EADDRINUSE` when the name exists. `connect` finds the listener by the
  file, so a renamed path still connects; an unlinked one leaves the listener
  and its connections alone and can be bound again. The file stays when its
  socket closes or its process ends: `connect` then fails with
  `ECONNREFUSED`, as for any path nobody listens at, and a server unlinks a
  stale path before it binds.
- `connect` returns once the listener has room for the connection, before it
  is accepted, and the client may write at once. A listener holds at most 16
  unaccepted connections (`listen`'s backlog, 1 to 16): a blocking `connect`
  waits for room, a nonblocking one fails with `EAGAIN`. Connections nobody
  accepted end with their listener.
- The kernel holds at most 128 sockets, a connection being two; one more
  fails with `ENFILE`. A socket goes with its last descriptor, so exit, a
  kill and a failed Worker release what a process held.
- Refused by name: every other family (`AF_INET` and `AF_INET6` fail with
  `EAFNOSUPPORT`, so a program takes the path it has for a host without a
  network), datagram and seqpacket sockets (`EPROTOTYPE`), descriptor
  passing (`sendmsg` with control data, `ENOTSUP`), abstract names
  (`ENOENT`) and every `setsockopt` (`ENOPROTOOPT`). `getsockopt` answers
  `SO_TYPE` and `SO_ERROR`. A socket call on another descriptor fails with
  `ENOTSOCK`.

## Pseudo-terminals

`pty@0` ([`host/pty/dolly-pty-0.wat`](../host/pty/dolly-pty-0.wat),
[`host/pty/kernel.c`](../host/pty/kernel.c)): a terminal one program gives
another, as a terminal multiplexer gives each of its panes. The bytes stay in
kernel memory, as a pipe's do, and the module has no browser import. The
pseudo-terminal itself is the kernel's ([`pty.c`](../kernel/pty.c)), which the
boot terminal and `console@0`'s terminals are too: without `pty@0` they stay
and programs cannot open one.

A program asks when it links: `cc ... -ldolly-pty` takes `openpty` from the
module's client (the `libdolly-pty` package), which records `pty@0`, and the image that keeps the program
declares `REQUIRES HOST pty@0`. Without it `openpty` is libc's, which finds
no `/dev/ptmx` and fails with `ENOENT`. The program on the slave links
nothing and declares nothing: any program built for Dolly runs on one.

- `openpty` gives two descriptors, a master and a slave, neither inherited by
  a spawned program unless it is mapped. Each reads, writes, polls,
  duplicates and closes like a pipe: what is written to the master is the
  slave's input (4 KiB unread), what is written to the slave is read from the
  master (64 KiB). A write takes what fits; a master that does not wait gets
  `EAGAIN` for the rest.
- The slave is a terminal to the program that holds it, with a mode and a
  size of its own: `isatty`, termios and `TIOCGWINSZ` answer as for the
  boot terminal, with the same discipline (`ICANON`, `ECHO` to the
  master, `OPOST` with `ONLCR`, `ISIG`, `ICRNL` and `INLCR`). Input is typed
  into the line, edited and echoed, when a read or a poll asks under
  `ICANON`, so a program that clears it first reads what was typed before
  unedited. A process whose descriptor 0, 1 or 2 is a
  slave opens it as `/dev/tty`: the same open file again, so `O_NONBLOCK` set
  there is set for every process that holds the slave. The master is not a
  terminal, but termios and `TIOCGWINSZ` on it reach the slave's mode and
  size, as on Linux, where a terminal emulator sets its slave's mode that way.
- `ioctl(TIOCSWINSZ)` on the master sets the size, and the processes that
  hold the slave get `SIGWINCH`.
- While `ISIG` is set, the slave's `VINTR` character (byte 3 unless a program
  set another) written to the master is `SIGINT` for the processes that hold
  the slave. The one the others descend from is spared
  while it has them: a shell, while its command runs. A process group is one
  process, so none names a foreground.
- Closing the master is `SIGHUP` to the processes that hold the slave, end of
  file to their reads and `EIO` to their writes. A read of the master fails
  with `EIO`, as on Linux, once every descriptor of the slave is closed and its
  output is read.
- The kernel delivers these signals as it delivers a kill
  (`dolly_process_next_event`, [`dolly-supervisor-0.wat`](../abi/dolly-supervisor-0.wat)):
  a program that does not answer `SIGINT` or `SIGHUP` within 500 ms is ended,
  unless it ignores the signal.
- The kernel holds at most 32 pseudo-terminals besides the boot terminal; one
  more fails with `ENFILE`.
  One goes with the last descriptor of its two ends, so exit, a kill and a
  failed Worker release what a process held.
- A shell on a slave publishes no command result to the page: the page
  follows the shell at the boot terminal.

`console@0` ([`host/console/dolly-console-0.wat`](../host/console/dolly-console-0.wat),
[`host/console/kernel.c`](../host/console/kernel.c)) gives the host the
standard streams of a root process it starts: a terminal into the session for
something outside it, a socket or a second view, or pipes for a program run on
input the host has. A terminal console is a pseudo-terminal whose master end
the host holds: the root process's descriptors 0, 1 and 2 are its slave, and
the host types into it, reads what its programs show, resizes it and hangs it
up; all the rest is the pseudo-terminal's above, and it is one of the 32. A
pipe console is three pipes of 64 KiB: descriptor 0 reads what the host writes
until the host ends it, 1 and 2 are read by the host apart, byte for byte, and
a write the host no longer reads is `EPIPE` and `SIGPIPE`, as a kernel pipe's.
There are at most 32 consoles. In the browser an image that declares the
module gets `openConsole()` on boot()'s handle (`docs/embedding.md`, "A
terminal into the session"); another host adds it to the images it runs.
- Not there: `/dev/ptmx` and a path for a slave (`posix_openpt`, `ptsname`
  and `forkpty` fail), sessions and controlling-terminal ioctls. The name
  `openpty` returns, `/dev/pts/N`, is for display.

## Spawn and wait

- Spawn inherits no descriptors, the standard streams, or all non-CLOEXEC
  descriptors, then applies explicit parent-to-child mappings, all read from the
  parent at once. A spawn may set the child's cwd.
- `posix_spawn` inherits all non-CLOEXEC descriptors and replays its file
  actions in order ([`runtime-adapter.c`](../process/runtime-adapter.c)):
  `adddup2` and `addclose` as mappings, a closed one keeping the child from
  inheriting the descriptor; `addchdir_np` chooses the child's directory, and
  `addopen` opens the file in the parent, from that directory, for the child.
  The child starts with the caller's signal mask and the signals it ignores,
  as after `fork` and `exec`, less what `POSIX_SPAWN_SETSIGMASK` and
  `POSIX_SPAWN_SETSIGDEF` reset; every handled signal is at its default
  action. A session, process group or scheduler returns `ENOTSUP`. A child of
  `runtime.h`'s spawns starts with every signal unblocked at its default
  action. There is no `fork`: it fails with `ENOSYS`.
- Each process is its own process group and its own session, which it leads:
  `getpgid`, `getpgrp` and `getsid` give its PID (the caller's for 0, `ESRCH`
  for none), `setpgid` of a process to itself succeeds and any other fails
  `EPERM`, as `setsid` does ([`libc-adapter.c`](../process/libc-adapter.c)).
  `kill(0)` signals the caller and `kill(-PID)` that one process, not its
  descendants; `kill(-1)` fails `ENOTSUP`.
- `waitpid` accepts a child PID, `-1` or `0`, and `-PID` for the group the
  child PID is, with `WNOHANG`, `WUNTRACED` and
  `WCONTINUED`: no child ever stops or continues. Wait records distinguish signal termination from exit:
  `exit(130)` is not SIGINT. A child that has exited is there until it is
  waited for: `kill` of it succeeds and does nothing.
- `system` and `popen` run their command as `/bin/slop -c`, given the
  standard streams only; `system` ignores SIGINT and SIGQUIT and blocks
  SIGCHLD while it waits, as POSIX says, so Ctrl+C ends the command and not
  its caller.
- Timed spawns carry an absolute monotonic deadline at most one day away; the
  kernel ends the child with status 124 even inside a pure CPU loop, its
  descendants first by SIGKILL.
- `SPAWN_FOREGROUND` and `SPAWN_INTERACTIVE` are explicit roles. Ctrl+C with
  `ISIG` set sends SIGINT to the foreground tree; like a job-control shell, an
  interactive owner with running children is spared. The page asks for it
  through its terminal mailbox; the boot terminal's `VINTR` typed under
  `ISIG` is the same. Slop clears `ISIG` while
  it reads a line, so Ctrl+C at its prompt is input. Image scripts
  use `/bin/foreground`; the browser knows no command names. Only the
  foreground tree can pass the role on; retirement returns it to the nearest
  foreground ancestor.
- Retirement ends the Worker before the child is waitable, and the memory and
  gate with it: they live in the process's Workers alone, so the pages go when
  the Workers do, not when the runtime Worker next collects garbage. A thread's
  Worker that has not started takes the memory posted to it and ends itself:
  Chrome keeps what was posted to a Worker terminated before it runs.
- A child outlives a parent that exits, as on POSIX: a child still running
  loses it (its parent is 0) and is reaped when it ends, as init reaps
  orphans. The terminal goes back to the parent's foreground ancestor, as a
  shell takes it back when a job ends. A parent a signal ends takes its
  descendants with it, by that signal, as a signal to its process group
  would: a Dolly group is one process, so the command of `slop -c` is the shell's
  child unless the shell `exec`s it, and a closed terminal's `SIGHUP` ends its jobs. A timed
  command's deadline ends its whole tree, as `timeout` signals the command's
  process group.
- Worker termination has no completion event, so a large interactive process
  gets 500 ms of reclamation before its exit is acknowledged, sparing the
  recovery shell. A thread whose call ends it (its EXIT or THREAD_EXIT, or any
  call once the supervisor ends its Worker) leaves Wasm by a trap in the gate
  and its Worker closes itself: no destructor or landing pad of the program
  runs, as a JavaScript exception thrown into Wasm would let them. Nothing guarantees against browser memory pressure; this is
  one reason Slop itself is [serial](architecture.md#decisions) and parallel
  builds need a modest `-jN`.

## Exec

`execve` and its family (`execv`, `execvp`, `execl`, ...) replace the program
of the calling process (`DOLLY_PROCESS_EXEC`, [`process.h`](../include/dolly/process.h)).

- The process keeps its pid, parent and children (the new program waits for
  them), cwd, locks, alarm, pending signals, terminal roles (foreground,
  interactive) and a timed spawn's deadline, and its descriptors without
  `FD_CLOEXEC`. The new program starts with the old one's signal mask,
  ignored signals and signals pending in it; every handled signal is back at
  its default action. A parent's `waitpid` gets the new program's status.
- What goes: the old program's memory and Workers, its threads (exec from any
  thread ends the others), mappings, DSOs, `atexit` handlers, and what its
  host modules held for it. `MAP_SHARED` writes are not written back, as at
  exit. stdio is not flushed: a program flushes before it calls `exec`.
- A program that cannot run fails the call and the old one goes on: a missing
  file is `ENOENT`, a file that is no Wasm and has no `#!` line `ENOEXEC`, and
  an executable the loader refuses (a stamp, an import, a host module the
  session has not) `ENOEXEC` after one line on the process's descriptor 2
  that names the cause. The kernel reads the program and the supervisor
  compiles and admits it while the old program waits in the call; only then
  does the old program go ([`process-supervisor.mjs`](../page/process-supervisor.mjs)).
- A signal delivered while the new program is prepared interrupts the call:
  the old program handles it, and libc calls `exec` again. Between the old
  Worker's end and the new one's start the process is `starting`, as a spawned
  one is: a signal the old program ignored is ignored, one it blocked waits
  for the new program, and any other ends it.
- A large interactive program gets the 500 ms of reclamation it gets at exit
  before its successor's memory is made.

## Signals

- Supported: `SIGHUP`, `SIGINT`, `SIGQUIT`, `SIGABRT`, `SIGKILL`, `SIGUSR1`,
  `SIGUSR2`, `SIGPIPE`, `SIGALRM`, `SIGTERM`, `SIGCHLD`, `SIGWINCH`; others
  are rejected, and only the kernel sends another process `SIGCHLD` (`kill`
  with it fails with `ENOTSUP`).
- Handlers run in Wasm at syscall boundaries ([`signal.c`](../process/signal.c))
  with masks, `SA_RESTART`, `SA_RESETHAND`, `SA_NODEFER` and `SA_SIGINFO`.
  Alternate stacks, `sigwait`, asynchronous preemption and `SA_NOCLDWAIT` are
  unsupported.
- The kernel knows what each program does with each signal: libc tells it
  the ignored and the handled ones after every change
  (`DOLLY_PROCESS_SIGNAL_DISPOSITIONS`). An ignored signal is discarded when
  it is sent; it interrupts no call and ends no process.
- A process that does not finish a delivered signal within 500 ms is terminated:
  the kernel decides (`dolly_process_next_event`), the supervisor stops its
  Workers. The filesystem and the shell survive; kernel or supervisor failure is outside
  this guarantee. Until a handler is finished the kernel delivers the process
  no other signal.
- A handler is finished when it returns, and when it leaves by `longjmp`,
  `_longjmp` or `siglongjmp`, as a pager or a shell leaves a blocked read.
  `sigsetjmp(env, 1)` saves the signal mask and `siglongjmp` restores it,
  delivering what that unblocks before it jumps; after `sigsetjmp(env, 0)`
  and after `setjmp` the jump leaves the handler's mask, as on Linux, and the
  program unblocks its signal itself. libc sees the jump because `<setjmp.h>`
  declares these as its own functions: a program that declares `longjmp`
  itself is not seen leaving, and its handler stays unfinished. A jump made
  and caught inside a handler counts as leaving it.
- Normal exit runs `atexit` handlers; default signal termination and forced
  termination do not, so named temporary files may remain.
- Delivered handlers interrupt sleep, `poll` and `pause`; `SA_RESTART` restarts
  read, write and wait. Ignored or blocked signals do not shorten sleeps.
- Because handlers run only when a syscall starts, `pselect` is the race-free
  way to wait for a descriptor or a blocked signal: a pending signal its mask
  unblocks interrupts it before the wait; `sigsuspend` is that wait without
  descriptors, and `select` the wait without a mask.
- `SIGCHLD` is queued once a child is waitable. While a parent ignores
  `SIGCHLD` its children are reaped as they end, as POSIX says: `wait`
  returns once none is left, with `ECHILD`. `SIGWINCH` follows terminal
  resizes and never forces termination.
- `alarm`, `setitimer` and `getitimer` support only `ITIMER_REAL` (others fail
  with `EINVAL`); the kernel raises due timers when the supervisor asks it at
  the time it named (`dolly_process_service_milliseconds`). A
  default-action SIGALRM is delivered like `kill`, ending even a CPU loop; a
  handled one only becomes pending and never forces termination.
- Clock reads use the Worker's clock aligned to the kernel's origin, but enter the
  kernel at least once per millisecond so signals arrive in clock-only loops.
  Linux's `CLOCK_MONOTONIC_RAW` and `CLOCK_MONOTONIC_COARSE` read the monotonic
  clock, which is never slewed, and `CLOCK_REALTIME_COARSE` the real-time one
  ([`time.c`](../process/time.c)); other Linux clocks fail with `EINVAL`.
- CPU time is not accounted: `clock()`, `CLOCK_PROCESS_CPUTIME_ID`,
  `getrusage` and `times` report the monotonic time since the program started
  (since its `exec`, if it was exec'd) as its user time, an upper bound that is
  exact while it computes without blocking; system time and children's times,
  `wait4`'s too, are zero ([`libc-adapter.c`](../process/libc-adapter.c)).

## Threads, DSOs and FFI

- `threads@0` ([`host/threads/dolly-threads-0.wat`](../host/threads/dolly-threads-0.wat),
  [`host/threads/threads.mjs`](../host/threads/threads.mjs)): statically linked `-pthread`
  programs, one Worker per thread sharing the process memory, at most 32 per
  process and 64 in total; `sysconf` reports 4 processors to them (1 without
  `-pthread`). The memory takes its
  maximum, 8 GiB, as the process starts and never grows: Chrome checks a copy,
  fill or atomic access against each thread's own record of the size, which
  another thread's growth updates late. Where the browser will not commit it
  (Chrome's sandbox limits a renderer's data, Linux's heuristic overcommit
  Firefox's), half is asked, down to the initial size; the console says what
  was given, and malloc fails with `ENOMEM` beyond it. Handlers run on the
  main thread, also while it waits in `pthread_join`. A host of libraries
  loads them in every thread (below); no cancellation or directed signals.
- Without `-pthread` a program is one thread
  ([`pthread-stubs.c`](../process/pthread-stubs.c)): `pthread_create` and
  `pthread_cancel` fail with `ENOTSUP`, a lock it holds is busy, and waiting
  for it is `EDEADLK` or, with a deadline, `ETIMEDOUT` there; a condition's
  timed wait lasts until its deadline; a barrier of more than one fails with `EAGAIN`.
- `dso@0` ([`host/dso/dolly-dso-0.wat`](../host/dso/dolly-dso-0.wat),
  [`host/dso/process.mjs`](../host/dso/process.mjs)): process-local DSOs and
  FFI, served in the Worker of an executable that records the module
  ([host modules](../host/README.md#modules-served-in-the-process-worker)).
  - `cc -rdynamic` builds a host: it exports the program's symbols and links
    the loader behind `dlopen`. A DSO (`cc -shared`) shares its owner's
    memory, table and allocator; the loader checks exact import types before
    instantiation. A DSO reaches a C++ `thread_local` of the process (libunwind's
    `__wasm_lpad_context`, which its catch clauses need) at the address the
    variable's `_ZTW` wrapper returns; a C `_Thread_local` it cannot reach.
  - FFI calls and closures (`dolly_ffi_*`, `<dolly/dso.h>`) stay in the process
    Worker; libffi supports CPython `_ctypes`.
  - In a program using `threads@0` each thread's Worker has a function table
    of its own. In a host (`cc -pthread -rdynamic`) what the loader or a
    closure adds to one table, every thread adds to its own in the same order,
    so at the same indices (`host/dso/threads.mjs`):
    the change goes into a record in the host's `__dolly_dso_threads`, and a
    thread applies the records it has not before it runs on: at its start,
    after a call that waited for the kernel, around a futex wait (libc's go
    through `DOLLY_DSO_WAIT`). `dlopen`, `dlsym` and a closure's preparation
    return once every other thread has applied the change or waits in the
    host, which it leaves only through the records; a thread that computes
    without a call delays them until it makes one. The library's data is
    relocated and its constructors run once; each other thread gets a block
    for its thread-locals (`__wasm_init_tls`, which `cc -shared` exports) and
    resolves its own `GOT.mem` entries. A threaded program that is not a host
    calls functions only: closures are refused with `ENOTSUP`.
  - A program passed through Binaryen's cast emulation (`cc
    --dolly-cast-emulation`, `wasm-opt --fpcast-emu`) holds nothing but thunks
    of one signature in its table, sixteen or more `i64` parameters and an `i64`
    result, which every indirect call uses. GObject programs need it: they call
    functions through casts to types of other parameters (Blender's Python
    methods too). Such a host loads a library linked so too (`cc -shared
    --dolly-cast-emulation`), whose table entries are thunks of the same
    signature; a library with entries of other signatures is refused, and a
    cast-emulated one is refused by any other program. A function the loader
    places in the table (a `GOT.func` entry, `dlsym`) goes in as a thunk of
    that signature, as Binaryen's convert, or as the program's own thunk where
    it has one, so that a pointer to a function compares equal wherever it was
    taken. A closure goes in as the thunk of the function made for it.
  - A program's function exports, but `_start` and Dolly's own (`dolly_*`,
    `__dolly_*`), are entries of a table the process Worker adds to the module
    (`__dolly_exports`), where the loader finds them: Chrome makes an object of
    every export when it instantiates a module, 50 MiB in each Worker for the
    234,338 functions a program linked `-rdynamic` exports, of the 4 GiB a tab's
    Workers share; a table costs 8 MiB, its entries made when first read.
  - Without the record a program loads nothing: `dlopen` returns `NULL` with
    `ENOSYS` and a `dlerror()` naming `-rdynamic` and `dso@0`, and the raw
    operations are unknown ones. With it, the image must declare
    `REQUIRES HOST dso@0` or the program is refused before it starts.

## Host modules at run time

- An image's host modules are the `REQUIRES HOST` lines of its recipe. A
  session of an image that declares `nena@0`
  ([`host/nena/dolly-nena-0.wat`](../host/nena/dolly-nena-0.wat),
  `<dolly/nena.h>`), as `default` does, may enable and disable modules while
  it runs; any other image's list is fixed, and nothing in Wasm changes it
  ([browser boundary](browser-boundary.md#host-modules)).
- `nena` lists every module of the page with its state and what it gives;
  `nena enable NAME...` and `nena disable NAME...` switch them; `amy install`
  runs `nena enable` for the modules a package needs. The loader's refusal of
  a program and the engine's refusal of a package name the command:
  `host module gpu@0 is not enabled: nena enable gpu`.
- Enabling starts the module as at boot: a device module is enabled also
  where the browser has no such device, and its programs' OPEN fails with
  `ENODEV`. A module whose check the browser does not answer within five
  seconds is refused, and the refusal says so. Disabling takes it away at once: programs that
  record it are refused, and a running program's next call through it fails
  with `ENOSYS`. Sockets and other state a module keeps in the kernel stay
  with their processes; a threaded program ends with status 126 when
  `threads@0` is disabled under it.
- Not switched: `runtime@0`, `build@0`, `display@0`, `input@0` and
  `snapshot@0`; `nena` says why for each. Nor is a module disabled that an
  enabled one needs (`http@0` under `build@0`). `http@0` switched on takes the
  page's HTTP policy as it was at load; switched off, each transfer in flight
  ends with `ECANCELED` (`amy install curl` enables it in `default`).
- `nena disable nena` gives the privilege up until the page is reloaded: the
  session then is as an image without `nena@0`, and its refusals read so.
- The modules a session enabled are listed in `/etc/dolly/enabled`, one
  `name@version` a line, written by the page's provider. A saved session
  holds the file, and loading it enables them again: ENTRY waits three
  seconds for them and starts without one the browser has not given by then.
  The page says in one line which were enabled; one that cannot be is said
  there too, with the command. A module the
  image declares and the session disabled is back when the page loads.

## Unsupported

`fork`, job control, joining another process group or session, network
sockets, and changing user or group identity fail explicitly.
