summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-17 02:40:21 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commit757cdaa826131dc5ff2d3ff0b270b8abe041c81a (patch)
tree96de2e4537bc009d502bdf74b453e6964a12dff0 /docs
parent83b9d45b8665a80bdb70934aa23bbde5cc03d202 (diff)
downloadpardes-757cdaa826131dc5ff2d3ff0b270b8abe041c81a.tar.gz
pardes-757cdaa826131dc5ff2d3ff0b270b8abe041c81a.zip
plumber: external ports (docs/next-plumber.md, phase 3): every port a rule names has a file, plumb/<port> (0444), listed after rules and send in the order rules named them and never dropped (Plumb.ports, dumped: seeded at boot from the rules in force, grown by each apply, refused past 32), its node a third family in the tree beside panes and columns (Node.ofPort, Target.port; port_bit is 1 << 40, clear of the host tree's and the archive's high bits, which 1 << 57 hit); an open reads (Open.what.port, an events.Queue of its own, 64 KiB): the messages sent from then on, packed, one a read, a short read the front and the next the rest, a read with none held until one comes (p.fs.news, answered by the listener as event reads are); every open gets its copy (fanOut, plumber(4)'s queuesend), one over the queue is not sent to it and the log says so; a port pardes reads itself (edit, web, a loaded kind) hands its readers copies without asking anyone, so a look stays speculated whole; another port's readers are the authority's to know, asked through tape.authority (a replica's own look waits for the first answer and guesses the last), with none its rule set's start runs, or its client, the message held in p.fs.plumb_held for the port's first opener (Plumb.opened, plumber(4)'s queueheld); test: plumber.zig, two opens of plumb/edit each read a look's message while the file opens, an open made after reads nothing, a client's message reaches the first opener and the next goes to the reader with nothing started, a port is not written; monkey9p.zig gains the plumb/ files, rules and messages that start no program, the ports' reads as held reads, and plumb/rules' rest read at the close (whose refusal is the log's alone, as a line file's: restAtClose); replicas.zig: a look to a port a program reads, the second of a replica's own speculated whole and confirmed, digests equal; tree.zig's readdir test lists web and edit; the reference's tree and plumber section, fs-help and the changelog say so
Diffstat (limited to 'docs')
-rw-r--r--docs/typ/reference.typ27
1 files changed, 20 insertions, 7 deletions
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index f1b4df76..4d077f71 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -41,6 +41,7 @@ tagexec a word clicked in the workspace tag @co
plumb/ the plumber's: plumb(6) rules, and messages sent by them @plumber
rules the rules in force; a write adds rule sets, > replaces them @plumber
send write a message: six header lines, then its data @plumber
+ <port> a port the rules name: read, the messages sent to it @plumber
col/ the columns @columns-and-tags
<n>/ column <n>; rmdir closes it when empty @columns-and-tags
tag its tag
@@ -1038,7 +1039,8 @@ own: a file or directory opened, else the word searched for.
(`plumbing` in the configuration directory, beside `init`; saved, its
rules are in force), or without one `include basic`, pardes's own
(`src/plumbing`, below). A write adds rule sets, each
- read as its blank line comes, the rest at the close; `>` replaces them
+ read as its blank line comes, the rest at the close (refused there, it
+ is an `err` in the log alone; Plan 9's loses it); `>` replaces them
all. One open writes at a time (`file in use`). Kept in a dump.
- A rule set that does not read is refused at the write it is whole in,
`plumb/rules:<line>: <why>` in rules.c's words (`unknown verb isnt`,
@@ -1062,11 +1064,22 @@ own: a file or directory opened, else the word searched for.
`$file` and `$dir` are where), `set`, `add` and `delete` (`delete` of
an attribute not there fails, as plumber's code does), and the actions
`plumb to <port>`, `plumb start <words>` and `plumb client <words>`.
-- The ports pardes reads itself: `edit` (the data opened as a
- #word("Look") opens it, at `addr=` when given), `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 runs its rule set's
- `start` or `client`; to a port no rule names it goes nowhere.
+- Each port a rule has named this session has a file,
+ #file("/plumb/<port>") (0444), listed after `rules` and `send` in the
+ order the rules named them, never dropped. An open of it reads the
+ messages sent to that port from then on, one a read in the six lines'
+ form, a read that finds none held until one comes; every open gets its
+ own copy (`cat /plumb/edit` beside the editor sees every look it opens),
+ 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`
+ (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),
+ or its `client`, the message held for the port's first reader (the
+ program it started, as a rule's `plumb client` means). To a port no
+ rule ever named it goes nowhere.
- `plumb start` of a builtin or a kind's word runs it in place, at the
looking pane (the pane with the keyboard for a #file("/plumb/send")
message); one that cannot do what it is asked declines, saying
@@ -1424,7 +1437,7 @@ with Client(sys.argv[1]) as c: # a socket path, or (ip, port)
[Edit], [every acme command but `B <cmd`, `D <cmd` and the `'` address; no `\1`-`\9`, and an alternation takes the first branch that matches, not the longest; a failing `< | >` command changes nothing, where acme puts in what it wrote (#doc("fs", section: "edit"))],
[`win`], [#word("Term") is a VT terminal pane; #file("pty/run") runs a line at its prompt and answers `exit N` and the output; with #word("Repl") bound, #word("Exec") on a source pane types the text into it],
[a directory window], [as acme's: a text pane named `dir/` (#file("index") kind `text`, #file("ctl") isdir 1), its entries in columns sorted bytewise, dotfiles shown, a directory's marked `/`; blanks pad the columns where acme's tabs do; a #word("Look") at an entry is from that directory, `Get` or a look at it again reads it again, and an edit is kept until then rather than lost to a resize; never dirty, #word("Save") refuses it],
- [the plumber], [no process: the plumber is the editor's own (#doc("reference", section: "plumber")): plumb(6)'s rules in #file("/plumb/rules") and the plumbing file #word("Plumb") opens, messages to #file("/plumb/send"); no submatches (`$1`-`$9`), no `click` from a #word("Look") (its own expansion stands), and no external port files yet],
+ [the plumber], [no process: the plumber is the editor's own (#doc("reference", section: "plumber")): plumb(6)'s rules in #file("/plumb/rules") and the plumbing file #word("Plumb") opens, messages to #file("/plumb/send"); no submatches (`$1`-`$9`), no `click` from a #word("Look") (its own expansion stands)],
[#key("Esc") selects what was typed], [#key("Esc") leaves insert mode, or goes back a pane (#doc("tags", section: "modes"))],
)