summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-17 02:44:25 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commit0a75f3f333e795e741c83c1193e3b833d40caf46 (patch)
treece627350732398e3dc071495742693c271855f86 /docs
parent757cdaa826131dc5ff2d3ff0b270b8abe041c81a (diff)
downloadpardes-0a75f3f333e795e741c83c1193e3b833d40caf46.tar.gz
pardes-0a75f3f333e795e741c83c1193e3b833d40caf46.zip
plumber: the pager sends (docs/next-plumber.md, phase 4): a +Pager filled with a diff (File.looksLikeDiff, pager_diff) is a plumbing message, as acme's `plumb -i` sends what it shows: fillPager's last call is Plumb.paged, which sends src pager, dst edit, wdir the +Pager's directory, type text/x-diff, `action=showdata filename=<the +Pager's name>` (quoted as mesg.c quotes), the text as data; the default rules' last set makes it showdiff (attr delete action, attr add action=showdiff, plumb to edit), and the edit port's showdata and showdiff (Plumb.show, acme's plumbshow) show the data in the pane filename names, the sender's own first, else a new clean pane of that name, showdiff then restacking it in a +Diff in its place (hunks.paged, the code the pager's hook called, unchanged); text paged that is no diff is not sent, where the record had every page sent: the look rules would read it whole, `type is text` holding (a `matches` over a MiB of output, up to the regular expressions' 300 ms budget, at each page), and a page of one line naming a file would ask the disk; the rules in force are read once and kept until their text changes (Plumb.parsed, by its hash, derived state: each process's own), measured in a fast build per send: 29k instructions to read the default rules, a URL's send 37k before, 8.3k after, a word's look 69k before, 40k after, a look that opens a file 262k before (its send 63k), 233k after (34k); test: a diff paged is stacked by the default rule, text that is no diff stays a +Pager, without the rule the +Pager stays as text, and another sender's showdata and showdiff; the design record gains what phases 2-4 did otherwise (detached starts with no output kept, only diffs paged sent, own ports asking nobody, the rules read once); plumber.zig's defaults end with the paged rule; the reference, the default rules' file and the changelog say so
Diffstat (limited to 'docs')
-rw-r--r--docs/next-plumber.md29
-rw-r--r--docs/typ/reference.typ10
2 files changed, 37 insertions, 2 deletions
diff --git a/docs/next-plumber.md b/docs/next-plumber.md
index 76a86bea..178814b3 100644
--- a/docs/next-plumber.md
+++ b/docs/next-plumber.md
@@ -867,6 +867,35 @@ The options as round 1 put them:
$0`, `9 page $file`), at the cost of a host effect generalising
`open_link`.
+## What phases 2-4 did otherwise (2026-11-17)
+
+- **Q4 is (b) now**, the coordinator's lean while the user was away: a
+ program a rule starts runs detached, as Plan 9's plumber starts one
+ (Effect.start, every host's host_io.startDetached: setsid, stdin, stdout
+ and stderr `/dev/null`, every other fd closed, argv exec'd in wdir with no
+ shell). Its output is not the session's log, as the lean said: that needs
+ an inbox message and an Event through the tui, window, macOS and daemon
+ hosts, which other agents are changing. A failure to start (the program
+ not found, its directory gone) is said and logged, the child's errno
+ carried back by a close-on-exec pipe. Its directory and words fit 256
+ bytes, an effect's inline payload.
+- **Only a diff paged is sent** (§5.4 had every page sent). Text paged is
+ `type text`, which the look rules do see, contrary to §5.4: their
+ `matches` would run over the whole output (up to a MiB, and the regular
+ expressions' 300 ms budget) at each page. A diff is `text/x-diff`, which
+ every look rule refuses at its first pattern.
+- **A port pardes reads itself (edit, web, a kind) asks nobody** whether a
+ program reads it: its readers' copies are the authority's own to hand
+ out, and pardes reads it anyway, so a URL's look still speculates whole.
+ Only another port's dispose asks `tape.authority`.
+- **The rules in force are read once** and kept until their text changes
+ (by its hash, derived state): per send the parse was 29k instructions
+ in a fast build, about half of a URL's send and 40% of a word's look.
+- **`showdata` from another sender** makes a clean pane of its `filename`
+ (acme's plumbshow); the pager's own message is shown already.
+- **plumb/rules' rest read at the close**, refused there, is an `err` in
+ the log (Plan 9 loses it); the T1 monkey models it as a line file's.
+
## Not verified
- **Nothing was built or run.** All sizes are estimates, and the test counts are
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index 4d077f71..987f9f9b 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -1073,7 +1073,10 @@ own: a file or directory opened, else the word searched for.
a message over its 64 KiB queue is not sent to it (an `err` in the log
says so). Messages sent before the open are not its.
- The ports pardes reads itself, whatever else reads them: `edit` (the
- data opened as a #word("Look") opens it, at `addr=` when given), `web`
+ data opened as a #word("Look") opens it, at `addr=` when given; with
+ `action=showdata` the data itself shown, as acme's `plumb -i`, in the
+ pane `filename=` names, else a new clean one of that name, and with
+ `action=showdiff` then stacked in a +Diff in its place), `web`
(the host's browser, a URL of at most 256 bytes) and each loaded kind by
its name (`image`, `pdf`). A message to another port goes to its
readers; with none, its rule set's `start` runs (the message dropped),
@@ -1096,7 +1099,10 @@ with the file, which declines one with no hunk, opened as text then); an
existing directory or file to `edit`, Look's own open (a kind's file in
its kind); a commit hash looked at in the editor, in a git work tree, to
#word("Diff") with it, `git show` paged (outside one, Diff declines and
-the word is searched for):
+the word is searched for); a diff paged into a +Pager, which the pager
+sends to `edit` (`src` `pager`, `type` `text/x-diff`, `action=showdata`
+and the +Pager's `filename`), made `showdiff`: stacked in a +Diff in the
++Pager's place. Text paged that is no diff is not sent:
#raw(read("../../src/plumbing"), block: true)