macroonz-harness 0.2.0

Safe-Rust property, fuzz, fault, schedule, mutation, network, and benchmark testing with typed evidence, reduction, and replay.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

//! The declared clock, the readings it produces, and why a reading can fail.

#[path = "type_guard.rs"]
mod guard;

/// What a caller declared: a reader, or nothing at all.
#[derive(Debug, Clone, Copy)]
pub(in crate::clock) enum Source {
    /// The caller declared no wall source.
    Unavailable,
    /// The caller declared this reading function.
    Available(Reader),
}

/// The two shapes a caller's reading function may take.
#[derive(Debug, Clone, Copy)]
pub(in crate::clock) enum Reader {
    /// A source that states one reading directly.
    Infallible(fn() -> u64),
    /// A source that may refuse one read.
    Fallible(fn() -> Result<u64, ClockReadRefusal>),
}

/// The wall-measurement source a caller declares for one run.
///
/// The source is either an infallible or fallible capture-free function pointer, or declared unavailability.
/// A function pointer excludes captured state and establishes neither purity, monotonicity, termination, nor abort safety.
#[derive(Debug, Clone, Copy)]
pub struct HarnessClock {
    pub(in crate::clock) source: Source,
}

/// An open measurement, finishable exactly once and only against the source it opened on.
///
/// Its opening and retained source are private, and [`MeasurementStart::finish`] consumes the value.
/// An outside caller therefore cannot replace the source, reverse the readings, or publish two readings from one opening.
#[must_use = "a measurement start must be finished to produce its reading"]
#[derive(Debug)]
pub struct MeasurementStart {
    pub(in crate::clock) opening: Opening,
}

/// What an opening left behind, including the reader a successful one retained.
#[derive(Debug)]
pub(in crate::clock) enum Opening {
    /// No measurement source was declared.
    Unavailable,
    /// The opening read failed.
    Failed(ClockFailure),
    /// The opening retained the source and its admitted tick.
    Opened {
        /// The exact source that must close the measurement.
        reader: Reader,
        /// The admitted opening tick.
        tick: MeasurementTick,
    },
}

/// One admitted reading in nanoseconds, on the caller source's own origin.
///
/// A tick is not a duration.
/// Only [`MeasurementStart::finish`](crate::clock::MeasurementStart::finish) turns two of them into one.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct MeasurementTick(u64);

/// One observed elapsed duration in nanoseconds.
///
/// Zero is a real observation and never spells unavailable measurement.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct RecordedDuration(u64);

/// A fallible caller source's stated read failure.
#[must_use = "a refusal is the caller source's stated read failure"]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ClockReadRefusal {
    /// The source produced no reading.
    Refused,
}

/// Why an offered measurement produced no duration.
#[must_use = "a failure is why an offered measurement produced no duration"]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ClockFailure {
    /// The opening read returned a typed refusal.
    OpeningRefused,
    /// The closing read returned a typed refusal.
    ClosingRefused,
    /// The opening read unwound.
    OpeningUnwound,
    /// The closing read unwound.
    ClosingUnwound,
    /// The closing tick preceded the opening tick on the same source.
    Regressed {
        /// The admitted opening tick.
        opened: MeasurementTick,
        /// The admitted closing tick.
        closed: MeasurementTick,
    },
}

/// The complete wall reading one run leaves in its report.
///
/// Observed zero, declared unavailability, and failure are distinct postures.
/// A failure retains its read boundary or both backwards ticks through [`ClockFailure`].
#[must_use = "a measurement reading is a report fact"]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum MeasurementReading {
    /// Both ticks were admitted in order, and this is their checked difference.
    Observed(RecordedDuration),
    /// The caller declared no clock for this run.
    Unavailable,
    /// A clock was offered and the measurement did not complete.
    Failed(ClockFailure),
}