Macro fail_point

macro_rules! fail_point {
    ($name:expr) => { ... };
    ($name:expr, $e:expr) => { ... };
    ($name:expr, $cond:expr, $e:expr) => { ... };
}

Define a fail point (requires failpoints feature).

The fail_point! macro has three forms, and they all take a name as the first argument. The simplest form takes only a name and is suitable for executing most fail point behavior, including panicking, but not for early return or conditional execution based on a local flag.

The three forms of fail points look as follows.

1. A basic fail point:

fn function_return_unit() {
    fail_point!("fail-point-1");
}

This form of fail point can be configured to panic, print, sleep, pause, etc., but not to return from the function early.

2. A fail point that may return early:

fn function_return_value() -> u64 {
    fail_point!("fail-point-2", |r| r.map_or(2, |e| e.parse().unwrap()));
    0
}

This form of fail point can additionally be configured to return early from the enclosing function. It accepts a closure, which itself accepts an Option<String>, and is expected to transform that argument into the early return value. The argument string is sourced from the fail point configuration string. For example configuring this “fail-point-2” as “return(100)” will execute the fail point closure, passing it a Some value containing a String equal to “100”; the closure then parses it into the return value.

3. A fail point with conditional execution:

fn function_conditional(enable: bool) {
    fail_point!("fail-point-3", enable, |_| {});
}

In this final form, the second argument is a local boolean expression that must evaluate to true before the fail point is evaluated. The third argument is again an early-return closure.

The three macro arguments (or “designators”) are called $name, $cond, and $e. $name must be &str, $cond must be a boolean expression, and$e must be a function or closure that accepts an Option<String> and returns the same type as the enclosing function.

For more examples see the crate documentation. For more information about controlling fail points see the cfg function.