summaryrefslogtreecommitdiff
path: root/docs/next-store.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/next-store.md')
-rw-r--r--docs/next-store.md113
1 files changed, 113 insertions, 0 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).