tiny.tripwire.module

1/// Creates a failpoint module at compile time for the failpoint enum `P` and2/// the error specification `E`: the namespace that holds one group of named3/// check sites.4///5/// - `P` is an enum whose fields name the check sites.6/// - `E` is one of four things: an error set type such as `anyerror` or7///   `error{...}`, an error union type such as `E!T`, a function type whose8///   return is an error union such as `fn (...) E!T`, or a function value that9///   declares such a return. An error value such as `error.OutOfMemory` does10///   not work as `E`, because the error set case hands `E` straight back and11///   the result has to be a type.12///13/// Every caller naming the same `P` and `E` shares one state map, which belongs14/// to the returned type, so no instance of the returned type carries the state.15/// Nothing synchronizes the state across threads.16pub fn module(17    comptime P: type,18    comptime E: anytype,19) type {20    return struct {21        /// The enum type whose tags name the check sites of this failpoint22        /// module, named here so a caller can write out the type that other23        /// functions take.24        pub const FailPoint: type = P;2526        /// The error set read out of the error specification at compile time,27        /// which `check` returns so a caller can match an enclosing function's28        /// error set against it.29        pub const Error: type = err: {30            const T = if (@TypeOf(E) == type) E else @TypeOf(E);31            break :err switch (@typeInfo(T)) {32                .error_set => E,33                .error_union => |info| info.error_set,34                .@"fn" => |info| @typeInfo(info.return_type.?).error_union.error_set,35                else => @compileError("E must be an error set or function type"),36            };37        };3839        /// The compile-time flag that turns the checks on, true in a test build40        /// and false everywhere else.41        pub const enabled = builtin.is_test;4243        comptime {44            assert(@typeInfo(FailPoint) == .@"enum");45            assert(@typeInfo(Error) == .error_set);46        }4748        var tripwires: TripwireMap = .{};4950        const TripwireMap: type = std.EnumMap(FailPoint, Tripwire);51        const Tripwire: type = TripwireType(Error);5253        /// Evaluates the check site named by `point` inside an operation where54        /// a simulated error should arrive, so a test can drive the error path55        /// that a successful run leaves alone.56        ///57        /// - Where `enabled` is false, meaning `builtin.is_test == false`, the58        ///   call is an inlined no-op that returns `void`.59        /// - In a test build, the call returns `void` when `point` has no60        ///   configuration or while the visit count stands at or below the61        ///   threshold. Once the visit count passes the threshold, the site is62        ///   marked tripped and the configured error is returned. The error63        ///   comes back on every later visit as well, as long as the visit64        ///   count stays inside `usize` range.65        pub fn check(point: FailPoint) callconv(callingConvention()) Error!void {66            if (comptime !enabled) return;67            return checkConstrained(point, Error);68        }6970        /// Evaluates the check site named by `point` and returns an error typed71        /// as `ConstrainedError`, letting the check sit inside a function whose72        /// declared error set is wider than the module's own.73        ///74        /// - Where `enabled` is false, the call is an inlined no-op that75        ///   returns `void`.76        /// - In a test build, it follows the same visit count and threshold77        ///   rules as `check`.78        /// - The typing requirement in a test build comes from the body: it79        ///   runs `return tripwire.err;`, and that value has type `Error`. Zig80        ///   coerces an error set only into a set that holds it, so81        ///   `ConstrainedError` has to be `Error` or a superset of `Error`.82        pub fn checkConstrained(83            point: FailPoint,84            comptime ConstrainedError: type,85        ) callconv(callingConvention()) ConstrainedError!void {86            if (comptime !enabled) return;87            const tripwire = tripwires.getPtr(point) orelse return;88            tripwire.reached += 1;89            if (tripwire.reached <= tripwire.min) return;90            tripwire.tripped = true;91            return tripwire.err;92        }9394        /// Provides the one-line setup for a test that wants the site to fail95        /// the first time an operation reaches it, configuring `point` to96        /// deliver `err` on its first visit, which is a threshold of 0. The97        /// call replaces whatever configuration `point` already had, putting98        /// the visit count back to 0 and the trip flag back to false. In a test99        /// build, later calls to `check(point)` follow the visit count rules100        /// written on `check`.101        pub fn errorAlways(point: FailPoint, err: Error) void {102            errorAfter(point, err, 0);103        }104105        /// Lets earlier visits through when an operation reaches the same site106        /// more than once before reaching the state the test targets, for107        /// example while parsing earlier records or running earlier loop108        /// iterations. The function configures `point` to pass its first `min`109        /// visits and to deliver `err` on visit `min + 1` and on every visit110        /// after that. This registration replaces whatever configuration111        /// `point` already had, putting the visit count back to 0 and the trip112        /// flag back to false. In a test build, later calls to `check(point)`113        /// follow the visit count rules written on `check`.114        pub fn errorAfter(point: FailPoint, err: Error, min: usize) void {115            tripwires.put(point, .{ .err = err, .min = min });116        }117118        /// Settles whether a test reached its configured sites, because a119        /// passing test proves its error path only once the site is known to120        /// have been reached. The function verifies that every configured site121        /// in the failpoint module was visited past its threshold and tripped.122        ///123        /// - With no site configured, it succeeds at once.124        /// - With any configured site still untripped, it returns125        ///   `error.UntrippedError`.126        /// - Under `.reset`, it clears every configured site, including on the127        ///   run that returns the error.128        /// - Under `.retain`, it keeps the registrations and the counters, so129        ///   the trip flags stay set and a later call passes with no further130        ///   visits in between.131        ///132        /// The call proves that the configured error was delivered at the check133        /// site. Whether the caller caught the error, ran its cleanup, or held134        /// its domain invariants is left to the test's own assertions.135        pub fn end(reset_mode: enum { reset, retain }) error{UntrippedError}!void {136            var untripped = false;137            var iter = tripwires.iterator();138            while (iter.next()) |entry| {139                if (!entry.value.tripped) {140                    untripped = true;141                }142            }143144            switch (reset_mode) {145                .reset => reset(),146                .retain => {},147            }148149            if (untripped) return error.UntrippedError;150        }151152        /// Clears every failpoint registration and the counters behind them. A153        /// test calls it before it starts and again on the way out, because154        /// that state belongs to the type and outlives any one test.155        pub fn reset() void {156            tripwires = .{};157        }158159        fn callingConvention() std.builtin.CallingConvention {160            return if (!enabled) .@"inline" else .auto;161        }162    };163}

1/// Creates a failpoint module at compile time for a given failpoint enum and2/// error specification.3pub const module = failpoint.module;