1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
|
//! Comptime reflection of a sketch's memory into `abi.Layout`.
//!
//! Structs are flattened into dotted leaf paths, and arrays and vectors into
//! element leaves: `boids: [64]Boid` gives one leaf `boids[].pos[]` for every
//! boid's every lane, with each `[]`'s count and stride in `dims`, rather
//! than 128 leaves. Each array also stays as a whole (`boids`, kind
//! `array`), which a host copies in one piece while its type is unchanged.
//! Optionals, unions and packed structs are one leaf. Each leaf carries a
//! structural hash of its type, so a host can tell, across a reload, which
//! bytes still mean the same thing. Padding is in no leaf.
//!
//! A concrete path names indices (`boids[3].pos[1]`); `match` resolves one
//! against a leaf's pattern at lookup time.
//!
//! What each kind of sketch memory may hold:
//! - State is saved to disk and snapshotted: no pointers, and no host
//! handles (images, sounds, buffers), which only mean something in the
//! process that made them.
//! - Session lives in this process: anything, as long as pointers go into
//! memory the host owns (its heaps, mapped files), never into the sketch
//! library, which a reload unmaps.
const std = @import("std");
const abi = @import("abi.zig");
/// The most a State may be, in bytes: a save holds at most 64 MiB.
pub const max_state = 64 << 20;
pub fn of(comptime T: type, comptime memory: abi.Memory) abi.Layout {
return comptime blk: {
@setEvalBranchQuota(1_000_000);
switch (memory) {
.state => {
check(T, @typeName(T));
if (@sizeOf(T) > max_state) @compileError(std.fmt.comptimePrint("State is {d} bytes, and a save holds at most {d} MiB: lower a capacity (an array, an sk.List), or keep what need not be saved in Session.", .{ @sizeOf(T), max_state >> 20 }));
},
.session => {},
}
const Leaves = struct {
const list = flatten(T, "", 0, &.{});
const fields: [list.len]abi.Field = list[0..list.len].*;
};
break :blk .{
.size = @sizeOf(T),
.alignment = @alignOf(T),
.hash = hash(T),
.fields = &Leaves.fields,
};
};
}
pub const Dim = abi.Field.Dim;
/// The most arrays a leaf may sit in.
pub const max_rank = 8;
fn flatten(comptime T: type, comptime prefix: []const u8, comptime base: usize, comptime dims: []const Dim) []const abi.Field {
comptime {
const here = if (prefix.len == 0) "value" else prefix;
switch (@typeInfo(T)) {
.@"struct" => |s| if (s.backing_integer == null) {
var leaves: []const abi.Field = &.{};
for (s.field_names, s.field_types, s.field_attrs) |name, F, attrs| {
if (attrs.@"comptime" or @sizeOf(F) == 0) continue;
const path = if (prefix.len == 0) name else prefix ++ "." ++ name;
leaves = leaves ++ flatten(F, path, base + @offsetOf(T, name), dims);
}
return leaves;
},
.array => |a| return elements(T, a.child, a.len, here, base, dims),
.vector => |v| if (lanes(v.child)) return elements(T, v.child, v.len, here, base, dims),
else => {},
}
return &.{leaf(T, here, base, dims)};
}
}
/// The whole array, then its elements' leaves.
fn elements(comptime T: type, comptime Child: type, comptime len: usize, comptime path: []const u8, comptime base: usize, comptime dims: []const Dim) []const abi.Field {
comptime {
if (dims.len == max_rank) @compileError("arrays nested deeper than " ++ std.fmt.comptimePrint("{d}", .{max_rank}) ++ " in sketch memory: " ++ path);
const whole = &[_]abi.Field{leaf(T, path, base, dims)};
if (@sizeOf(Child) == 0) return whole;
return whole ++ flatten(Child, path ++ "[]", base, dims ++ &[_]Dim{.{ .count = len, .stride = @sizeOf(Child) }});
}
}
/// Vector lanes are addressable bytes only for whole-byte numbers.
fn lanes(comptime Child: type) bool {
return switch (@typeInfo(Child)) {
.int, .float => @bitSizeOf(Child) == 8 * @sizeOf(Child),
else => false,
};
}
fn leaf(comptime T: type, comptime path: []const u8, comptime offset: usize, comptime dims: []const Dim) abi.Field {
comptime {
const kind: abi.Field.Kind = switch (@typeInfo(T)) {
.int => |i| if (i.signedness == .signed) .int else .uint,
.float => .float,
.bool => .bool,
.@"enum" => .@"enum",
.array => .array,
.vector => |v| if (lanes(v.child)) .array else .bytes,
else => .bytes,
};
const stored = dims[0..dims.len].*;
return .{
.path = (path ++ "\x00")[0..path.len :0],
.offset = offset,
.size = @sizeOf(T),
.kind = kind,
.hash = hash(T),
.tags = if (kind == .@"enum") tags(T) else "",
.rank = dims.len,
.dims = &stored,
};
}
}
/// The byte offset of `path`, which names indices (`list[3].pos[1]`), from
/// a leaf's own offset, when it is an element of the leaf with `pattern`
/// (`list[].pos[]`) and `dims`; null when it is not, or out of range.
pub fn match(pattern: []const u8, dims: []const Dim, path: []const u8) ?usize {
var p: usize = 0;
var q: usize = 0;
var d: usize = 0;
var offset: usize = 0;
while (p < pattern.len) {
if (pattern[p] == '[' and p + 1 < pattern.len and pattern[p + 1] == ']') {
if (q >= path.len or path[q] != '[') return null;
const start = q + 1;
q = start;
while (q < path.len and std.ascii.isDigit(path[q])) q += 1;
if (q == start or q >= path.len or path[q] != ']' or d >= dims.len) return null;
const index = std.fmt.parseInt(u32, path[start..q], 10) catch return null;
if (index >= dims[d].count) return null;
offset += @as(usize, index) * dims[d].stride;
d += 1;
q += 1;
p += 2;
} else {
if (q >= path.len or path[q] != pattern[p]) return null;
p += 1;
q += 1;
}
}
return if (q == path.len) offset else null;
}
pub const Resolved = struct { field: abi.Field, offset: usize };
/// The field `path` names, indices resolved: for readers of a sketch's own
/// reflected layout (the web host's `sk_field`).
pub fn resolve(fields: []const abi.Field, path: []const u8) ?Resolved {
for (fields) |f| {
const delta = match(std.mem.span(f.path), f.dims[0..f.rank], path) orelse continue;
return .{ .field = f, .offset = f.offset + delta };
}
return null;
}
fn check(comptime T: type, comptime path: []const u8) void {
comptime {
if (T == abi.Image or T == abi.Audio or T == abi.Buffer) @compileError("State cannot hold host handles (" ++ path ++ "): they mean nothing to the next process. Keep them in Session.");
switch (@typeInfo(T)) {
.pointer => @compileError("State cannot hold pointers (" ++ path ++ "): it is saved to disk and outlives every address. Keep indices or offsets, or put it in Session."),
.array => |a| check(a.child, path ++ "[]"),
.vector => |v| check(v.child, path ++ "[]"),
.optional => |o| check(o.child, path),
.@"struct" => |s| for (s.field_names, s.field_types) |name, F| check(F, path ++ "." ++ name),
.@"union" => |u| for (u.field_names, u.field_types) |name, F| check(F, path ++ "." ++ name),
else => {},
}
}
}
fn tags(comptime E: type) [:0]const u8 {
comptime {
var text: []const u8 = "";
const e = @typeInfo(E).@"enum";
for (e.field_names, e.field_values, 0..) |name, value, i| {
text = text ++ (if (i == 0) "" else ",") ++ name ++ "=" ++ decimal(value);
}
return (text ++ "\x00")[0..text.len :0];
}
}
/// Equal hashes mean the bytes can be copied and keep their meaning. Enum
/// leaves also carry their tags, so a host can remap them by name.
pub fn hash(comptime T: type) u64 {
return comptime blk: {
@setEvalBranchQuota(1_000_000);
break :blk std.hash.Wyhash.hash(0, signature(T));
};
}
/// `n` in decimal, as `{d}` prints it: `std.fmt.comptimePrint` costs about a
/// millisecond of comptime a call, and a signature makes hundreds.
fn decimal(comptime n: comptime_int) []const u8 {
if (n < 0) return "-" ++ decimal(-n);
if (n < 10) return &[_]u8{'0' + n};
return decimal(n / 10) ++ &[_]u8{'0' + n % 10};
}
pub fn signature(comptime T: type) []const u8 {
comptime {
return switch (@typeInfo(T)) {
.int => |i| (if (i.signedness == .signed) "i" else "u") ++ decimal(i.bits),
.float => |f| "f" ++ decimal(f.bits),
.bool => "b",
.void => "v",
.@"enum" => |e| "e(" ++ signature(e.tag_type) ++ ":" ++ tags(T) ++ ")",
.array => |a| "[" ++ decimal(a.len) ++ "]" ++ signature(a.child),
.vector => |v| "@" ++ decimal(v.len) ++ signature(v.child),
.optional => |o| "?" ++ signature(o.child),
.@"struct" => |s| blk: {
var text: []const u8 = "s" ++ decimal(@sizeOf(T)) ++ "{";
for (s.field_names, s.field_types, s.field_attrs) |name, F, attrs| {
if (attrs.@"comptime") continue;
text = text ++ name ++ "@" ++ decimal(@offsetOf(T, name)) ++ ":" ++ signature(F) ++ ";";
}
break :blk text ++ "}";
},
.@"union" => |u| blk: {
var text: []const u8 = "u" ++ decimal(@sizeOf(T)) ++ "{";
if (u.tag_type) |tag| text = text ++ signature(tag) ++ "|";
for (u.field_names, u.field_types) |name, F| text = text ++ name ++ ":" ++ signature(F) ++ ";";
break :blk text ++ "}";
},
.pointer => |p| "*" ++ @tagName(p.size) ++ ":" ++ @typeName(p.child),
.@"opaque" => "opaque",
.@"fn" => @typeName(T),
else => @compileError("unsupported type in sketch memory: " ++ @typeName(T)),
};
}
}
test "leaves flatten structs, and arrays into element leaves" {
const Inner = extern struct { a: u8 = 0, b: enum(u8) { x, y = 5 } = .x };
const S = extern struct { inner: Inner = .{}, list: [4]f32 = @splat(0), flag: bool = false };
const l = of(S, .state);
const fields = l.fields;
try std.testing.expectEqual(5, fields.len);
try std.testing.expectEqualStrings("inner.a", std.mem.span(fields[0].path));
try std.testing.expectEqualStrings("inner.b", std.mem.span(fields[1].path));
try std.testing.expectEqualStrings("x=0,y=5", std.mem.span(fields[1].tags));
try std.testing.expectEqual(abi.Field.Kind.array, fields[2].kind);
try std.testing.expectEqualStrings("list", std.mem.span(fields[2].path));
try std.testing.expectEqual(@as(u32, 4), fields[2].offset);
try std.testing.expectEqualStrings("list[]", std.mem.span(fields[3].path));
try std.testing.expectEqual(abi.Field.Kind.float, fields[3].kind);
try std.testing.expectEqual(@as(u8, 1), fields[3].rank);
try std.testing.expectEqual(Dim{ .count = 4, .stride = 4 }, fields[3].dims[0]);
try std.testing.expect(hash([4]f32) != hash([5]f32));
try std.testing.expect(hash(enum(u8) { a }) != hash(enum(u8) { a, b }));
}
test "vector lanes and nested array elements resolve by index" {
const Boid = struct { pos: @Vector(2, f32) = @splat(0), mood: enum(u8) { calm = 1, wild = 2 } = .calm };
const S = struct { boids: struct { buffer: [8]Boid = @splat(.{}), len: u32 = 0 } = .{}, grid: [3][2]u16 = @splat(@splat(0)), mask: @Vector(4, bool) = @splat(false) };
var s: S = .{};
s.boids.buffer[3].pos[1] = 7.5;
s.grid[2][1] = 9;
const fields = of(S, .state).fields;
const bytes = std.mem.asBytes(&s);
const pos = resolve(fields, "boids.buffer[3].pos[1]").?;
try std.testing.expectEqualStrings("boids.buffer[].pos[]", std.mem.span(pos.field.path));
try std.testing.expectEqual(@as(f32, 7.5), @as(f32, @bitCast(bytes[pos.offset..][0..4].*)));
const cell = resolve(fields, "grid[2][1]").?;
try std.testing.expectEqual(@as(u16, 9), std.mem.readInt(u16, bytes[cell.offset..][0..2], .little));
try std.testing.expect(resolve(fields, "boids.buffer[8].pos[0]") == null);
try std.testing.expect(resolve(fields, "boids.buffer[1].pos[2]") == null);
try std.testing.expect(resolve(fields, "boids.buffer[].pos[0]") == null);
try std.testing.expect(resolve(fields, "boids.buffer[1]x") == null);
try std.testing.expectEqual(abi.Field.Kind.@"enum", resolve(fields, "boids.buffer[0].mood").?.field.kind);
try std.testing.expectEqual(abi.Field.Kind.bytes, resolve(fields, "mask").?.field.kind);
try std.testing.expectEqual(abi.Field.Kind.array, resolve(fields, "boids.buffer[2].pos").?.field.kind);
}
|