tiny.game.reload

1//! A loader that runs a game from a shared library and swaps in the rebuilt library while the host2//! keeps running.3//!4//! A developer who rebuilds the game's code wants the host to pick up the change while it keeps5//! running, with the game's state kept in the host's memory.6//!7//! A compiler writes a library file over a stretch of time, so a host that loads the file at its8//! first change can load a half-written library. Rebuilt code takes over the game state the old9//! code left in memory, so the rebuilt code has to fit that memory and agree with the host on how10//! the two call each other.11//!12//! The loader copies the library file to a new numbered file beside it (a *staged copy*) and opens13//! the copy. At each poll the loader looks at the original file, and once the file's size and14//! modification time have held still for 120 milliseconds, it stages and opens a fresh copy. Before15//! it swaps, the loader calls a function the library exports and reads back a record that describes16//! the library (a *contract*), and it checks the major interface version and the alignment of the17//! state the library needs. The loader also checks the state size against a limit18//! (`state_capacity`) that starts at the first library's state size and that a caller can set, for19//! example to the size of the state memory the host allocated. The caller fixes the largest state20//! alignment and the size bound for the library file the loader copies when it makes the loader21//! type (`Limits`). After a refusal, the old library stays loaded and the poll's result carries the22//! error, and after a swap the loader deletes the previous copy and the poll's result carries the23//! new contract.24const std = @import("std");25const sys = @import("sys");26const settle = @import("settle.zig");2728const settle_window_ns: i128 = 120 * std.time.ns_per_ms;2930/// The largest state alignment and the size bound for the library file the loader copies, fixed31/// when the loader type is made. A host picks both once for its loader type, for example an32/// alignment of 16 bytes and a file of 64 MiB. Making the loader type is a compile error when33/// either limit is zero or the alignment fails to be a power of two.34pub const Limits = struct {35    /// The largest state alignment in bytes that a library may ask for, a power of two. A host36    /// allocates its state memory at this alignment, so the state of any accepted library fits it.37    max_state_align: usize,38    /// The size bound in bytes for the library file the loader copies. A file of this size or39    /// larger is refused with `error.StreamTooLong`, so the largest accepted file is one byte40    /// smaller.41    max_library_bytes: usize,42};4344const ReloadError = sys.dynamic.LibraryError || sys.fs.ReadFileError || sys.fs.WriteFileError || std.mem.Allocator.Error || error{45    MissingContract,46    ContractTooNew,47    ContractAbiMismatch,48    InvalidStateAlignment,49    StateLayoutChanged,50};5152/// Returns a loader type for game libraries that follow the interface `Abi` describes, within53/// `limits`. A host makes one loader type for its game interface and keeps one loader for the game54/// it runs. `Abi` declares the record type `Contract`, the type of the function that fills it55/// `ContractFn`, that function's exported name `contract_symbol`, and the host's major interface56/// version `current_abi_major`. `Contract` has at least the fields `abi_major`, `state_size` and57/// `state_align`. A loader holds the open library, its contract, its staged copy, and a change58/// detector for the original file. Each staged copy's path is the original path with `.hot.` and a59/// number appended, and the first load uses 0.60pub fn Loader(comptime Abi: type, comptime limits: Limits) type {61    comptime {62        if (limits.max_state_align == 0 or !std.math.isPowerOfTwo(limits.max_state_align) or63            limits.max_library_bytes == 0) @compileError("invalid game reload limits");64    }65    return struct {66        const Dynamic = @This();67        /// Every error the loader returns: the errors of opening a library, reading the file and68        /// writing the copy, running out of memory, and five contract errors. A host names it in69        /// its own signatures and reports a refused swap by the error's name. `MissingContract`:70        /// the library exports no function by the contract name. `ContractTooNew`: the library's71        /// function returned 0 for the host's record size, which a library does when its own record72        /// is larger. `ContractAbiMismatch`: the major interface version differs from73        /// `current_abi_major`. `InvalidStateAlignment`: the state alignment is zero, fails to be a74        /// power of two, or is above `max_state_align`. `StateLayoutChanged`: a new library's state75        /// size is above `state_capacity`. `StateLayoutChanged` compares sizes alone, so a library76        /// whose state layout changes at the same or a smaller size is accepted.77        pub const Error = ReloadError;78        /// The result of one `poll`: the loader stayed idle, swapped in a rebuilt library, or79        /// refused a swap. A host switches on it after each poll, takes the new contract after a80        /// swap, and reports a refusal.81        pub const Poll = union(enum) {82            /// The loader stayed idle: the file is unchanged or still settling, or the look at its83            /// size and modification time returned an error.84            idle,85            /// The loader swapped in a rebuilt library, and the payload is its contract. The old86            /// library is closed by then, so the caller replaces every contract copy it holds with87            /// this one.88            swapped: Abi.Contract,89            /// The file settled and the swap was refused, and the payload is the error. Staging the90            /// copy, before any copy is opened, returns the errors of reading the library file,91            /// `error.StreamTooLong` for a file at the size bound or larger, `error.OutOfMemory`,92            /// and the errors of writing the copy. Opening the fresh copy returns the errors of93            /// opening a library, and reading and checking its contract returns the contract94            /// errors. The old library, its contract and its staged copy stay in place. The loader95            /// tries again only after the file changes and settles again.96            failed: ReloadError,97        };9899        allocator: std.mem.Allocator,100        source_path: []u8,101        staged_path: ?[]u8,102        lib: sys.dynamic.Library,103        /// The contract of the library that is loaded now. A host reads it after `load` for the104        /// game's functions and its state size.105        contract: Abi.Contract,106        settle: settle.Settle,107        counter: usize,108        /// The largest state size in bytes that a rebuilt library may ask for. `load` sets it to109        /// the first library's state size, and a caller can set it, for example to the size of the110        /// state memory the host allocated.111        state_capacity: usize,112113        /// Copies the library at `path` to its first staged copy, opens the copy and reads its114        /// contract. A host calls it once at startup with the path of the game's library. The115        /// loader keeps its own copy of `path` and allocates it and the staged path with116        /// `allocator`, and `deinit` frees both. The call records the file's size and modification117        /// time as the change detector's first look when it can read them. The call returns the118        /// errors of opening, reading and writing, `error.OutOfMemory`, and each contract error119        /// except `StateLayoutChanged`. On an error, the call deletes the staged copy it opened and120        /// frees what it allocated. When writing the copy fails after the copy's file exists, the121        /// partly written copy stays on disk until a later `load` of the same path writes its copy122        /// under the same name. A state size of zero is accepted, for a stateless game.123        pub fn load(allocator: std.mem.Allocator, path: []const u8) ReloadError!Dynamic {124            const source_path = try allocator.dupe(u8, path);125            errdefer allocator.free(source_path);126127            const staged = try stage(allocator, source_path, 0);128            errdefer {129                sys.fs.deleteFile(staged) catch {};130                allocator.free(staged);131            }132133            var lib = try sys.dynamic.openRuntimeFfiPlugin(staged);134            errdefer lib.close();135136            const contract = try readContract(&lib);137138            var watch = settle.Settle{};139            if (sys.fs.statFile(source_path)) |st| {140                _ = watch.observe(.{ .mtime_ns = st.mtime.nanoseconds, .size = st.size }, 0, settle_window_ns);141            } else |_| {}142143            return .{144                .allocator = allocator,145                .source_path = source_path,146                .staged_path = staged,147                .lib = lib,148                .contract = contract,149                .settle = watch,150                .counter = 1,151                .state_capacity = contract.state_size,152            };153        }154155        /// Looks at the library file and swaps in a fresh copy once the file has held still for 120156        /// milliseconds. A host calls it once per step before it runs the game's update, passing157        /// the current time in nanoseconds. A swap stages the next numbered copy, opens it, reads158        /// and checks its contract, and checks its state size against `state_capacity`. A swap then159        /// closes the old library, deletes its staged copy, and keeps the new library and contract.160        /// A refused swap deletes the new copy and leaves the old library, its contract and its161        /// staged copy in place. When writing the new copy fails after the copy's file exists, the162        /// partly written copy stays on disk until the next swap writes its copy under the same163        /// number, and `deinit` leaves it there. The result is `.idle`, `.swapped` with the new164        /// contract, or `.failed` with the error. The call returns no error of its own: a failure165        /// to read the file's size and time gives `.idle`, and a swap error gives `.failed`.166        pub fn poll(self: *Dynamic, now_ns: i128) Poll {167            const st = sys.fs.statFile(self.source_path) catch return .idle;168            if (!self.settle.observe(.{ .mtime_ns = st.mtime.nanoseconds, .size = st.size }, now_ns, settle_window_ns)) return .idle;169            const next = self.swap() catch |err| return .{ .failed = err };170            return .{ .swapped = next };171        }172173        /// Closes the library, deletes the current staged copy, frees the loader's paths, and174        /// leaves the loader undefined. A host calls it once at shutdown, after its last call into175        /// the game. The function pointers in any contract from this loader are invalid after the176        /// call.177        pub fn deinit(self: *Dynamic) void {178            self.lib.close();179            if (self.staged_path) |p| {180                sys.fs.deleteFile(p) catch {};181                self.allocator.free(p);182            }183            self.allocator.free(self.source_path);184            self.* = undefined;185        }186187        fn swap(self: *Dynamic) ReloadError!Abi.Contract {188            const staged = try stage(self.allocator, self.source_path, self.counter);189            errdefer {190                sys.fs.deleteFile(staged) catch {};191                self.allocator.free(staged);192            }193            self.counter += 1;194195            var new_lib = try sys.dynamic.openRuntimeFfiPlugin(staged);196            errdefer new_lib.close();197198            const next = try readContract(&new_lib);199            if (next.state_size > self.state_capacity) {200                return error.StateLayoutChanged;201            }202203            self.lib.close();204            if (self.staged_path) |old| {205                sys.fs.deleteFile(old) catch {};206                self.allocator.free(old);207            }208            self.lib = new_lib;209            self.staged_path = staged;210            self.contract = next;211            return next;212        }213        fn stage(allocator: std.mem.Allocator, source_path: []const u8, counter: usize) ReloadError![]u8 {214            const staged = try std.fmt.allocPrint(allocator, "{s}.hot.{d}", .{ source_path, counter });215            errdefer allocator.free(staged);216            const bytes = try sys.fs.readFileAlloc(allocator, source_path, limits.max_library_bytes);217            defer allocator.free(bytes);218            try sys.fs.writeFile(staged, bytes);219            return staged;220        }221222        fn readContract(lib: *sys.dynamic.Library) ReloadError!Abi.Contract {223            const entry = lib.lookup(Abi.ContractFn, Abi.contract_symbol) orelse return error.MissingContract;224            var contract = std.mem.zeroes(Abi.Contract);225            if (entry(&contract, @sizeOf(Abi.Contract)) == 0) return error.ContractTooNew;226            if (contract.abi_major != Abi.current_abi_major) return error.ContractAbiMismatch;227            if (contract.state_align == 0 or !std.math.isPowerOfTwo(contract.state_align) or228                contract.state_align > limits.max_state_align) return error.InvalidStateAlignment;229            return contract;230        }231    };232}

1pub const reload = @import("reload.zig");