diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-17 00:45:31 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-17 12:15:01 -0300 |
| commit | e699ffe4182f66e28180ea2d91ab1fb8c408d49e (patch) | |
| tree | 0577374fb6164ef214cd727b662a23498ad547eb /README.md | |
| parent | a1ae80096bd69ee7d92ea9e4564e960d8553395e (diff) | |
| download | sketchbook-e699ffe4182f66e28180ea2d91ab1fb8c408d49e.tar.gz sketchbook-e699ffe4182f66e28180ea2d91ab1fb8c408d49e.zip | |
Delete the Store; State is checked against the 64 MiB a save holds
A sketch's data is State: flat bytes, what grows has its capacity in its
type. The Store, a heap in a file mapped at 0x2000_0000_0000 with 64 GiB
reserved, its power-of-two allocator, its root adopt and migration, and
its test, are gone from memory.zig; so are Context.store and store_root,
Info.store, Memory.store, the Store declaration's glue, Init.store,
Frame.store and Console.store, the web host's store in wasm memory, the
host's StoreFile wiring and `<state>.store` file, the `.store` suffix in
moving an old state into .sketchbook/, the build's tests' `rm` of it, and
layout.check's `pointers` flag (State is the one checked memory now).
Its one real user, micscope, moved off it in the change before. Old
`.state.store` files are not read, converted or deleted, and stay
ignored by .gitignore. A sketch that still declares a Store gets no
error for the declaration: nothing reads it, and a `*Store` parameter is
a compile error (no argument of that type).
layout.of(T, .state) refuses a State bigger than layout.max_state, 64 MiB,
one constant: "State is N bytes, and a save holds at most 64 MiB: lower
a capacity (an array, an sk.List), or keep what need not be saved in
Session." The pointer-hash gap the spec found (a Store pointer's
element type changing kept the old bytes) is gone with the only
persisted memory that held pointers.
README: no Store row, allocator row, migration paragraph, file bullet or
known limits; draw and command lose their store parameter; State's row
says 64 MiB at most; data that grows and is the user's work goes in a
List in State or, bigger than a save, in files the sketch appends to.
Tests: zig build test, 166/166 steps (the store's unit test gone; new: a
65-MiB State fails to compile with the message above, by expect_errors).
micscope, spheres, noc's e2e and drat-meout's test unchanged and green.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 55 |
1 files changed, 21 insertions, 34 deletions
@@ -44,24 +44,23 @@ An app is an ordinary module. Every declaration is optional: | Declaration | Meaning | | --- | --- | | `name`, `width`, `height` | Window title and initial canvas | -| `State` | Saved to a file, kept in every session's keyframes and marks, replayed: what `update` changes. No pointers and no host handles (compile errors). | +| `State` | Saved to a file, kept in every session's keyframes and marks, replayed: what `update` changes. No pointers, no host handles, and at most 64 MiB (compile errors). | | `Session` | This process: survives reloads, never saved. Caches, image and buffer handles, playback cursors. | -| `Store` | On disk, at the same address in every run: survives reloads and restarts. Big data that is not replayed (a recording, a document). May point into itself; no host handles. | | `init(state, host)` | Seed brand-new state, after the declared defaults | | `setup(session, init) !void` | Initialize resources once per fresh Session, including startup with restored State | | `update(state, input)` | **Deterministic**: the host replays recorded input through it | -| `draw(state, session, store, frame)` | Pictures and sound, as commands; may change Session and Store | -| `command(state, session, store, console, line) !bool` | Console lines the host does not know | +| `draw(state, session, frame)` | Pictures and sound, as commands; may change Session | +| `command(state, session, console, line) !bool` | Console lines the host does not know | | `commands` | Console completions | Functions take the parameters they name, matched by type and in any order: -`draw(s: *const State, f: *sk.Frame)` and `draw(s: *const State, store: -*Store, ss: *Session, f: *sk.Frame)` both work. `update` can only ask for +`draw(s: *const State, f: *sk.Frame)` and `draw(f: *sk.Frame, ss: *Session, +s: *const State)` both work. `update` can only ask for `State` and `Input`; asking for more is a compile error, since a replay could not reproduce it. -`setup` receives `*sk.Init` with `host`, `session`, and `store` allocators; -it may also request Session, Store, or Host directly. It gets no State, Input, +`setup` receives `*sk.Init` with `host` and the `session` allocator; it may +also request Session or Host directly. It gets no State, Input, or Frame. Load assets and create/upload GPU buffers there, then use those resources in `draw`. `try init.host.writeBuffer(buffer, offset, bytes)` submits a copy immediately; the source bytes may be released when it returns. WebGPU @@ -82,14 +81,11 @@ Memory comes by lifetime, one allocator each: | --- | --- | --- | | `f.scratch` | this frame | all at once, after the frame is drawn | | `f.session` | this process | one allocation at a time; the rest when Session's layout changes, along with the images and buffers the session made | -| `f.store` | on disk, `<state>.store` | one allocation at a time; `--fresh` empties it | -A Store layout change migrates field by field like State: unchanged fields, -pointers included, keep their values, since the store never moves. -`command` gets the session and store allocators on its `Console`. +`command` gets the session allocator on its `Console`. -`update` sees only State, so when a key should do something to Session or -Store, State carries a request: `seek: sk.Request(f32)`, sent with +`update` sees only State, so when a key should do something to Session, +State carries a request: `seek: sk.Request(f32)`, sent with `s.seek.send(0.5)`. Session keeps an `sk.Handled`, and `draw` runs `if (ss.seek.take(s.seek)) |to| ...` once per request. A fresh Session counts earlier requests as handled, so nothing re-fires after a restart. @@ -131,7 +127,7 @@ State. `decodeSound`, `newSound`, `samples`, `readFile`, `appendFile`, `env`, `log`, `textSize`). Commands may be built from locals: the methods copy what they keep (text, GPU descriptions, uniforms) into scratch. Bulk data (vertices, samples, pixels, uploads) is -not copied and must outlive the frame: scratch, session or store memory. +not copied and must outlive the frame: scratch or session memory. `f.text(x, y, scale, bytes, color)` draws one line from its top left corner; scale 1 is a 13 px monospace face (8 px a character on a 16 px @@ -168,8 +164,8 @@ move. The web host ignores `raster`. dialog; the answer comes back as the console line `open <path>`, so it reaches the sketch's `command` like anything typed there. `f.run(line)` does the same with any line, after the frame: `draw` cannot write State, -so this is how it tells State something only it learns (how many takes a -Store holds, say). +so this is how it tells State something only it learns (which of its +files are already written, say). `f.host.appendFile(name, bytes)` appends to a file of the sketch's own, `<state>.<name>` beside its state file (in `.sketchbook/` under `zig build @@ -375,9 +371,8 @@ after a reload that shrinks it. The default buffer is the element's own defaults, never `std.mem.zeroes` (an enum may have no 0). **Data that grows.** State is kept in keyframes, replayed and migrated, so -it holds what `update` changes, at a size fixed in its type. Store is not -kept in keyframes or replayed, so what is in it does not follow a seek. Three -cases, by who needs the data: +it holds what `update` changes, at a size fixed in its type, 64 MiB at most. +Three cases, by who needs the data: - `update` needs it: a `List` in State, sized for the worst case (the quadtree's 4096 points, 32 KiB; flocking's 2048 boids). @@ -391,7 +386,8 @@ cases, by who needs the data: may derive it differently. A cheap derivation needs no cache at all: the quadtree builds its tree in `f.scratch` every frame. - It is the user's work, not a function of State (a recording, a - document): Store. + document): a `List` in State, or, bigger than a save, files of the + sketch's own (`appendFile`), named from State, as micscope's takes are. The timeline then needs nothing more: a seek changes the key like an update does (`examples/noc`: `koch`, `lsystem`, `quadtree`). @@ -781,17 +777,12 @@ a talk with a slider, a loop, a choice, two slides and `beside`. rewritten, and the snapshot slots of files from before sessions become marks `1` to `7` in a run that records; a file that is not a state file is refused, never truncated. -- **Store file.** `<name>.state.store` is a heap mapped at a fixed address - (`0x2000_0000_0000`, 64 GiB reserved), grown in place, locked to one - process. Power-of-two size classes with free lists in the file. - Keyframes, marks and replays do not cover it (only `draw` and `command` - change it). - **Where files go.** `zig build run`, `probe` and `export` keep a sketch's - files in `.sketchbook/`: `<name>.state`, `<name>.state.store` and - `<name>.xitdb`. The host makes the directory with a `.gitignore` of `*`, + files in `.sketchbook/`: `<name>.state`, `<name>.xitdb` and the + `<name>.state.<file>` it appends to. The host makes the directory with a `.gitignore` of `*`, so neither git nor jj takes in a database that grows (the jj snapshot a build makes would commit one while it is under a megabyte), and moves in, - once, the state and store an older build kept in the project's root; + once, the state an older build kept in the project's root; when both exist, nothing moves and the host says which is used. Without `--state`, a run keeps them in `$XDG_DATA_HOME/<name>/` (`~/.local/share/<name>/` without it), which is where a shipped game's @@ -1103,17 +1094,13 @@ Add `.sketchbook = .{ .path = "..." }` to your `build.zig.zon`. `f.openFile` answers with a line of any length. - Every upload, compute dispatch and GPU pass is its own command buffer and submit. Fine at a handful per frame; batch them per frame if that grows. -- The store is not crash-safe: a crash in the middle of an allocation can - leave it inconsistent, and `--fresh` starts it over. -- Handles inside Store containers (`std.ArrayList(sk.Image)`) are not caught - at compile time: the check does not follow pointers. - Native antialiasing resolves coverage per sample within a run of shapes, the canvas per shape, so where two shapes' edges meet the web can show a faint seam native does not. `fill` rects and images are antialiased natively only inside a target. Without a GPU renderer, native draws aliased. A stroke that overlaps itself blends twice natively where it overlaps, once on the web. -- On the web: nothing persists (Store lasts as long as the page) and no +- On the web: nothing persists and no sessions are recorded, and multisampling is 4× at most. Every voice is silent there, whatever its sound (loaded, decoded or made with `newSound`), and so are groups' gains; `decodeSound` gives `.none`, and |
