tiny.accy.tensor.session

1/// A caller reads these descriptors to size and type the buffers it passes to a run: the value2/// gives the element type, axes, byte length and required alignment of one input or output. `dims`3/// points into the compiled program's own types and stays valid until that program is released.4pub const Descriptor = struct {5    dtype: tensor.DType,6    dims: []const tensor.Dim,7    byte_size: usize,8    alignment: u32,9};

1/// A caller matches on these to handle session failures: the set lists every failure a session call2/// can return. Each failure maps to exactly one stable status number.3pub const Error = error{4    InvalidProgram,5    UnsupportedVersion,6    InvalidHandle,7    InvalidBuffer,8    TooManyPrograms,9    OutOfMemory,10    CompileFailed,11    LaunchFailed,12};

1/// A caller keeps this handle to name one compiled program in later calls by slot index and2/// generation count. `Session.release` changes the slot's generation, so every copy of the old3/// handle is refused with `error.InvalidHandle` from then on.4pub const Handle = struct {5    index: u32,6    generation: u32,7};

1/// A host creates a session to compile tensor programs for the CPU backend inside this process and2/// run them on memory it supplies. The session runs programs forward only, with no transform that3/// computes derivatives.4pub const Session = struct {5    allocator: std.mem.Allocator,6    cpu: *CpuState,7    entries: [max_programs]Entry = @splat(.{}),8    /// A caller reads this field to log why the last failing call failed: the field holds the inner9    /// error behind the most recent failure that went through the session's error mapping, and it10    /// is for diagnostics only. Failures returned directly, such as a full table, a stale handle, a11    /// buffer count mismatch or a failed allocation while describing buffers, leave it unchanged.12    last_cause: ?anyerror = null,1314    pub fn init(allocator: std.mem.Allocator) Error!Session {15        const cpu = allocator.create(CpuState) catch return error.OutOfMemory;16        cpu.* = CpuState.init(allocator);17        return .{ .allocator = allocator, .cpu = cpu };18    }1920    pub fn deinit(self: *Session) void {21        for (&self.entries) |*entry| {22            if (entry.live) self.releaseEntry(entry);23        }24        self.cpu.deinit();25        self.allocator.destroy(self.cpu);26        self.* = undefined;27    }2829    /// A caller passes a program's wire bytes, the versioned byte encoding of a tensor program, to30    /// get a handle it can run. The call decodes the bytes, compiles the program for the CPU, and31    /// loads the result into a free slot. Bad bytes return `error.InvalidProgram` or32    /// `error.UnsupportedVersion`, a compile or load failure returns `error.CompileFailed` or33    /// `error.OutOfMemory`, and a full table returns `error.TooManyPrograms`. The caller may free34    /// `bytes` once the call returns, because decoding copies names and payloads into the program.35    pub fn compile(self: *Session, bytes: []const u8) Error!Handle {36        const index = self.freeIndex() orelse return error.TooManyPrograms;37        var program = tensor.wire.decode(self.allocator, bytes) catch |err| {38            return self.fail(decodeError(err), err);39        };40        errdefer program.deinit();41        const cpu = self.cpu.handle();42        const options = accy.executable.FragmentCompilerOptions{ .artifact_format = .cpu_object };43        const compiled = tensor.lower.compileFragment(44            self.allocator,45            cpu,46            &program,47            options,48        ) catch |err| return self.fail(compileError(err), err);49        const fragment = accy.executable.loadFragment(50            self.allocator,51            cpu,52            compiled,53            options,54        ) catch |err| return self.fail(compileError(err), err);55        errdefer fragment.deinit();56        const capabilities = cpu.queryCapabilities() catch |err| {57            return self.fail(compileError(err), err);58        };59        const min_alignment = capabilities.memory.min_buffer_alignment;60        const artifact_plan = compiled.artifactPlan();61        const descriptors = try describe(self.allocator, &program, artifact_plan, min_alignment);62        std.debug.assert(descriptors.len == program.parameters.len + program.outputs.len);6364        const entry = &self.entries[index];65        std.debug.assert(!entry.live);66        entry.* = .{67            .live = true,68            .generation = entry.generation,69            .program = program,70            .compiled = compiled,71            .fragment = fragment,72            .descriptors = descriptors,73            .input_count = program.parameters.len,74        };75        return .{ .index = index, .generation = entry.generation };76    }7778    pub fn inputDescriptors(self: *const Session, handle: Handle) Error![]const Descriptor {79        const entry = &self.entries[try self.indexOf(handle)];80        return entry.descriptors[0..entry.input_count];81    }8283    pub fn outputDescriptors(self: *const Session, handle: Handle) Error![]const Descriptor {84        const entry = &self.entries[try self.indexOf(handle)];85        return entry.descriptors[entry.input_count..];86    }8788    /// A caller runs a compiled program on its own input and output buffers. The input and output89    /// slices follow the program's descriptors in order, and a count that does not match returns90    /// `error.InvalidBuffer`. The run uses the caller's buffers in place wherever the plans allow,91    /// and copies any input the program writes so the caller's inputs stay unchanged. Each output92    /// must share no bytes with any input or with another output, and a buffer that breaks this or93    /// the descriptor's size or alignment returns `error.InvalidBuffer`. `scratch` backs the94    /// short-lived state of one launch, and a launch failure returns `error.LaunchFailed`.95    pub fn invoke(96        self: *Session,97        handle: Handle,98        scratch: std.mem.Allocator,99        input_bytes: []const []const u8,100        output_bytes: []const []u8,101    ) Error!void {102        const entry = &self.entries[try self.indexOf(handle)];103        std.debug.assert(entry.live);104        const output_count = entry.descriptors.len - entry.input_count;105        if (input_bytes.len != entry.input_count) return error.InvalidBuffer;106        if (output_bytes.len != output_count) return error.InvalidBuffer;107        const bindings = binding.prepareBorrowed(108            self.allocator,109            self.cpu.handle(),110            entry.compiled.artifactPlan(),111            entry.compiled.launchPlan(),112            input_bytes,113            output_bytes,114        ) catch |err| return self.fail(bindError(err), err);115        defer bindings.deinit();116        entry.fragment.submitInvocationWithOptions(scratch, bindings, .{}) catch |err| {117            return self.fail(launchError(err), err);118        };119        entry.fragment.completeInvocationWithOptions(.{}) catch |err| {120            return self.fail(launchError(err), err);121        };122        binding.completeBorrowed(bindings, output_bytes) catch |err| {123            return self.fail(launchError(err), err);124        };125    }126127    /// Frees the compiled program, its descriptors and its decoded form. After the call the handle128    /// and every descriptor slice from that program are invalid, and the handle is refused with129    /// `error.InvalidHandle`.130    pub fn release(self: *Session, handle: Handle) Error!void {131        const entry = &self.entries[try self.indexOf(handle)];132        self.releaseEntry(entry);133    }134135    fn releaseEntry(self: *Session, entry: *Entry) void {136        std.debug.assert(entry.live);137        entry.fragment.deinit();138        self.allocator.free(entry.descriptors);139        entry.program.deinit();140        entry.* = .{ .generation = entry.generation +% 1 };141    }142143    fn indexOf(self: *const Session, handle: Handle) Error!u32 {144        if (handle.index >= max_programs) return error.InvalidHandle;145        const entry = &self.entries[handle.index];146        if (!entry.live or entry.generation != handle.generation) return error.InvalidHandle;147        return handle.index;148    }149150    fn freeIndex(self: *const Session) ?u32 {151        for (&self.entries, 0..) |*entry, index| {152            if (!entry.live) return @intCast(index);153        }154        return null;155    }156157    fn fail(self: *Session, public: Error, cause: anyerror) Error {158        self.last_cause = cause;159        return public;160    }161};

