diff options
Diffstat (limited to 'docs/typ')
| -rw-r--r-- | docs/typ/building.typ | 51 | ||||
| -rw-r--r-- | docs/typ/reference.typ | 22 |
2 files changed, 42 insertions, 31 deletions
diff --git a/docs/typ/building.typ b/docs/typ/building.typ index d551c251..152be838 100644 --- a/docs/typ/building.typ +++ b/docs/typ/building.typ @@ -1,6 +1,6 @@ // Building pardes, for contributors: platforms, options, tests, the // release gates and sending patches, then how the pieces fit: the core -// and its shells, the threads, detached sessions, the 9P engine, the +// and its shells, the threads, the daemon and its sessions, the 9P engine, the // listeners and mounts. #import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs @@ -177,8 +177,9 @@ Code map: `src/panes.zig` and the pane kinds it names (`src/File.zig`, `src/Terminal.zig`, ...), `src/layout.zig`, `src/fs.zig` (host access, mounts and resolution) and `src/pardes.zig` (input), with one file per thing beside them (`edit.zig`, `normal.zig`, `look.zig`, `exec.zig`, -`mouse.zig`, ...). `src/ninep/` is the control tree, `src/detached/` the -wire, the detached core and the frontend client, `src/lsp/` the +`mouse.zig`, ...). `src/ninep/` is the control tree, `src/daemon.zig` the +per-user daemon and a terminal's stub, `src/detached/wire.zig` the input +wire a remote client will speak, `src/lsp/` the language-server client; `test/` holds harnesses, goldens and helix cases, `build/` the snapshot suite's build step. @@ -197,26 +198,34 @@ reading the live core, and a request id, the pane's serial and (for an edit) the file's revision reject a stale reply. A process that never calls `turn.start` (the tests, the ESP32-P4, the browser) has no second thread. -== Detached sessions +== The daemon and detached sessions -One poll loop in `src/detached/server.zig` owns core mutation, frontend -connections, pty I/O and file watches. The frontend socket is -`pardes-detached-<name>.sock` beside the session's 9P socket; a second -session cannot take a live name. Up to 32 frontends attach; frames go to -every one, while clipboard reads, browser opens and #word("Detach") go to -the frontend that asked (else the first attached). Frames are full grids -or changes against what each frontend last received, never queued: a -frontend with unsent bytes skips that frame, and one that stops draining -past 1 MiB of control backlog is closed, its peers untouched. Frontends -never spawn shells, write session files or watch files. #word("Attach") -connects first and swaps second: only after the handshake does a shell -give up its own core. #word("Restore") builds the replacement core before touching -the current one. +One `pardes --daemon` per user (`src/daemon.zig`) listens on +`pardes-daemon.sock` in the runtime directory, its `.lock` flocked for its +life; the first session that finds none starts it (a double fork and an +exec) and it exits a second after it holds nothing. It is nobody's parent: +a session registers on one connection, sends it a dup of every pty master +it forks (so a session killed outright never hangs its shells up, and +#word("Adopt") takes them into another), says whether a terminal or a +window shows it, and is handed a terminal (`pardes --attach`) or a window +request (`pardes-gui --attach`) through it. Messages are `SOCK_SEQPACKET` +datagrams: a line of words and the fds it carries. -`src/detached/wire.zig` is the versioned protocol (version 10): fixed-width -little-endian fields, a 5-byte header (tag, then a u32 length), payloads up -to 16 MiB and grids up to 512 by 128. A comptime hash of `pardes.Chrome` -forces a version bump when that struct changes. +`pardes` in a terminal forks its session off before anything starts: the +session, in a session of its own (`setsid`), draws on the terminal it +opened, and the process the shell waits on stays as its stub, passing it +`SIGWINCH`, `SIGTERM`, `SIGINT` and `SIGQUIT` and ending with its status. +#word("Detach"), or the terminal's end (EIO, a hangup), puts +the terminal back and lets it go; the stub ends (exit 0) and the session +runs on with nothing drawn, until `pardes --attach` hands it another +terminal. A window's #word("Detach") closes the window and keeps the +process; `pardes-gui --attach` opens one again. `PARDES_DAEMON=off` (the +snapshot harness) runs a session as before the daemon: in the terminal's +own process, ended by its hangup. + +`src/detached/wire.zig` is the input half of the protocol a remote client +will speak (version 13): fixed-width little-endian fields, a 5-byte header +(tag, then a u32 length), the hello and its version, the input events. = 9P diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ index b83b4a83..c95a574a 100644 --- a/docs/typ/reference.typ +++ b/docs/typ/reference.typ @@ -386,9 +386,9 @@ Writes take settings and session builtins (`scope = .session` in record for why. A #word("ThemeFile") the dump names that fails to load changes nothing. - #word("Kill") `[word...]` (above), #word("Mount") `name dial`, #word("Unmount") `name`, #word("Theme") `x`. -- `size C R` sizes a `--detach` session no frontend is attached to (160x50 - until then): from 20x6 to 4096x4096, else `invalid size`; refused while a - frontend owns the size, and when a column would lose its panes' minimum +- `size C R` sizes a session no terminal or window is attached to (160x50 + for a `--detach` one until then): from 20x6 to 4096x4096, else `invalid + size`; refused while a terminal or window owns the size, and when a column would lose its panes' minimum rows (`size: too small for the panes, each its tag and 2 rows`). A bad `size` is refused quoting the value it got (`"5 2"`). @@ -454,8 +454,7 @@ turning it off: #word("PanelSlide"), #word("PanelZoom"), #word("PanelDissolve"), #word("PanelAscii"), #word("PanelVertical"), #word("PanelEdges"), #word("PanelFall"), #word("PanelWave"), #word("PanelCurtain"), #word("PanelScramble"), #word("PanelType"); all -start off, and the web shell has none. Scene passes (the SDL window, and -one attached to a detached session), each at a level 0-3 (`on` is 2), all +start off, and the web shell has none. Scene passes (the SDL window), each at a level 0-3 (`on` is 2), all off: #word("Crt"), #word("Bloom"), #word("Vignette"), #word("Grain"). #word("Shader") `<file.glsl>` adds a Shadertoy file written for ghostty to the chain (#word("Shader") `off` removes it; it recompiles when saved); @@ -1011,11 +1010,14 @@ to its end before the write is answered, and one that finds nothing fails, git's `a/` `b/` (and `c/ i/ w/ o/`) prefixes are dropped; a `--no-prefix` diff's paths are kept. - *Sessions.* Bare `--detach` names the session after its pid; bare - `--attach` needs exactly one session; a second `--detach=NAME` while NAME - runs (a plain session is named by its pid) says so in words and exits 1. Frontends share the smallest common size. With - none attached, `size C R` sets the screen, messages clear by the clock, - and a pty reports its size in pixels at the last frontend's cell size - (8×16 before any), as CSI 14, 16 and 18 t do. + `--attach` needs exactly one detached session of its kind (a terminal's + for `pardes`, a window's for `pardes-gui`); a second `--detach=NAME` + while NAME runs (a plain session is named by its pid) says so in words + and exits 1. One terminal or window shows a session at a time. With none + attached, `size C R` sets the screen, messages clear by the clock, and a + pty reports its size in pixels at the last cell size (8×16 before any), + as CSI 14, 16 and 18 t do. Attaching from another machine is gone until + the replicated clients (docs/next-daemon.md, phase 5). - *Config.* The startup file is `$XDG_CONFIG_HOME/pardes/init` when that is absolute, else `~/.config/pardes/init` (macOS: `~/Library/Application Support/pardes/init`). A line that fails is a |
