summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-10-24 14:10:14 -0300
committerGabriel Schneider <[email protected]>2026-10-24 15:50:47 -0300
commit93862a52fd695014969a272b04f442e512211a97 (patch)
tree66eb1a756f99d9e987201d010370d19c561f7f3c /docs
parentf3405aaef8db79094b2741a9caaeaa5328ab6288 (diff)
downloadpardes-93862a52fd695014969a272b04f442e512211a97.tar.gz
pardes-93862a52fd695014969a272b04f442e512211a97.zip
Store 3/3: Recent and Panes in the guide and reference, the changelog, an unhosted core's flush returning before any host call, the design note as built with its numbers and positions
Diffstat (limited to 'docs')
-rw-r--r--docs/next-store.md113
-rw-r--r--docs/typ/guide.typ4
-rw-r--r--docs/typ/reference.typ4
3 files changed, 118 insertions, 3 deletions
diff --git a/docs/next-store.md b/docs/next-store.md
index 894ea2f5..67702438 100644
--- a/docs/next-store.md
+++ b/docs/next-store.md
@@ -126,3 +126,116 @@ newest closed panes.
The old `recent` file is read once into a store that does not exist yet,
so nobody's list is lost; it is left where it is.
+
+## As built
+
+| piece | where |
+|---|---|
+| the log: framing, reader, resync, fold, flush, compaction | `src/Store.zig` (`Pardes.store`) |
+| Recent as records: `Entry.changed`, `List.note` (a record read), `changedFirst` | `src/recent.zig` |
+| a pane to and from a Dump, one at a time | `dump.dumpPane`, `dump.restorePane` (lifted out of `dumpState` / `initDump`) |
+| a closed pane kept: before its teardown, its rows' gainer after | `Pardes.removePane`, `Pardes.removeColumn` (`Store.keep`, `Store.close`) |
+| back where it was | `Store.reopen` → `layout.giveBack` (rows from the gainer alone), `layout.attachFrom` for an attachment whose owner is open, else `exec.placeNew` |
+| Panes: open panes, then this session's closed ones, `@p7 notes/a.md (closed)`, dimmer (the gutter's colour between the match marks) | `Query.startSource` / `makeNameRows` / `land` |
+| Recent and `/recent` read the store on use | `Query.startSource`, `ninep/tree.zig` |
+| the path | `main.storePath`: `$XDG_STATE_HOME/pardes/store` (`Options.store_path`, was `recent_path`) |
+
+Which closes are kept: every `removePane` / `removeColumn` of a pane the
+user had (announced: a pane made and refused in one step never was), not
+a query pane nor a +Preview. Exit and Restore keep nothing (Restore's new
+core takes the old session's list, `Store.clone`). Brought back, a pane is
+a new pane (a fresh serial, as Restore gives); its row goes (`x` record).
+
+A Look at `@p7` naming a pane this session closed brings it back instead of
+the "no pane @p7" miss: the row's text is its address, as everywhere. That
+is the only change to Look, in its miss branch.
+
+**The turn.** Every host call is made out of the turn (`Store.host(f,
+args)`, one call each), so a store under a mount of this session's own
+tree cannot deadlock, and nothing in the store or Recent changes while a
+step is out. `/recent` (a 9P read) reads the store only when no step is
+out; otherwise it answers the list as it was.
+
+## Measured (Debug, the `zz store timings` test, STORE_TIMES=<dir>)
+
+A store as a running session leaves it: 200 files and 90 closed panes of
+1 MiB (94 MB).
+
+| what | cost |
+|---|---|
+| a session starting on it (`load`: headers only, every `c` body skipped) | 3.4 ms |
+| a refresh with nothing new (one `stat`) | ~1 µs |
+| a flush of one record (lock, read the tail, one write) | 36 µs |
+| a compaction of the 94 MB file (CRC of every record, copy the live, rename) | 278 ms, to 51 MB (the newest within half the cap) |
+
+## Tests
+
+`store: two windows share Recent...` (two cores on one file, a lock held by
+a third party delays a write and loses nothing, a fresh window folds the
+same list), `store: the cap holds...` (3000 files and 30 closed 20 KB
+scratches against a 48 KiB / 256 KiB cap: never past it, compactions
+happen, the newest 200 files and the newest closed pane survive),
+`store: a garbage or torn file...` (a foreign file, a torn header, junk,
+then a whole record; a half-written record waited for; mended by the next
+writer), `store: a closed pane comes back...` (from the file, not memory;
+its rect, the gainer's and another column's as before the close; listed
+`(closed)` in Panes, Enter brings it back, unlisted after a re-read; another
+session lists none). `test/fs.py store_shared_between_windows`: two live
+sessions over 9P. The related suites (dump, Restore, query, Find, Grep,
+Del, Delcol, attach, collapse, jump, Edit, recent) pass. The tty build
+compiles.
+
+Found, not mine: `fs.py recent_survives_restart` fails on the converge
+baseline too, at its Recent step (the query pane's rows are relative
+names now, the test looks for absolute ones).
+
+## Open questions, and my position on each
+
+1. **Closed panes on disk or in memory?** On disk (argued above). The
+ honest counter: only this session reads them, and a Del now costs a
+ dump and a write. Measured, a flush is 36 µs; the dump of a big
+ terminal is the cost (its history base64'd), capped at 8 MiB.
+2. **Recent's cap stays 200**, now for every window together. Shared, it
+ fills faster; 1000 is cheap for the fuzzy scorer. I kept 200 to change
+ one thing at a time; I would raise it.
+3. **"open" means open here.** A file open in another window reads
+ `(closed)` in this one's Recent (its place is the other window's last
+ close). Saying `open elsewhere` needs the store to know which windows
+ are alive and what they hold (a record per open, its pid): doable,
+ not done.
+4. **Compaction is on the loop** (278 ms for 94 MB, Debug). It happens
+ when the file doubles past what was live, or reaches the cap, which a
+ window that closes many big terminals does. Off the loop it would need
+ the disk engine's worker and the lock held across frames; I would do
+ it only if it shows up. A store of Recent alone is ~20 KB to rewrite
+ (not timed separately).
+5. **A crashed session's closed panes** are dropped at the next
+ compaction (its pid is gone). Keeping them a day for a "what was I
+ doing" word would be cheap: the records are there.
+6. **A dirty file pane closed with the second Del** comes back with its
+ unsaved text (it is in its dump, by Restore's rules; not tested
+ here). That is a feature (undo a discard)
+ and a surprise (the discard was asked for twice). I kept it; say if a
+ discard should be final.
+
+## What I would push back on
+
+- "shared among all pardes windows" for the closed panes: they are this
+ session's by the spec, so the sharing is only of the file and its bound.
+ If the bound is the only reason, an in-memory list with a byte budget
+ is less code (no `c`/`x` records, no offsets); I chose the disk for the
+ memory and Restore, but this is the part I hold least firmly.
+- The 100 MiB: nothing in Recent comes near it; only closed terminals'
+ history does. A smaller cap (16 MiB) would bound compaction to ~50 ms
+ and lose little. 100 MiB is what was asked, so it is the default.
+- Reopening a closed pane makes a new serial: `@p7` in old text names a
+ pane that is now `@p12`. Restore does the same and logs `restored 7 12`;
+ the store could log the same, not done.
+
+## Rough
+
+- The dim tint of a closed Panes row is the gutter colour (`lineno`), not
+ checked by eye in every theme.
+- A Delcol'd pane comes back where `placeNew` puts it (its column is gone).
+- An attachment whose owner was closed with it comes back as a plain pane
+ next to wherever placement puts it (its owner's serial is new).
diff --git a/docs/typ/guide.typ b/docs/typ/guide.typ
index 9fd33e60..d479a884 100644
--- a/docs/typ/guide.typ
+++ b/docs/typ/guide.typ
@@ -189,8 +189,8 @@ Line 1's first word names what it searches, and editing the word changes it:
[`/pat`], [the pane's own text: a regex, any case unless it has a capital (#key("/"))],
[`Find name`], [the files below the pane's directory, by a fuzzy match of their names (#key("SPC f f"), #word("Find"))],
[`Grep text`], [the lines of those files holding `text`, literally (#key("SPC f g"), #word("Grep")); past 2000 lines #word("More") goes on],
- [`Recent name`], [the files opened lately (#key("SPC f r"), #word("Recent"))],
- [`Panes name`], [the open panes (#key("SPC b b"), #word("Panes"))],
+ [`Recent name`], [the files opened lately, in any window (#key("SPC f r"), #word("Recent"))],
+ [`Panes name`], [the open panes, then the ones closed this session, `(closed)` and dimmer: #key("Enter") (or a #word("Look") at its `@pN`) brings one back where it was, its text with it (#key("SPC b b"), #word("Panes"))],
[`Symbols name`], [the text's declarations (#key("SPC s s"))],
[`All pat`], [every open pane's text, its rows under each pane (#key("SPC /"))],
[`Refs`, `Def`, `Impl`, `Diagnostics`], [the language server's lists; their places in the text tinted as a `/`'s are, `]d` stepping the diagnostics],
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index 3ddcd881..b83b4a83 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -910,7 +910,9 @@ at 200, ending in `…`. Control characters become spaces.
a line, generated from the builtin registry (`both`: #word("Edit"), at the active
pane from the root).
- #file("/recent"): up to 200 files, PDFs and images, most recent first,
- `open <path>` or `closed <path>`; kept in `$XDG_STATE_HOME/pardes/recent`.
+ `open <path>` or `closed <path>` (open in this window or not), every
+ window's: kept in `$XDG_STATE_HOME/pardes/store`, 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