diff options
| author | Gabriel Schneider <[email protected]> | 2026-10-29 10:48:56 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-10-29 12:13:25 -0300 |
| commit | 9be47b76e4edf4ddb56e4d572c14b54bf45fdd39 (patch) | |
| tree | 602d0943dc1c48bb4e90a7f9d9de16e541cdb981 /docs/next-daemon.md | |
| parent | 5c23bd8b1bbdbbacd99b11e75d38f7ce1801cd8a (diff) | |
| download | pardes-9be47b76e4edf4ddb56e4d572c14b54bf45fdd39.tar.gz pardes-9be47b76e4edf4ddb56e4d572c14b54bf45fdd39.zip | |
docs: the daemon, Detach, --attach and Adopt; phase 3 notes in docs/next-daemon.md
building.typ's detached sessions are the daemon and its sessions; the guide, cheatsheet and reference say what Detach, a closing terminal, --attach of each kind and Adopt do, and that attaching from another machine waits for phase 5. docs/next-daemon.md records the forks taken (sessions register and are not the daemon's children, and why; how it starts; masters; Adopt as a word; the stub's signals and job control; --detach; the Attach word; the harness switch), the known gaps, and the termios trap.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Diffstat (limited to 'docs/next-daemon.md')
| -rw-r--r-- | docs/next-daemon.md | 98 |
1 files changed, 98 insertions, 0 deletions
diff --git a/docs/next-daemon.md b/docs/next-daemon.md index 8bc9b38c..d164eced 100644 --- a/docs/next-daemon.md +++ b/docs/next-daemon.md @@ -169,3 +169,101 @@ open. terminal's scope ever kills it] 5. The join writer: a fork child, or a metadata copy serialised on a worker. [fork first, measure the page-table copy] + +## Phase 3 notes + +Built 2026-10-29 (`src/daemon.zig`, the tty and GUI hosts, `main.zig`). +Decisions taken at the forks, with the ponytail lens: + +- **Sessions are not the daemon's children; every one registers.** The + design had the daemon spawn a terminal's session from the fd, cwd, env + and argv the stub passes. That proved wrong here: + - the user's terminals each run in a `9ns --mntgen` user and mount + namespace (`unshare(CLONE_NEWUSER|CLONE_NEWNS)`); a session the daemon + spawned would run in whichever namespace the daemon was started from, + its `/mnt/9p` served by a 9ns that may be gone. Its cgroup, rlimits, + umask and stdin (`pardes -`) would be the daemon's too, or have to be + carried and re-execed; + - startup would pay an IPC round trip and an exec of a 100+ MB binary; + - the snapshot harness's idleness probe walks the launched process's + tree, and a daemon-spawned session is outside it. + + So `pardes` in a terminal forks its session off itself before anything + starts (`daemon.forkSession`): the child calls `setsid` and draws on the + `/dev/tty` the parent opened; the parent stays as its stub. GUI windows + and `--detach` sessions just register. The daemon spawns nothing, so it + is no subreaper: a detached session is reparented to the system's reaper + (systemd --user or init), which reaps it, as it reaps a crashed + session's shells. Nothing dangles: the daemon lists every session (its + connection) and holds every master, and exits a second after it holds + neither. +- **Starting the daemon.** The first session takes the flock, binds and + listens itself and queues its own connection; `pardes --daemon` is then + double-forked and exec'd onto that listener and lock (fds 3 and 4), by + a terminal's stub after the session's fork, so no session waits for it: + its hello sits queued until the daemon runs, and is not waited on (the + daemon's `ok` is the reader thread's; Detach waits for it, up to 2 s). + With the spawn before the fork, a cold start measured +0.38 ms (+7.6%). + The daemon's reader thread likewise starts after the first frame. + Another starter waits on the lock; a stale socket is the lock holder's + to replace. Messages are `SOCK_SEQPACKET` datagrams, a line of words and + the fds it carries. +- **pty masters.** `forkShell` sends a dup; a host's close sends `close`; + a session's end sends `quit` (its shells hang up); a master whose shell + is gone (`POLLHUP`, polled with no events) is dropped. TERM, HUP and INT + handlers send `quit` too (one `send`, async-signal-safe), so only a + session killed outright or crashed leaves shells behind. +- **Adoption is a word, `Adopt`,** calling the host through a vtable entry + (no Effect): the daemon hands over every orphaned master, and each + becomes a pane through the `Tty` word, its spawn taking the pty instead + of forking; a 1x1 size then the pane's makes it redraw. Adopting at + startup was rejected: an `EDITOR='pardes --wait'` session would take the + shells and hang them up when the editor exits. +- **The stub.** It forwards WINCH, TERM, INT, QUIT and HUP by `kill`, and + ends with the session's status (a forked stub `waitpid`s; an attaching + one reads `x<code>`). A HUP is the terminal's end: kept by a daemon, a + session takes HUP on its signal thread (sigwait, beside WINCH) and + detaches, as on EIO; HUP never ends a kept session, since the terminal's + own EIO and HUP arrive in either order. Ctrl-Z stays a key for the pane + (the terminal is raw, as before); a TSTP sent to the stub is ignored, + since a stopped stub hands the terminal back under a session still + drawing; a background start stops at a `tcsetattr` before the fork, as + the old raw mode did. `--wait`, nested forwarding and `--tty` run before + any of this and are unchanged. +- **`--detach` is a session started detached:** the tty host with no + terminal, the GUI with a hidden window closed at once. With the frames + gone, `detached/server.zig` was a third host with nothing left to do + that the other two could not. +- **`Attach` (the word) is deleted:** it switched a session's own terminal + to another session through the frames. +- **Harnesses.** `PARDES_DAEMON=off` (the e2e harness sets it) runs a + session as before: in the terminal's own process, ended by its hangup, + for a harness that kills by pid and closes the terminal. A GUI test + window (`PARDES_TEST`) has none unless `PARDES_DAEMON=on`. +- **Known gaps.** A stub killed with SIGKILL while its terminal stays open + leaves the session drawing there until the terminal closes or Detach. A + reattached terminal keeps the first one's environment (TERM, COLORTERM); + vaxis queries its capabilities again. A daemon killed outright leaves + its sessions unregistered, and Detach then refuses. A daemon of an older + protocol answers `version`, and a session then runs without one. A + GUI started in a terminal's foreground stays that terminal's job. + +Measured (ReleaseFast, base main a7369739 against these changes, both +live at once and their samples alternating A, B, A, B; A/A the base +against itself; p50 ratio new/base): + +| | tty | A/A | GUI (test mode) | A/A | +|---|---|---|---|---| +| startup, no daemon running | 1.017 (4.73 to 4.81 ms) | 0.998 | 0.982 (295 to 290 ms) | 0.999 | +| startup, daemon running | 1.014 (4.66 to 4.72 ms) | | 1.014 (noisy) | | +| key in a file, to its frame | 0.992 | 1.009 | 1.003 | 0.986 | +| key echoed by bash, to its frame | 1.016 | 1.005 | | | + +What is left of the tty's startup is the stub's fork (about 70 us), which +the design cannot do without: the job the shell waits on must be able to +end while the session runs on. + +Trap found on the way: glibc's `tcgetattr` writes its 60-byte `struct +termios` into Zig's `std.c.termios`, which is 44 (the kernel's layout), +and overran the stack, clobbering a neighbouring local in the forked +child; `std.posix.tcgetattr` (an ioctl on that layout) is the right one. |
