tiny.mprompt.Continuation

1/// Returns the typed handle type that a `yieldWith` handler gets for the paused rest of the body,2/// for a handler that uses it to continue the paused body with its answer. `ResumeValue` is the3/// type the paused `yieldWith` call returns. `PromptResult` is the type the body's `run` returns.4/// `PromptResult` must be the `Result` of the enclosing `run`, and the compiler does not check that5/// the two match. The handler must call one of the continue methods before it returns, or the6/// program stops with a panic.7pub fn Continuation(comptime ResumeValue: type, comptime PromptResult: type) type {8    return struct {9        /// Holds the runtime's resumption for the paused body.10        raw_resume: *raw.Resume,11        /// Points to a flag in `yieldWith` that a continue method sets once the body hands control12        /// back. `yieldWith` stops the program with a panic when the handler returns and the flag13        /// is still false.14        continued: *bool,15        /// Points to where a continue method stores the runtime's result pointer. `yieldWith`16        /// returns that pointer to the call that entered the prompt.17        raw_result: *?*anyopaque,1819        const Self = @This();2021        /// Resumes the paused body so that its `yieldWith` call returns `value`, for a handler22        /// continuing the paused body with its answer and getting the body's result back. The call23        /// returns the body's result once the body runs to its end, through any later pauses that24        /// their own handlers continue. The call marks the continuation as used. A one-shot25        /// continuation is continued once. When other references of a multi-shot continuation26        /// remain, the call first copies the paused stack to the heap, and a later resume copies it27        /// back.28        pub fn continueWith(self: Self, value: ResumeValue) PromptResult {29            return self.continueInternal(false, value);30        }3132        /// Resumes the paused body with `value` as a tail resume, for a handler whose last act is33        /// to continue the body, so repeated pauses do not pile up handler frames. For a one-shot34        /// continuation, control never comes back to the handler, and the body's result goes35        /// straight to the call that entered the prompt. The call must be the handler's last36        /// action. For a multi-shot continuation, only the first tail resume works this way, and37        /// later ones behave as `continueWith` does.38        pub fn continueTailWith(self: Self, value: ResumeValue) PromptResult {39            return self.continueInternal(true, value);40        }4142        /// Continues the paused body with no value, for a `ResumeValue` of `void`. Any other43        /// `ResumeValue` is a compile error.44        pub fn continueWithoutValue(self: Self) PromptResult {45            if (ResumeValue != void) {46                @compileError("continueWithoutValue requires ResumeValue to be void");47            }48            return self.continueWith({});49        }5051        /// Continues the paused body with no value as a tail resume, for a `ResumeValue` of `void`.52        /// Any other `ResumeValue` is a compile error.53        pub fn continueTailWithoutValue(self: Self) PromptResult {54            if (ResumeValue != void) {55                @compileError("continueTailWithoutValue requires ResumeValue to be void");56            }57            return self.continueTailWith({});58        }5960        /// Returns a multi-shot continuation for the same pause, for a handler that converts the61        /// continuation before continuing the same pause more than once, as a search that tries62        /// each branch does. The handler uses the returned continuation in place of the old one.63        /// Converting a one-shot continuation allocates a record from the process allocator, and64        /// the program stops with a panic if that allocation fails. A continuation that is already65        /// multi-shot comes back unchanged. Each continue call gives up one reference, so66        /// continuing twice takes a `dup` first.67        pub fn asMulti(self: Self) Self {68            return .{69                .raw_resume = raw.resumeMulti(self.raw_resume),70                .continued = self.continued,71                .raw_result = self.raw_result,72            };73        }7475        /// A handler takes one extra reference for each extra time it will continue the pause. The76        /// call returns a second continuation for the same pause and adds one reference, or returns77        /// null for a one-shot continuation. The call copies no stack memory.78        pub fn dup(self: Self) ?Self {79            const duplicated = raw.resumeDup(self.raw_resume) orelse return null;80            return .{81                .raw_resume = duplicated,82                .continued = self.continued,83                .raw_result = self.raw_result,84            };85        }8687        /// Gives up one reference without continuing the body, for a handler giving back an extra88        /// reference it took and will not use. The handler must still continue the body through89        /// another reference before it returns, because a handler that drops its only reference and90        /// returns stops the program with a panic.91        pub fn drop(self: Self) void {92            raw.resumeDrop(self.raw_resume);93        }9495        /// Returns the number of resumes of a multi-shot continuation, or 0 for a one-shot96        /// continuation, for a handler reading how many times the pause has been continued so far.97        pub fn resumeCount(self: Self) c_long {98            return raw.resumeResumeCount(self.raw_resume);99        }100101        fn continueInternal(self: Self, comptime tail: bool, value: ResumeValue) PromptResult {102            var slot: Slot(ResumeValue) = .{};103            writeSlot(ResumeValue, &slot, value);104            const result = if (tail)105                raw.resumeTailPrompt(self.raw_resume, slotPtr(ResumeValue, &slot))106            else107                raw.resumePrompt(self.raw_resume, slotPtr(ResumeValue, &slot));108            self.continued.* = true;109            self.raw_result.* = result;110            return readSlot(PromptResult, result);111        }112    };113}

1pub const Continuation = zig_api.Continuation;