summaryrefslogtreecommitdiff
path: root/docs/next-daemon.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-10-29 10:48:56 -0300
committerGabriel Schneider <[email protected]>2026-10-29 12:13:25 -0300
commit9be47b76e4edf4ddb56e4d572c14b54bf45fdd39 (patch)
tree602d0943dc1c48bb4e90a7f9d9de16e541cdb981 /docs/next-daemon.md
parent5c23bd8b1bbdbbacd99b11e75d38f7ce1801cd8a (diff)
downloadpardes-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.md98
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.