//! 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. //! - Store is a file mapped at the same address in every run: pointers into //! the store itself, but no host handles. const std = @import("std"); const abi = @import("abi.zig"); pub fn of(comptime T: type, comptime memory: abi.Memory) abi.Layout { return comptime blk: { @setEvalBranchQuota(1_000_000); switch (memory) { .state => check(T, "State", @typeName(T), false), .store => check(T, "Store", @typeName(T), true), .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 = std.fmt.comptimePrint("{s}", .{path}), .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 memory: []const u8, comptime path: []const u8, comptime pointers: bool) void { comptime { if (T == abi.Image or T == abi.Audio or T == abi.Buffer) @compileError(memory ++ " cannot hold host handles (" ++ path ++ "): they mean nothing to the next process. Keep them in Session."); switch (@typeInfo(T)) { // Not followed: types can point to themselves. .pointer => if (!pointers) @compileError(memory ++ " cannot hold pointers (" ++ path ++ "): it is saved to disk and outlives every address. Keep indices or offsets, or put it in Store or Session."), .array => |a| check(a.child, memory, path ++ "[]", pointers), .vector => |v| check(v.child, memory, path ++ "[]", pointers), .optional => |o| check(o.child, memory, path, pointers), .@"struct" => |s| for (s.field_names, s.field_types) |name, F| check(F, memory, path ++ "." ++ name, pointers), .@"union" => |u| for (u.field_names, u.field_types) |name, F| check(F, memory, path ++ "." ++ name, pointers), 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 ",") ++ std.fmt.comptimePrint("{s}={d}", .{ name, value }); } return std.fmt.comptimePrint("{s}", .{text}); } } /// 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)); }; } pub fn signature(comptime T: type) []const u8 { comptime { return switch (@typeInfo(T)) { .int => |i| std.fmt.comptimePrint("{c}{d}", .{ if (i.signedness == .signed) 'i' else 'u', i.bits }), .float => |f| std.fmt.comptimePrint("f{d}", .{f.bits}), .bool => "b", .void => "v", .@"enum" => |e| "e(" ++ signature(e.tag_type) ++ ":" ++ tags(T) ++ ")", .array => |a| std.fmt.comptimePrint("[{d}]", .{a.len}) ++ signature(a.child), .vector => |v| std.fmt.comptimePrint("@{d}", .{v.len}) ++ signature(v.child), .optional => |o| "?" ++ signature(o.child), .@"struct" => |s| blk: { var text: []const u8 = std.fmt.comptimePrint("s{d}{{", .{@sizeOf(T)}); for (s.field_names, s.field_types, s.field_attrs) |name, F, attrs| { if (attrs.@"comptime") continue; text = text ++ std.fmt.comptimePrint("{s}@{d}:", .{ name, @offsetOf(T, name) }) ++ signature(F) ++ ";"; } break :blk text ++ "}"; }, .@"union" => |u| blk: { var text: []const u8 = std.fmt.comptimePrint("u{d}{{", .{@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| std.fmt.comptimePrint("*{s}:{s}", .{ @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); }