tiny.mprompt.SuspendedPrompt

1/// Returns the typed handle type for a body that paused inside a `SuspendedRun`. A caller keeps2/// this handle from the moment a run pauses until it continues or abandons the run, for example a3/// scheduler that holds one handle per waiting worker. The handle points into the `SuspendedRun`4/// that started the body, so that `SuspendedRun` must stay at the same address while the handle is5/// in use. A one-shot handle is continued once or dropped once, because continuing it again, or6/// after a drop, uses a stacklet the runtime has already freed or reused. `asMulti` turns it into a7/// multi-shot handle that the caller can continue once per reference.8pub fn SuspendedPrompt(comptime ResumeValue: type, comptime Result: type) type {9    return struct {10        /// Holds the runtime's resumption for the paused body. The methods pass it to the runtime's11        /// `resumePrompt`, `resumeDrop`, `resumeMulti`, `resumeDup` and `resumeResumeCount`.12        raw_resume: *raw.Resume,13        /// Points to the done marker inside the `SuspendedRun` that started the body.14        /// `continueWith` compares the runtime's result with this address to tell a finished body15        /// from a new pause.16        done_marker: *u8,17        /// Points to the storage inside the `SuspendedRun` where the body's wrapper writes the18        /// body's result. `continueWith` reads the result from it when the body finishes.19        result: *Slot(Result),2021        const Self = @This();22        /// Names the `PromptOutcome` type for this handle's `ResumeValue` and `Result`, which23        /// `continueWith` returns.24        pub const Outcome: type = PromptOutcome(ResumeValue, Result);2526        /// Resumes the paused body so that its `suspendPrompt` call returns `value`, for a caller27        /// continuing the body with the value the pause is waiting for. The call runs the body on28        /// its stacklet until it finishes or pauses again. The call returns `.returned` with the29        /// body's result when the body finished, or `.suspended` with a new handle when it paused30        /// again. The call uses up a one-shot handle, and a later pause comes back as a new handle31        /// in `.suspended`. The call gives up one reference of a multi-shot handle. When other32        /// references of a multi-shot handle remain, the call first copies the paused stack to the33        /// heap, and a later resume copies it back.34        pub fn continueWith(self: Self, value: ResumeValue) Outcome {35            var slot: Slot(ResumeValue) = .{};36            writeSlot(ResumeValue, &slot, value);37            const raw_result = raw.resumePrompt(self.raw_resume, slotPtr(ResumeValue, &slot));38            return outcomeFromRaw(ResumeValue, Result, raw_result, self.done_marker, self.result);39        }4041        /// Continues the paused body with no value, for a `ResumeValue` of `void`. Any other42        /// `ResumeValue` is a compile error.43        pub fn continueWithoutValue(self: Self) Outcome {44            if (ResumeValue != void) {45                @compileError("continueWithoutValue requires ResumeValue to be void");46            }47            return self.continueWith({});48        }4950        /// Returns a multi-shot handle for the same pause, for a caller that converts the handle51        /// before continuing the same pause more than once. The caller uses the returned handle in52        /// place of the old one. Converting a one-shot handle allocates a record from the process53        /// allocator, and the record starts with one reference. The program stops with a panic if54        /// that allocation fails. A handle that is already multi-shot comes back unchanged.55        pub fn asMulti(self: Self) Self {56            return .{57                .raw_resume = raw.resumeMulti(self.raw_resume),58                .done_marker = self.done_marker,59                .result = self.result,60            };61        }6263        /// A caller takes one extra reference for each extra time it will continue the pause. The64        /// call returns a second handle for the same pause and adds one reference, or returns null65        /// for a one-shot handle. The call copies no stack memory. The runtime copies the paused66        /// stack only when a resume finds other references still held.67        pub fn dup(self: Self) ?Self {68            const duplicated = raw.resumeDup(self.raw_resume) orelse return null;69            return .{70                .raw_resume = duplicated,71                .done_marker = self.done_marker,72                .result = self.result,73            };74        }7576        /// Gives up this handle without continuing the body, for a caller abandoning a paused body77        /// it will never continue, as the Chic host does when it tears down a turn. For a one-shot78        /// handle, and for the last reference of a multi-shot handle, the runtime frees the paused79        /// stacklets, and the rest of the body never runs, so its `defer` statements never run80        /// either.81        pub fn drop(self: Self) void {82            raw.resumeDrop(self.raw_resume);83        }8485        /// Returns the number of resumes of a multi-shot handle, or 0 for a one-shot handle, for a86        /// caller reading how many times the pause has been continued so far.87        pub fn resumeCount(self: Self) c_long {88            return raw.resumeResumeCount(self.raw_resume);89        }90    };91}

1pub const SuspendedPrompt = zig_api.SuspendedPrompt;