Similar to the try! macro or ? operator,
but externally controllable to inject faults
during testing. Unlike the try! macro or ?
operator, this additionally annotates the
description of the error to include the crate,
file name, and line number where the error
originated from to facilitate quick debugging.
It is specialized to work with io::Result
types, and will return an io::Error for faults,
with into() called similar to the try! macro
or ? operator.
Decrements the FAULT_INJECT_COUNTER by 1
(it is set to u64::MAX by default), and if
it hits 0, returns an io::Error with a kind
of Other. If SLEEPINESS is set to
something other than 0, this macro will also
inject weakly pseudorandom delays for
facilitating a basic form of concurrency testing.
Facilitates fault injection. Every time any IO operation
is performed, this is decremented. If it hits 0, an
io::Error is returned from that IO operation. Use this
to ensure that error handling is being performed, by
running some test workload, checking the counter, and
then setting this to an incrementally-lower number while
asserting that your application properly handles the
error that will propagate up. Defaults to u64::MAX,
so it won’t be hit normally unless you do something 6 billion
times per second for 100 years. If you’re building something
like that, maybe consider re-setting this to u64::MAX every
few decades for safety.
Facilitates delay injection. If you set this to something other
than 0, the fallible! macro will randomly call std::thread::yield_now(),
with the nubmer of times being multiplied by this value. You should not
need to set it very high to get a lot of delays, but you’ll need
to play with the number sometimes for specific concurrent systems under test.
This function will be called any time the FAULT_INJECT_COUNTER reaches 0
and an error is injected. You can use this to re-set the counter for deep
fault tree enumeration, test auditing, etc…