tiny.mprompt.EffectDefinition

1/// Returns a type for one effect so a caller declares an effect once in Zig, then performs and2/// handles its operations with checked types and no pointer casts. The type is built from a spec3/// with a `.name` string and an `.operations` struct literal whose fields are4/// `operation(Arg, Result)` values. A spec with more than eight operations is a compile error, and5/// so is an `.operations` value of any type other than a struct literal. The type builds the6/// effect's name table and one operation tag per operation at compile time, with operation names of7/// the form `name/operation`.8pub fn EffectDefinition(comptime spec: anytype) type {9    const Operations = @TypeOf(spec.operations);10    const operations_info = switch (@typeInfo(Operations)) {11        .@"struct" => |info| info,12        else => @compileError("effect operations must be a struct literal"),13    };14    const operation_names = operations_info.field_names;15    if (operation_names.len > max_operations) {16        @compileError("effect definitions support at most eight operations");17    }1819    return struct {20        /// An enum with one tag per field of `.operations`, in declaration order. `optag`,21        /// `Signature`, `Continuation`, `perform` and `performWithoutValue` take one to pick the22        /// operation.23        pub const Op: type = std.meta.FieldEnum(Operations);24        /// The number of operations in the spec.25        pub const operation_count = operation_names.len;2627        const Self = @This();2829        const names = blk: {30            var result: [operation_count + 2:null]?[*:0]const u8 = undefined;31            result[0] = spec.name;32            for (operation_names, 0..) |operation_name, index| {33                result[index + 1] = std.fmt.comptimePrint("{s}/{s}", .{ spec.name, operation_name });34            }35            result[operation_count + 1] = null;36            break :blk result;37        };3839        const tags = blk: {40            var result: [operation_count]Optag = undefined;41            for (operation_names, 0..) |_, index| {42                result[index] = .{ .effect = rawEffect(), .opidx = index };43            }44            break :blk result;45        };4647        /// Returns the effect's name table so raw calls that name this effect take it.48        pub fn rawEffect() Effect {49            return @ptrCast(&names);50        }5152        /// Returns a pointer to `op_id`'s operation tag so raw calls that perform or handle one53        /// operation take its tag. The tag's index is the operation's position in `.operations`.54        pub fn optag(comptime op_id: Op) *const Optag {55            return &tags[operationIndex(op_id)];56        }5758        /// Returns the argument type and result type of `op_id` as the spec declares them.59        pub fn Signature(comptime op_id: Op) OperationSignature {60            return @field(spec.operations, @tagName(op_id));61        }6263        /// Returns the continuation type that a clause of kind `kind` for `op_id` receives, so a64        /// continuation clause names its parameter type with it. A resume of that continuation65        /// passes a value of `op_id`'s result type into the body and returns `HandlerResult`.66        /// `HandlerResult` must be the `Result` of the `handle` call, and the compiler rejects a67        /// mismatch at the clause call site.68        pub fn Continuation(comptime op_id: Op, comptime kind: OperationKind, comptime HandlerResult: type) type {69            const sig = Signature(op_id);70            return EffectContinuation(sig.Result, HandlerResult, kind);71        }7273        /// Performs `op_id` with `arg` and returns the result the clause gives, so code under a74        /// handler asks for an operation with a typed argument and gets a typed result. The75        /// argument and the result travel in a small record on the performer's stack, and the76        /// clause reaches that record by address. Whether the call suspends the body depends on the77        /// clause's kind. With no enclosing handler for the effect, the runtime prints78        /// `lib/mpeff: unhandled operation:` and the operation's name to standard error. An79        /// operation with a non-`void` result then unwraps a null pointer, which panics in safe80        /// builds, and an operation with a `void` result returns normally.81        pub fn perform(comptime op_id: Op, arg: Signature(op_id).Arg) Signature(op_id).Result {82            const sig = Signature(op_id);83            const OpFrame = PerformFrame(sig.Arg, sig.Result);84            var frame: OpFrame = .{};85            writeSlot(sig.Arg, &frame.arg, arg);86            return readSlot(sig.Result, performRaw(optag(op_id), &frame));87        }8889        /// Performs `op_id` with no argument, for an operation whose `Arg` is `void`. Any other90        /// operation is a compile error.91        pub fn performWithoutValue(comptime op_id: Op) Signature(op_id).Result {92            const sig = Signature(op_id);93            if (sig.Arg != void) {94                @compileError("performWithoutValue requires an operation with a void argument");95            }96            return Self.perform(op_id, {});97        }9899        /// Runs `body(context)` on a new stacklet under a handler for this effect and returns a100        /// `Result`, so a caller runs a body under this effect's typed clauses and gets back the101        /// body's result, or the result a clause chose. The `context` parameter must be a pointer,102        /// and every clause that asks for it receives it. The `clauses` argument is a struct103        /// literal with one field per operation, each made by `on` or `forward()`, and a missing104        /// field is a compile error. The handler table is built at compile time. The result is the105        /// body's return value, the value an `abort` or `never` clause returns, or the value a106        /// continuation clause returns. An error union passes through as `Result`.107        pub fn handle(108            comptime Result: type,109            context: anytype,110            comptime body: *const fn (@TypeOf(context)) Result,111            comptime clauses: anytype,112        ) Result {113            const Context = @TypeOf(context);114            requirePointer(Context, "effect handler context");115            const Clauses = @TypeOf(clauses);116117            const Runner = struct {118                const Env = struct {119                    context: Context,120                    result: Slot(Result) = .{},121                };122123                fn start(arg: ?*anyopaque) callconv(.c) ?*anyopaque {124                    const env: *Env = @ptrCast(@alignCast(arg.?));125                    writeSlot(Result, &env.result, body(env.context));126                    return slotPtr(Result, &env.result);127                }128129                fn table() [max_operations]Operation {130                    var entries = @as([max_operations]Operation, @splat(.{ .opkind = .null_op, .optag = null, .opfun = null }));131                    inline for (operation_names) |operation_name| {132                        if (!hasStructField(Clauses, operation_name)) {133                            @compileError("missing handler clause for operation '" ++ operation_name ++ "'");134                        }135                        const op_id = std.meta.stringToEnum(Op, operation_name).?;136                        entries[operationIndex(op_id)] = operationEntry(op_id);137                    }138                    return entries;139                }140141                fn operationEntry(comptime op_id: Op) Operation {142                    const clause = @field(clauses, @tagName(op_id));143                    return .{144                        .opkind = clause.kind,145                        .optag = optag(op_id),146                        .opfun = switch (clause.kind) {147                            .forward => null,148                            .null_op => null,149                            else => thunk(op_id),150                        },151                    };152                }153154                fn thunk(comptime op_id: Op) OpFn {155                    return struct {156                        fn call(raw_resume: ?*Resume, local: ?*anyopaque, raw_arg: ?*anyopaque) callconv(.c) ?*anyopaque {157                            const env: *Env = @ptrCast(@alignCast(local.?));158                            const sig = Signature(op_id);159                            const OpFrame = PerformFrame(sig.Arg, sig.Result);160                            const frame: *OpFrame = @ptrCast(@alignCast(raw_arg.?));161                            const op_arg = readSlotValue(sig.Arg, &frame.arg);162                            const clause = @field(clauses, @tagName(op_id));163164                            switch (clause.kind) {165                                .tail_noop, .tail => {166                                    const op_result = callTailHandler(clause.handler, env.context, op_arg);167                                    writeSlot(sig.Result, &frame.result, op_result);168                                    return slotPtr(sig.Result, &frame.result);169                                },170                                .abort, .never => {171                                    const result = callTailHandler(clause.handler, env.context, op_arg);172                                    writeSlot(Result, &env.result, result);173                                    return slotPtr(Result, &env.result);174                                },175                                .scoped_once, .scoped, .once, .multi => {176                                    const continuation: EffectContinuation(sig.Result, Result, clause.kind) = .{177                                        .raw_resume = raw_resume.?,178                                        .local = local,179                                    };180                                    const result = callContinuationHandler(clause.handler, continuation, env.context, op_arg);181                                    writeSlot(Result, &env.result, result);182                                    return slotPtr(Result, &env.result);183                                },184                                .forward, .null_op => unreachable,185                            }186                        }187                    }.call;188                }189190                const hdef = HandlerDef{191                    .effect = rawEffect(),192                    .resultfun = null,193                    .operations = table(),194                };195            };196197            var env: Runner.Env = .{ .context = context };198            return readSlot(Result, handleRaw(&Runner.hdef, &env, Runner.start, &env));199        }200201        /// Runs a body that takes no arguments, the way `handle` does, so a caller whose body and202        /// clauses need no context skips the pointer. A clause of the `(context, arg)` form203        /// receives a pointer to an empty struct.204        pub fn handleWithoutContext(205            comptime Result: type,206            comptime body: *const fn () Result,207            comptime clauses: anytype,208        ) Result {209            const Context = struct {};210            const Runner = struct {211                fn start(_: *Context) Result {212                    return body();213                }214            };215216            var context: Context = .{};217            return Self.handle(Result, &context, Runner.start, clauses);218        }219220        fn operationIndex(comptime op_id: Op) usize {221            inline for (operation_names, 0..) |operation_name, index| {222                if (std.mem.eql(u8, operation_name, @tagName(op_id))) return index;223            }224            unreachable;225        }226    };227}

1pub const EffectDefinition = effect.EffectDefinition;