tiny.mprompt.EffectContinuation

1/// Returns the continuation type for clause kinds `scoped_once`, `scoped`, `once` and `multi`, so a2/// typed clause that may keep the body waiting receives one and resumes the body with the3/// operation's result. Any other kind is a compile error. `ResumeValue` is the operation's result4/// type, which `perform` returns in the body. `HandlerResult` is the result type of the `handle`5/// call. A resume returns when the resumed body finishes, with the body's result, or when a later6/// clause suspends the body and returns, with that clause's result. A `scoped_once` or `once`7/// continuation is resumed at most once, and a `scoped` or `multi` continuation is resumed any8/// number of times, with its last resume final. A `scoped`, `once` or `multi` continuation that9/// gets no final resume and no release stays allocated.10pub fn EffectContinuation(comptime ResumeValue: type, comptime HandlerResult: type, comptime kind: OperationKind) type {11    comptime {12        switch (kind) {13            .scoped_once, .scoped, .once, .multi => {},14            else => @compileError("effect continuations are only available for scoped_once, scoped, once, and multi operations"),15        }16    }1718    return struct {19        /// The raw resumption for the suspended body.20        raw_resume: *Resume,21        /// The handler's local state, passed back with each resume. The typed `handle` sets it to22        /// the address of its own environment, which holds the context and the result.23        local: ?*anyopaque,2425        const Self = @This();2627        /// Resumes the body with `value` as the result of its `perform` and returns the handler's28        /// result, for every resume but the last in a clause that resumes the body more than once,29        /// as a search over both branches of a choice does. A `scoped` or `multi` continuation30        /// stays usable for another resume. This call is the one resume for a `scoped_once`31        /// continuation. A `once` continuation is a compile error here, and it uses32        /// `continueFinalWith` or `continueTailWith`.33        pub fn continueWith(self: Self, value: ResumeValue) HandlerResult {34            if (kind == .once) {35                @compileError("once continuations must use continueFinalWith or continueTailWith");36            }37            return self.continueInternal(.regular, value);38        }3940        /// Resumes the body with `value` as the result of its `perform` and returns the handler's41        /// result, so a clause makes its last resume of the body. This call is the continuation's42        /// last resume: it frees an allocated continuation, which no caller uses again.43        pub fn continueFinalWith(self: Self, value: ResumeValue) HandlerResult {44            return self.continueInternal(.final, value);45        }4647        /// Resumes the body with `value` as a tail resume and frees an allocated continuation, for48        /// a clause whose last act is to resume the body, so no clause frame stays under the49        /// resumed body. For every kind this type allows, control does not come back to the clause,50        /// and the result goes to the call that entered or last resumed the handled body. The call51        /// must be the clause's last action.52        pub fn continueTailWith(self: Self, value: ResumeValue) HandlerResult {53            return self.continueInternal(.tail, value);54        }5556        /// Resumes the body with no value, for a `ResumeValue` of `void`. Any other `ResumeValue`57        /// is a compile error.58        pub fn continueWithoutValue(self: Self) HandlerResult {59            if (ResumeValue != void) {60                @compileError("continueWithoutValue requires ResumeValue to be void");61            }62            return self.continueWith({});63        }6465        /// Makes the final resume with no value, for a `ResumeValue` of `void`. Any other66        /// `ResumeValue` is a compile error.67        pub fn continueFinalWithoutValue(self: Self) HandlerResult {68            if (ResumeValue != void) {69                @compileError("continueFinalWithoutValue requires ResumeValue to be void");70            }71            return self.continueFinalWith({});72        }7374        /// Makes a tail resume with no value, for a `ResumeValue` of `void`. Any other75        /// `ResumeValue` is a compile error.76        pub fn continueTailWithoutValue(self: Self) HandlerResult {77            if (ResumeValue != void) {78                @compileError("continueTailWithoutValue requires ResumeValue to be void");79            }80            return self.continueTailWith({});81        }8283        /// Ends the suspended body without running its rest, for a clause that will not continue84        /// the body, such as a failing branch of a search. The body is resumed only to jump back to85        /// its handler, and its stacklet is freed. For a `multi` or `scoped` continuation that86        /// other references share, or that has resumed before, the call gives up one reference and87        /// resumes nothing. The call is valid for `scoped`, `once` and `multi` continuations, and88        /// any other kind is a compile error. A `finally` call inside the ended body never calls89        /// its `finally_fun` function.90        pub fn release(self: Self) void {91            switch (kind) {92                .scoped, .once, .multi => {},93                else => @compileError("release is only valid for scoped, once, and multi continuations"),94            }95            resumeRelease(self.raw_resume);96        }9798        fn continueInternal(self: Self, comptime continue_kind: ContinueKind, value: ResumeValue) HandlerResult {99            var slot: Slot(ResumeValue) = .{};100            writeSlot(ResumeValue, &slot, value);101            const result = switch (continue_kind) {102                .regular => resumeEffect(self.raw_resume, self.local, slotPtr(ResumeValue, &slot)),103                .final => resumeFinal(self.raw_resume, self.local, slotPtr(ResumeValue, &slot)),104                .tail => resumeTail(self.raw_resume, self.local, slotPtr(ResumeValue, &slot)),105            };106            return readSlot(HandlerResult, result);107        }108    };109}

1pub const EffectContinuation = effect.EffectContinuation;