summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/next-store.md122
-rw-r--r--docs/typ/building.typ3
-rw-r--r--docs/typ/reference.typ43
-rw-r--r--docs/typ/setup.typ19
4 files changed, 141 insertions, 46 deletions
diff --git a/docs/next-store.md b/docs/next-store.md
index 89997ee2..3c8a2f7d 100644
--- a/docs/next-store.md
+++ b/docs/next-store.md
@@ -1,4 +1,4 @@
-# The store: Recent's file, and this session's closed panes
+# The store: the state file, the blob cache, and this session's closed panes
> We should have some persistent state that is bounded (a houndred or so
> MiB at most) stored on the fs and shared among all pardes windows. It will
@@ -6,22 +6,66 @@
> picker and this should include panes from the current session that were
> deleted/closed.
-## The decision (2026-11-05)
+## The decision (2026-11-05, the persistence step): everything on disk through xitdb
-**Recent is a file of at most 200 lines**, `$XDG_STATE_HOME/pardes/recent`
-(else `~/.local/state/pardes/recent`), a line a file, the newest first:
-`<line> <col> <aline> <acol> <path>`. Every session reads it at start, and
-again on use (Recent, `/recent`) when a stat of it says another session
-wrote it since. A step that changed the list writes it at its end: `flock`
-on the file (held by another session: the next step tries again, so a
-frame never waits for one; at exit the lock is waited for), the file read
-again with this session's changes put over it (`recent.List.merge`) when
-another session wrote it since, and the whole list written over it in
-place. A line that is no entry is passed over: a missing, unreadable or
-foreign file is an empty list, a reader meeting a write half done reads it
-again once its stat moves on, a line a crash tore is one entry fewer, and
-pardes always starts. A rename of a new file over it (atomic) cost twice
-the write in Debug for nothing the lenient read does not already give.
+What pardes keeps on disk goes through xitdb (`src/Db.zig`; architecture
+§14): two files, both BLAKE3-keyed, both with xitdb's header-last commit,
+so a kill or a full disk leaves the last commit whole.
+
+**The state file**, `pardes.xitdb` in the DumpDir (`$XDG_DATA_HOME/pardes`,
+else `~/.local/share/pardes`), one a user: Recent is documented as shared
+by every window, a Restore is any session's. Its root is a map:
+
+- `recent`: Recent's 200 lines as one value, the format the `recent` file
+ had. A session reads it at start (after the startup config, whose DumpDir
+ says where the file is) and on use when the file's committed size has
+ moved; a step that changed it reads, merges (`recent.List.merge`) and
+ writes it in one transaction under the file's lock, taken without
+ waiting: busy, the next step tries again. Not fsynced, as the file never
+ was: a commit is 20 us without fsync and 5.2 ms with xitdb's two on this
+ machine's btrfs, against 124-148 us for the whole flush after an open.
+ Measured: 133-135 us for that flush (Debug, 200 files), and 12,325 bytes
+ of file a Recent change (its 12,089 bytes of lines and 236 of xitdb's).
+- `dumps/<label>`: a dump each, `pardes-<date>-<time>` (UTC, `-2` and on in
+ one second), `upgrade-<pid>`: its number, date, pane count and size, the
+ session as a database of its own (walk.Put's maps, by field name: another
+ build reads it by name), and the hashes of the texts it keeps beside it.
+ One Dump is one fsynced transaction; the newest 32 are kept, the texts no
+ kept one names dropped in the same transaction.
+- `blobs/<hash>`: each such text (a `.blob` field of 4 KiB and up) once:
+ an unchanged text is written once across dumps.
+- `last`, `seq`: the newest dump's label, the next number.
+
+At a session's end the file is compacted into `pardes.xitdb.new` and
+renamed over it once it is past twice what it holds plus 64 MiB, under the
+lock; another session notices the new file by its inode and opens it. A
+file there that is no database is kept aside as `pardes.xitdb.broken`.
+
+**A dump travels as an image**: a database in memory holding one dump in
+the same shape (deterministic: no random ids, so one session is one
+image). The core makes one at a Dump (the host puts it in the state file
+under its label, or writes it whole for `Dump export <path>` and
+`$PARDES_DUMP`), a Restore of a label is read into one, a handover's
+carried panes are one (`handover-<seq>`), and `-l <file>` and
+`Restore <path>` read one, an old byte dump (`.dump`) too for one release.
+
+**The far client's blob cache** is `cache.xitdb` in `$XDG_CACHE_HOME/pardes`:
+expendable and up to a gigabyte, so never the state file. `blobs/<hash>`,
+`seen` (a sorted map of numbers to hashes, the least recently used first),
+`size`; past the cap (`PARDES_BLOB_CACHE_MB`, 1 GiB) the oldest go and the
+file is compacted, at a client's end.
+
+**Not in a database**: the closed panes (this session's, in memory, as
+below), the crash record (one `write(2)` from the panic handler, which may
+not lock or allocate), the startup file and themes (edited by hand), and
+the kernel's and the shells' files (sockets, locks, the registry, rc
+snippets).
+
+**Migration**: Recent is read once from the `recent` file this decision
+replaces, else the `store` before it, when the state file holds none yet;
+both are left where they are.
+
+## Closed panes
**Closed panes are this session's, in memory**: the newest 64, within
64 MiB together, each a one-pane dump (`dump.savePane`, at most 8 MiB; a
@@ -30,6 +74,12 @@ and where it was. Panes lists them after the open panes, `(closed)`;
Enter, or a Look at `@pN`, brings one back beside the pane that took its
rows. Restore keeps them; the session's end drops them.
+## Before it, the same day
+
+**Recent was a file of at most 200 lines**, `$XDG_STATE_HOME/pardes/recent`,
+under `flock`, written whole in place; the state file keeps those lines as
+one value and reads the file once.
+
## What went, and why
The store this replaced (2026-10-24, Store.zig 1,135 lines) was one
@@ -46,21 +96,31 @@ or closes a file.
What a user loses: the closed panes of other sessions, which the log kept
on disk until a compaction and nothing ever listed.
-The first session of a build with this reads the old `store` once more,
-when it is newer than `recent`: its `@r` records' bodies are this file's
-lines. The old file is left in place for an older pardes still running.
+W4's `recent` file read the old `store` once more while it was the newer
+of the two; the state file reads `recent`, else `store`, once (the
+migration above), and leaves both for an older pardes still running.
## Tests
-Store.zig: two windows share Recent (each reads the other's writes on use;
-a lock held by a third party delays a write, never loses it); the file
-holds the newest 200, newest first; a foreign file's Recent lines are read
-and the next write mends it; the old store read once, its newest records
-first; a session keeps its newest 64 closed panes; a closed pane comes back
-where it was, its rows from the pane that took them, listed `(closed)` in
-Panes and unlisted once back, and another session lists none.
-recent.zig: a merge puts this session's changes over the file's list.
-test/process/other_files.zig: a file opened and closed is in `/recent`
-closed and still is in the next session; two sessions share Recent, and a
-Del'd pane comes back from `@p` only where it was. test/behaviour/
-other_files.zig: `/recent` and Recent's rows.
+Db.zig: two windows share Recent (each reads the other's commits on use; a
+lock held by a third party delays a write, never loses it); the file holds
+the newest 200, newest first; a file that is no database is kept aside and
+a new one started; Recent is read once from the `recent` file, else the
+`store`, both left in place; two dumps of one label get labels of their own;
+a Dump makes the directories of its DumpDir. Store.zig: a session keeps its
+newest 64 closed panes; a closed pane comes back where it was, its rows from
+the pane that took them, listed `(closed)` in Panes and unlisted once back,
+and another session lists none. recent.zig: a merge puts this session's
+changes over the list read. dump.zig: an image read by name is the session,
+and dumps to the same bytes again; an old `.dump` is read by `-l` and
+Restore. upgrade.zig: an older build's record loads its `.dump` file.
+replica.zig: the blob cache rehashes what it reads, keeps its cap by least
+recent use and compaction, and starts afresh over a file that is no
+database. test/behaviour/root_ctl.zig: a Dump and Restore round trip through
+9P, a missing label refused in words, the 33rd dump dropping the first, an
+unchanged text written once across two dumps, a killed Dump leaving the one
+before it whole. test/behaviour/other_files.zig: two sessions on one state
+file share Recent. test/process/other_files.zig: a file opened and closed is
+in `/recent` closed and still is in the next session; two sessions share
+Recent. test/daemon.py: an Upgrade keeps its dump in `/dumps`, and far
+clients' cache.
diff --git a/docs/typ/building.typ b/docs/typ/building.typ
index 456cbb3e..4b736251 100644
--- a/docs/typ/building.typ
+++ b/docs/typ/building.typ
@@ -224,7 +224,8 @@ pings and nothing more.
#word("Upgrade") (`src/upgrade.zig`) execs the path the session was started
from, at a step boundary, after asking it `--version`: the session's dump
-goes to the DumpDir (`pardes-upgrade-<pid>.dump`), and its pty masters,
+is committed to the state file as `upgrade-<pid>` (the build before wrote
+`pardes-upgrade-<pid>.dump`, which this one still reads, for one release), and its pty masters,
terminals, stubs and daemon link stay open across the exec, named in a
record on the new command line (`--upgraded=`) ahead of the arguments it
was started with. The pid stays, so the shells stay its children; the new
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index d0f492cf..cb2df2a8 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -160,7 +160,7 @@ the next read on that fid is EOF until the next write (or seek to 0). With
other clients about, write and read on one open:
#cmd("exec 3<>$m/pane/$n/look; echo x >&3; cat <&3; exec 3<&-")
-*Snapshots.* #file("/index"), #file("/layout"), #file("/recent"),
+*Snapshots.* #file("/index"), #file("/layout"), #file("/recent"), #file("/dumps"),
#file("/commands"), #file("/status"), #file("/listeners"), #file("/sessions"), a read-only
#file("ctl"), #file("/log"), #file("/screen") and a terminal's
#file("body") freeze at the open, so one read in several chunks never
@@ -192,7 +192,7 @@ the range and flag files, the workspace's #file("tag"), the root
#file("look")/#file("exec") answers, #file("focus"); #file("event") and
#file("pty/data") the next record's, zero when none waits. A stream and a
view generated by each read stat 0, as acme's do: #file("log"), #file("screen"), #file("data"), #file("xdata"), #file("index"),
-#file("layout"), #file("recent"), #file("listeners"), #file("sessions"), #file("pane/new").
+#file("layout"), #file("recent"), #file("dumps"), #file("listeners"), #file("sessions"), #file("pane/new").
Read those to the end rather than trust a length (`cat` does). The qid
version of #file("body"), #file("data") and #file("xdata") is the pane's
revision, so a stat sees an edit land. Modes are 0644/0666, 0444
@@ -389,20 +389,30 @@ Writes take settings and session builtins (`scope = .session` in
#word("Delcol") and a pane's `get` refuse the same way with their own
word, except that #word("Delcol") opens no `+Unsaved` pane: it names the
panes only in its `unsaved` records and its notice.
-- #word("Dump") writes `pardes-<date>-<time>.dump` (UTC) in #word("DumpDir"),
- logs `dump <path>`, and adds a #word("Restore") `<path>` word naming it to the
- workspace tag (the last dump's, replacing an earlier one's).
- #word("Restore") `[path]` replaces every pane (bare: the last dump this session
- wrote). The #word("Restore") write is answered, then *every connection is hung
+- #word("Dump") puts the session in the state file (`pardes.xitdb` in
+ #word("DumpDir"), below) under a label, `pardes-<date>-<time>` (UTC;
+ `-2` and on for another in the same second), logs `dump <label>`, and adds a
+ #word("Restore") `<label>` word naming it to the workspace tag (the last
+ dump's, replacing an earlier one's). The state file keeps the newest 32
+ dumps, and a text unchanged since an earlier one once; #file("/dumps")
+ lists them. `Dump export <path>` writes the dump to a file of its own
+ instead (`~` the home directory; the tag's word then names the path), which
+ `-l <path>` and #word("Restore") `<path>` read: the way to carry a session to
+ another machine.
+ #word("Restore") `[label|path]` replaces every pane: the state file's dump of
+ that label, or the dump in that file (an old `.dump` file too, for this
+ release); bare, the last dump this session made, else the newest. The
+ #word("Restore") write is answered, then *every connection is hung
up*: dial again, and restart a 9ns mount. The new log has a `new` per
- pane, then `restore <path>`. Its panes and columns keep the serials they
+ pane, then `restore <label|path>`. Its panes and columns keep the serials they
had when dumped; one made after takes a serial past every one the old
session handed out. A dump keeps every pane's text and undo: a clean
file changed on disk since comes back as it is now, an unsaved one with
its own text, marked changed on disk, and its first #word("Save") asks
before overwriting. A #word("Restore") of a file that is no dump fails
- before anything is replaced (`not a pardes dump: it is cut short`), with
- EIO: read the `err` record for why. A #word("ThemeFile") the dump names that fails to load changes
+ before anything is replaced (`not a pardes dump: it is cut short`), and one
+ of a label the state file keeps none of says `Restore: no dump labelled
+ <label>`, each with EIO: read the `err` 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 session no terminal or window is attached to (160x50
@@ -438,7 +448,7 @@ word clicked in a tag does. The same lines go in the startup file
[#word("JumpScope") `file|all`], [`file`: #word("Back") and #word("Forward") keep to the focused pane's file, that pane's places first, then the file's in another pane, and go to another file only when the file has no place left that way; from a terminal or a pane with no file they step through every place; `all`: every place, in the order it was jumped to],
[#word("TermImages") `real|petscii`], [`real`: a new terminal draws its program's kitty graphics (yazi's previews) as pixels where the shell can; #word("Petscii") flips one terminal; a tui under a terminal without kitty graphics draws them as glyph art either way],
[#word("Shell") `<name or path>`], [`$SHELL` when it is executable, else `/bin/sh`: the shell the next terminal and command pane run; a bare name is searched for in the usual bin directories, not `$PATH`; bare #word("Shell"): `$SHELL` if it is executable, else `/bin/sh`],
- [#word("DumpDir") `<dir>`], [`$XDG_DATA_HOME/pardes`, else `~/.local/share/pardes`: where #word("Dump") writes, an absolute or `~` path to a directory that may be written (made if missing); a relative one, or one under a directory that may not be written, is refused; bare returns to the default],
+ [#word("DumpDir") `<dir>`], [`$XDG_DATA_HOME/pardes`, else `~/.local/share/pardes`: the directory of the state file, `pardes.xitdb`, which keeps Recent and the dumps and which every session of the user shares (one that cannot be read as one is kept aside as `pardes.xitdb.broken` and a new one started); an absolute or `~` path to a directory that may be written (made if missing); a relative one, or one under a directory that may not be written, is refused; bare returns to the default],
[#word("TreeContext")], [off: sticky declaration headers in a source pane (per pane, dumped)],
[#word("TreeContextTagStyle")], [on: draw those headers in the tagline style],
[#word("LocationsConfig") `...`], [the layout of #word("Grep"), search and language-server results (below)],
@@ -890,7 +900,7 @@ just before the #word("Restore") are not lost.
[`ask <serial> <what> <choices>`, `answer <serial> <choice|->`], [a pane asked, and was answered (`-`: taken back, or the pane closed)],
[`changed <serial> [reloaded|deleted]`], [its file changed on disk (bare: under unsaved edits)],
[`unsaved <serial> <name>`], [a pane an #word("Exit"), #word("Restore"), #word("Del") or #word("Delcol") refused over, before the `err`],
- [`dump <path>`, `restore <path>`], [a #word("Dump") written; a #word("Restore"), after its panes' `new`s],
+ [`dump <label|path>`, `restore <label|path>`], [a #word("Dump") written (a label of the state file's, or the file `Dump export` named); a #word("Restore"), after its panes' `new`s],
)
The serial is the pane the line ran at (the pane with the keyboard for the root's
@@ -927,12 +937,17 @@ at 200, ending in `…`. Control characters become spaces.
pane from the root).
- #file("/recent"): up to 200 files, PDFs and images, most recent first,
`open <path>` or `closed <path>` (open in this window or not), every
- window's: kept in `$XDG_STATE_HOME/pardes/recent`, shared by every pardes
- process, each reading what the others wrote when it is next read.
+ window's: kept in the state file (#word("DumpDir")'s `pardes.xitdb`), shared
+ by every pardes process, each reading what the others wrote when it is next
+ read.
#word("Recent") lists them in a query pane (line 1 `Recent`, the rest
narrowing them by a fuzzy match), an open one at its dot now and a
closed one at its last (a PDF's is its page); a #word("Look") of a row reopens it
there.
+- #file("/dumps"): the dumps the state file keeps, a line each, the newest
+ first: `<label> <date> <size> <panes>`, the date UTC
+ (`2026-11-05T12:00:00Z`), the size the dump's bytes (its session and the
+ texts it keeps); #word("Restore") `<label>` brings one back.
- #file("/status"): `pid`, `version`, `panes`.
- #file("/pager"): write a directory, `~` expanded and resolved (an empty
line is the session's; one not there is refused ENOENT, a relative one
diff --git a/docs/typ/setup.typ b/docs/typ/setup.typ
index 466b178a..c94751da 100644
--- a/docs/typ/setup.typ
+++ b/docs/typ/setup.typ
@@ -6,6 +6,25 @@
= Install <install>
#include "install.typ"
+= The files pardes keeps <files>
+
+- `~/.config/pardes/init`, the startup file; `themes/` there, the
+ #word("ThemeFile")s and #word("DumpThemes")'s; `crashes` there, a line or
+ two each time pardes panicked.
+- `pardes.xitdb` in the #word("DumpDir") (`$XDG_DATA_HOME/pardes`, else
+ `~/.local/share/pardes`): the state file, a xitdb database every session
+ of yours shares: Recent and the dumps (#file("/dumps") lists them). It is
+ compacted at a session's end once it holds mostly what no dump keeps.
+- `cache.xitdb` in `$XDG_CACHE_HOME/pardes` (else `~/.cache/pardes`): a far
+ client's blob cache, a gigabyte at most (`PARDES_BLOB_CACHE_MB`), safe to
+ delete.
+- In `$XDG_RUNTIME_DIR`: the sessions' sockets and their registry entries
+ (`9p/pardes/`), and a pane on its way to another window.
+- From the build before: `~/.local/state/pardes/recent` (and `store` beside
+ it) is read once into the state file; `pardes-*.dump` files in the
+ DumpDir are read by #word("Restore") `<path>` and `-l`, for one release; the
+ directory `~/.cache/pardes/blobs` is no longer read. Each can be deleted.
+
= A 9P mount: 9ns <ninens>
`9ns`, from cloud9 (`git.sr.ht/~gbrls/cloud9`, whose `zig build` builds it