tiny.mprompt.SuspendedRun

1/// Returns a struct type that holds a context pointer, storage for the body's result, and a done2/// marker, for a caller that starts a body that may pause and hand control back, then continues it3/// later from its own loop, as a scheduler does with workers or the Chic host does with an4/// interpreter turn. `Context` must be a pointer type, and any other type is a compile error.5/// `init(context)` builds the value, and `start(body)` runs `body(prompt, context)` on a new6/// stacklet and returns a `PromptOutcome`. The body pauses with `suspendPrompt`, and the pause7/// comes back to the caller as `.suspended`. The value must stay at one address from `start` until8/// the body finishes or its last handle is dropped, because every handle points to its result9/// storage and done marker. A caller may call `start` again after the previous run finished, as the10/// scheduler test does with one value per worker.11pub fn SuspendedRun(12    comptime ResumeValue: type,13    comptime Result: type,14    comptime Context: type,15) type {16    requirePointer(Context, "SuspendedRun context");17    return struct {18        /// The pointer passed to `init`, which `start` hands to the body.19        context: Context,20        /// Storage where the body's wrapper writes the body's result when the body finishes. A21        /// handle from this run reads the result from it. The default is empty storage, whose value22        /// stays undefined until the body returns.23        result: Slot(Result) = .{},24        /// The done marker: a byte whose address the body's wrapper returns when the body finishes.25        /// `start` and each handle compare the runtime's result with this address to tell a26        /// finished body from a pause. Only its address is used, and its value stays at the27        /// default 0.28        done_marker: u8 = 0,2930        const Self = @This();31        /// Names the `PromptOutcome` type for this run's `ResumeValue` and `Result`, which `start`32        /// returns.33        pub const Outcome: type = PromptOutcome(ResumeValue, Result);3435        /// Returns a run holding `context`, with empty result storage and the done marker at 0, for36        /// a caller that builds the run once before starting the body. The call allocates nothing37        /// and starts nothing.38        pub fn init(context: Context) Self {39            return .{ .context = context };40        }4142        /// Creates a prompt with a new stacklet and runs `body(prompt, context)` on it, for a43        /// caller that begins the body and learns whether it finished at once or paused. The call44        /// returns `.returned` with the body's result when the body finishes without pausing, or45        /// `.suspended` with a handle when it pauses through `suspendPrompt`. `self` must stay at46        /// the same address while any handle from this run is in use.47        pub fn start(48            self: *Self,49            comptime body: *const fn (*Prompt, Context) Result,50        ) Outcome {51            const Callback: type = SuspendedRunStartCallbackType(Self, Result, body);52            const raw_result = raw.prompt(Callback.run, self);53            return outcomeFromRaw(54                ResumeValue,55                Result,56                raw_result,57                &self.done_marker,58                &self.result,59            );60        }61    };62}

1pub const SuspendedRun = zig_api.SuspendedRun;