1/// A host sends these numbers to report failures across a language boundary: the codes run from 02/// for success to 8 for a failed launch. Once a number is assigned it keeps its meaning for good.3pub const Status = enum(u32) {4    ok = 0,5    invalid_program = 1,6    unsupported_version = 2,7    invalid_handle = 3,8    invalid_buffer = 4,9    too_many_programs = 5,10    out_of_memory = 6,11    compile_failed = 7,12    launch_failed = 8,1314    pub fn fromError(err: Error) Status {15        return switch (err) {16            error.InvalidProgram => .invalid_program,17            error.UnsupportedVersion => .unsupported_version,18            error.InvalidHandle => .invalid_handle,19            error.InvalidBuffer => .invalid_buffer,20            error.TooManyPrograms => .too_many_programs,21            error.OutOfMemory => .out_of_memory,22            error.CompileFailed => .compile_failed,23            error.LaunchFailed => .launch_failed,24        };25    }26};

1/// A caller sizes its bookkeeping by this bound on programs held at once: one session holds at most2/// 64 compiled programs at a time. Compiling another program while all 64 are held returns3/// `error.TooManyPrograms`.4pub const max_programs: u32 = 64;

1pub const session = @import("session/root.zig");

1//! A way to compile tensor programs for the host CPU inside the calling process and run them2//! directly on memory the caller supplies. A host program, possibly written in another language,3//! needs to compile and run array programs through a few calls and report failures across a4//! language boundary as plain numbers. A host that hands over large buffers wants them used in5//! place on every run. Host code can keep a program's name after it released the program, and a6//! reused slot would then run the wrong program.7//!8//! A table inside the host process (*session*) holds up to 64 compiled programs, which arrive as9//! versioned bytes and run on the CPU backend. Each compiled program is named by its slot and a10//! generation count that changes on release (*handle*), so a name kept past release is refused.11//! Runs use the caller's buffers in place wherever the plans allow, and inputs the program writes12//! are copied first so the caller's inputs stay unchanged. Every failure maps to one fixed number13//! that never changes meaning (*status code*).14//!15//! - *descriptor*: the element type, axes, byte length and alignment of one program input or16//!   output.17const session = @import("session.zig");1819pub const Session = session.Session;20pub const Handle = session.Handle;21pub const Descriptor = session.Descriptor;22pub const Error = session.Error;23pub const Status = session.Status;24pub const max_programs = session.max_programs;