rsaeb 0.3.0

A no_std + alloc interpreter for A=B ordered rewrite programs.
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
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

use alloc::vec::Vec;
use core::error::Error;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AllocationContext {
    /// Building the parsed program rule table.
    ProgramRules,
    /// Building a compact code-line byte table.
    CompactCodeLine,
    /// Building canonical source bytes from structured rule data.
    CanonicalSource,
    /// Storing a parsed program payload.
    Payload,
    /// Storing validated runtime input.
    RuntimeInput,
    /// Storing per-run `(once)` rule state.
    RuntimeRuleState,
    /// Building the next runtime state after a rewrite.
    RuntimeState,
    /// Materializing a borrowed runtime-state view outside trace snapshot APIs.
    RuntimeStateView,
    /// Materializing a stable final runtime state as public output bytes.
    FinalOutput,
    /// Materializing `(return)` output bytes.
    ReturnOutput,
    /// Materializing a trace snapshot.
    TraceSnapshot,
}

/// Fallible allocation failure reported instead of silently relying on
/// allocation side effects.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AllocationError {
    context: AllocationContext,
    kind: AllocationErrorKind,
}

/// Reason an allocation boundary failed.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AllocationErrorKind {
    /// The required capacity could not be represented as `usize`.
    CapacityOverflow,
    /// The allocator rejected the requested capacity.
    ReserveFailed {
        /// Vector capacity requested at the failing site.
        requested_capacity: usize,
    },
}

impl AllocationError {
    pub(crate) const fn capacity_overflow(context: AllocationContext) -> Self {
        Self {
            context,
            kind: AllocationErrorKind::CapacityOverflow,
        }
    }

    pub(crate) const fn reserve_failed(
        context: AllocationContext,
        requested_capacity: usize,
    ) -> Self {
        Self {
            context,
            kind: AllocationErrorKind::ReserveFailed { requested_capacity },
        }
    }

    /// Allocation site that failed.
    #[must_use]
    pub const fn context(&self) -> AllocationContext {
        self.context
    }

    /// Structured allocation failure reason.
    #[must_use]
    pub const fn kind(&self) -> AllocationErrorKind {
        self.kind
    }

    /// Requested vector capacity, when allocation reached the allocator.
    #[must_use]
    pub const fn requested_capacity(&self) -> Option<usize> {
        match self.kind {
            AllocationErrorKind::CapacityOverflow => None,
            AllocationErrorKind::ReserveFailed { requested_capacity } => Some(requested_capacity),
        }
    }
}

impl Error for AllocationError {}

pub(crate) fn try_reserve_total_exact<T>(
    vec: &mut Vec<T>,
    total_capacity: usize,
    context: AllocationContext,
) -> Result<(), AllocationError> {
    if vec.capacity() >= total_capacity {
        return Ok(());
    }

    let additional = total_capacity
        .checked_sub(vec.len())
        .ok_or_else(|| AllocationError::capacity_overflow(context))?;

    vec.try_reserve_exact(additional)
        .map_err(|_| AllocationError::reserve_failed(context, total_capacity))
}

pub(crate) fn try_push<T>(
    vec: &mut Vec<T>,
    value: T,
    context: AllocationContext,
) -> Result<(), AllocationError> {
    if vec.len() == vec.capacity() {
        let minimum_capacity = vec
            .len()
            .checked_add(1)
            .ok_or_else(|| AllocationError::capacity_overflow(context))?;
        let doubled_capacity = vec.capacity().checked_mul(2).unwrap_or(minimum_capacity);
        let requested_capacity =
            core::cmp::max(minimum_capacity, core::cmp::max(4, doubled_capacity));
        try_reserve_total_exact(vec, requested_capacity, context)?;
    }

    vec.push(value);
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn allocation_contexts_are_publicly_inspectable() {
        let error = AllocationError::reserve_failed(AllocationContext::TraceSnapshot, 123);
        assert_eq!(error.context(), AllocationContext::TraceSnapshot);
        assert_eq!(
            error.kind(),
            AllocationErrorKind::ReserveFailed {
                requested_capacity: 123,
            },
        );
        assert_eq!(error.requested_capacity(), Some(123));

        let error = AllocationError::capacity_overflow(AllocationContext::CanonicalSource);
        assert_eq!(error.context(), AllocationContext::CanonicalSource);
        assert_eq!(error.kind(), AllocationErrorKind::CapacityOverflow);
        assert_eq!(error.requested_capacity(), None);
    }
}