summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-17 01:01:26 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commit70be2e0776d2e61a2d018b264ef5602e7e2c7f86 (patch)
tree620d316cc48062d374b1c270cda0723afbb3fc7f
parente699ffe4182f66e28180ea2d91ab1fb8c408d49e (diff)
downloadsketchbook-70be2e0776d2e61a2d018b264ef5602e7e2c7f86.tar.gz
sketchbook-70be2e0776d2e61a2d018b264ef5602e7e2c7f86.zip
micscope: a take starts its file empty; a deleted take's file stays, and why
Phase 1 left two loose ends in micscope's take files. A new take could continue an old file when its id met one already written without a jump in between (the jump is what moves next_id past written files), and a deleted take's file stayed on disk. The host gains one call beside appendFile: f.host.writeFile(name, bytes) writes a new, empty file of that name, through the same vtable entry with a `replace` flag. The old file is unlinked, so a readFile mapping of it keeps its bytes, and the host's cached mapping is retired (kept until exit, the sketch may hold it) so the next readFile maps the new file. The web host writes nothing, as for appendFile. micscope writes each take's file so when the take begins: on the frame whose transport request is newly `recording`, live, and not a jump (a jump's requests are restored State's, not a beginning; a fresh Session counts old requests as handled, so a restart mid-recording keeps its file), before the takes are read; `open` writes a file's samples so too. A deleted take's file stays: its State entry comes back with any seek or mark from before the delete, marks are kept with no end, and an exported session carries them; neither the sketch (which cannot see the history) nor the host (which cannot read State's meaning) can tell when none is left. So "never, safely": the file is kept. Tests: zig build test, 164/166 steps, 132/132 tests (the appendFile test now also replaces a file and reads back only the new bytes); the one failure was the Typst bench's 1 ms bound (1.024 ms), timing code this change does not touch, on a machine loaded by other builds; it passed in the next full run (166/166, with the change above this one). micscope's zig build test, 67/67 steps, 10/10 tests. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
-rw-r--r--README.md8
-rw-r--r--examples/micscope/README.md5
-rw-r--r--examples/micscope/src/main.zig11
-rw-r--r--src/abi.zig11
-rw-r--r--src/host/Host.zig24
-rw-r--r--src/sketch/web.zig2
6 files changed, 45 insertions, 16 deletions
diff --git a/README.md b/README.md
index 7691d85..b59c3a3 100644
--- a/README.md
+++ b/README.md
@@ -124,7 +124,7 @@ State.
`imageAt`, `target`, `blend`, `text`, `print`, `clip`, `canvas`, `cursor`, `voice`, `gain`, `audio`, `microphone`, `pixels`, `gpu`,
`compute`, `upload`, `download`, `openFile`, `run`, `quit`, plus the three allocators and
`f.host` (`loadImage`, `decodeImage`, `newImage`, `newBuffer`, `loadSound`,
-`decodeSound`, `newSound`, `samples`, `readFile`, `appendFile`, `env`, `log`, `textSize`). Commands may be built
+`decodeSound`, `newSound`, `samples`, `readFile`, `appendFile`, `writeFile`, `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 or session memory.
@@ -172,8 +172,10 @@ files are already written, say).
run`), creating it, and returns its path for `readFile` ("" when nothing
was written, and always on the web). Only `draw` and `command` can call it,
and a write is not replayed, like sound. `readFile` maps a file once, so
-what is appended afterwards is not in what it returned. micscope writes
-each take to `take-<id>.f32` as it records.
+what is appended afterwards is not in what it returned.
+`f.host.writeFile(name, bytes)` does the same to a new, empty file of that
+name. micscope starts each take's `take-<id>.f32` so, and appends to it as
+it records.
`f.download(buffer, .{ .size = n, .key = k })` reads a GPU buffer back
without stalling: the bytes arrive in a later frame's `in.downloads`, a
diff --git a/examples/micscope/README.md b/examples/micscope/README.md
index c02318c..e917bf0 100644
--- a/examples/micscope/README.md
+++ b/examples/micscope/README.md
@@ -151,7 +151,8 @@ addresses as QR codes, for phones).
Each take is a file of its samples (mono 32-bit floats at the host's
rate), `micscope.state.take-<id>.f32` beside the state (in `.sketchbook/`
under `zig build run`), written as it records (`Host.appendFile`). State
-lists the takes, so they are still there after a restart. A deleted take's
-file stays: a seek back finds it again. Takes stop at ten minutes; the
+lists the takes, so they are still there after a restart. A take starts
+its file empty (`Host.writeFile`). A deleted take's file stays: a seek
+back, or any mark from before the delete, finds it again. Takes stop at ten minutes; the
strip holds 64. A `micscope.state.store` from before is not read: its takes
stay in it.
diff --git a/examples/micscope/src/main.zig b/examples/micscope/src/main.zig
index ba7d678..99aac76 100644
--- a/examples/micscope/src/main.zig
+++ b/examples/micscope/src/main.zig
@@ -486,7 +486,8 @@ fn panBy(s: *State, pixels: f32, in: *const sk.Input) void {
}
/// Deletes the selected take and selects the one above it. Its file stays:
-/// the host deletes no files, and a seek back finds it again.
+/// any keyframe or mark from before the delete brings the take back, and
+/// neither the sketch nor the host can tell when none is left.
fn remove(s: *State, in: *const sk.Input) void {
const n = s.takes.count();
const index = @min(s.selected, n - 1);
@@ -539,7 +540,7 @@ pub fn command(s: *State, ss: *Session, c: *sk.Console, line: []const u8) !bool
try ss.tape.appendSlice(c.session, kept);
try ss.clips.appendBounded(.{ .id = take.id, .start = ss.tape.items.len - kept.len, .len = kept.len });
var file: [32]u8 = undefined;
- _ = c.host.appendFile(try std.fmt.bufPrint(&file, "take-{d}.f32", .{take.id}), std.mem.sliceAsBytes(kept));
+ _ = c.host.writeFile(try std.fmt.bufPrint(&file, "take-{d}.f32", .{take.id}), std.mem.sliceAsBytes(kept));
try s.takes.appendBounded(take);
s.next_id += 1;
s.selected = s.takes.count() - 1;
@@ -571,13 +572,15 @@ pub fn draw(s: *const State, ss: *Session, f: *sk.Frame) void {
while (f.host.readFile(f.host.appendFile(f.format("take-{d}.f32", .{id}), &.{})).len > 0) id += 1;
if (id != s.next_id) f.run(f.format("next-id {d}", .{id}));
}
- readTakes(s, ss, f);
-
// Requests from State. Any of them, or another take selected, flushes
// what is queued, so the cursor restarts from what was heard.
const transport = ss.transport.take(s.transport);
const seek = ss.seek.take(s.seek);
const takes = s.takes.constSlice();
+ // A take that begins here (not one a jump brought) starts its file
+ // empty, whatever a file of its id held.
+ if (transport == .recording and writing and !in.jumped and takes.len > 0) _ = f.host.writeFile(f.format("take-{d}.f32", .{takes[takes.len - 1].id}), &.{});
+ readTakes(s, ss, f);
const selected: ?*Clip = if (takes.len > 0) clipOf(ss, takes[@min(s.selected, takes.len - 1)].id) else null;
var queued: usize = in.stream(stream).queued;
if (selected) |t| {
diff --git a/src/abi.zig b/src/abi.zig
index aecb654..3991a35 100644
--- a/src/abi.zig
+++ b/src/abi.zig
@@ -647,8 +647,8 @@ pub const Host = struct {
samples: *const fn (*anyopaque, Audio) []const f32,
/// The whole file, mapped for the life of the host; empty if missing.
readFile: *const fn (*anyopaque, []const u8) []const u8,
- /// See `Host.appendFile`: name, then bytes.
- appendFile: *const fn (*anyopaque, [*]const u8, usize, [*]const u8, usize) callconv(.c) [*:0]const u8,
+ /// See `Host.appendFile`: name, then bytes; `replace` for `writeFile`.
+ appendFile: *const fn (*anyopaque, [*]const u8, usize, [*]const u8, usize, bool) callconv(.c) [*:0]const u8,
env:*const fn (*anyopaque, []const u8) ?[]const u8,
/// A monotonic clock in nanoseconds, for measuring, not for state:
/// `update` must use `Input` time to stay replayable.
@@ -730,7 +730,12 @@ pub const Host = struct {
/// replayed, like sound. `readFile` maps a file once: what is appended
/// to it afterwards is not in what it returned.
pub fn appendFile(h: Host, name: []const u8, bytes: []const u8) []const u8 {
- return std.mem.span(h.vtable.appendFile(h.ctx, name.ptr, name.len, bytes.ptr, bytes.len));
+ return std.mem.span(h.vtable.appendFile(h.ctx, name.ptr, name.len, bytes.ptr, bytes.len, false));
+ }
+ /// `appendFile` to a new, empty file of that name: what the old one
+ /// held is gone (a `readFile` of it keeps its bytes).
+ pub fn writeFile(h: Host, name: []const u8, bytes: []const u8) []const u8 {
+ return std.mem.span(h.vtable.appendFile(h.ctx, name.ptr, name.len, bytes.ptr, bytes.len, true));
}
pub fn env(h: Host, name: []const u8) ?[]const u8 {
return h.vtable.env(h.ctx, name);
diff --git a/src/host/Host.zig b/src/host/Host.zig
index 75b49b3..3a2a25f 100644
--- a/src/host/Host.zig
+++ b/src/host/Host.zig
@@ -106,6 +106,8 @@ commands: std.ArrayList(abi.Command) = .empty,
pending: std.ArrayList(abi.Event) = .empty,
input: abi.Input = .{},
files: std.StringHashMapUnmanaged([]align(memory.page) const u8) = .empty,
+/// Mappings of files `writeFile` replaced: the sketch may still hold them.
+retired: std.ArrayList([]align(memory.page) const u8) = .empty,
/// The paths `appendFile` wrote, each once, 0-terminated: the sketch keeps
/// them.
written: std.StringHashMapUnmanaged(void) = .empty,
@@ -254,6 +256,8 @@ pub fn deinit(self: *Host) void {
std.posix.munmap(entry.value_ptr.*);
}
self.files.deinit(self.gpa);
+ for (self.retired.items) |bytes| std.posix.munmap(bytes);
+ self.retired.deinit(self.gpa);
var written = self.written.keyIterator();
while (written.next()) |path| self.gpa.free(path.ptr[0 .. path.len + 1]);
self.written.deinit(self.gpa);
@@ -1081,7 +1085,7 @@ fn apiReadFile(ctx: *anyopaque, path: []const u8) []const u8 {
self.files.put(self.gpa, key, bytes) catch self.gpa.free(key);
return bytes;
}
-fn apiAppendFile(ctx: *anyopaque, name_ptr: [*]const u8, name_len: usize, bytes: [*]const u8, len: usize) callconv(.c) [*:0]const u8 {
+fn apiAppendFile(ctx: *anyopaque, name_ptr: [*]const u8, name_len: usize, bytes: [*]const u8, len: usize, replace: bool) callconv(.c) [*:0]const u8 {
const self = hostOf(ctx);
const name = name_ptr[0..name_len];
if (name.len == 0 or std.mem.indexOfScalar(u8, name, '/') != null) {
@@ -1090,6 +1094,14 @@ fn apiAppendFile(ctx: *anyopaque, name_ptr: [*]const u8, name_len: usize, bytes:
}
var buf: [std.fs.max_path_bytes]u8 = undefined;
const path = std.mem.print(&buf, "{s}.{s}", .{ self.options.state, name }) catch return "";
+ if (replace) {
+ // A new file: a mapping of the old one stays valid.
+ std.Io.Dir.cwd().deleteFile(self.io, path) catch {};
+ if (self.files.fetchRemove(path)) |old| {
+ self.gpa.free(old.key);
+ self.retired.append(self.gpa, old.value) catch {};
+ }
+ }
const file = std.Io.Dir.cwd().createFile(self.io, path, .{ .truncate = false }) catch |err| {
self.print("appendFile: {s}: {t}", .{ path, err });
return "";
@@ -1319,6 +1331,7 @@ test "appendFile appends to a file beside the state and names it for readFile" {
host.gpa = std.testing.allocator;
host.io = io;
host.written = .empty;
+ host.files = .empty;
host.options = .{ .state = try std.mem.print(&buf, ".zig-cache/tmp/{s}/t.state", .{&tmp.sub_path}) };
defer {
var written = host.written.keyIterator();
@@ -1326,10 +1339,15 @@ test "appendFile appends to a file beside the state and names it for readFile" {
host.written.deinit(host.gpa);
}
const name = "take-1.f32";
- const path = std.mem.span(apiAppendFile(&host, name, name.len, "ab", 2));
+ const path = std.mem.span(apiAppendFile(&host, name, name.len, "ab", 2, false));
try std.testing.expect(std.mem.endsWith(u8, path, "/t.state.take-1.f32"));
- try std.testing.expectEqual(path.ptr, apiAppendFile(&host, name, name.len, "cd", 2));
+ try std.testing.expectEqual(path.ptr, apiAppendFile(&host, name, name.len, "cd", 2, false));
const bytes = try tmp.dir.readFileAlloc(io, "t.state.take-1.f32", host.gpa, .unlimited);
defer host.gpa.free(bytes);
try std.testing.expectEqualStrings("abcd", bytes);
+ // writeFile: a new file, its old bytes gone.
+ _ = apiAppendFile(&host, name, name.len, "e", 1, true);
+ const again = try tmp.dir.readFileAlloc(io, "t.state.take-1.f32", host.gpa, .unlimited);
+ defer host.gpa.free(again);
+ try std.testing.expectEqualStrings("e", again);
}
diff --git a/src/sketch/web.zig b/src/sketch/web.zig
index 9efad0f..49b9d42 100644
--- a/src/sketch/web.zig
+++ b/src/sketch/web.zig
@@ -475,7 +475,7 @@ fn Driver(comptime App: type) type {
return &.{};
}
/// No files on the web: nothing is written, and the path is "".
- fn appendFile(_: *anyopaque, _: [*]const u8, _: usize, _: [*]const u8, _: usize) callconv(.c) [*:0]const u8 {
+ fn appendFile(_: *anyopaque, _: [*]const u8, _: usize, _: [*]const u8, _: usize, _: bool) callconv(.c) [*:0]const u8 {
return "";
}
fn env(_: *anyopaque, _: []const u8) ?[]const u8 {