diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/next-store.md | 113 | ||||
| -rw-r--r-- | docs/typ/guide.typ | 4 | ||||
| -rw-r--r-- | docs/typ/reference.typ | 4 |
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 |
