pipecircuit 0.0.18

Correct. Robust. Fast. Portable. Pick four.
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

//! Owned questions and mutation intents. Evaluation belongs to the owner;
//! neither a query nor a command contains a borrow into a previous answer.
use super::{
    Authority, Change, Error, Guarantee, OperationId, PersistentRow, ReadOutcome, ReadRequest,
    Revision,
};
use crate::StepInputOf;
use crate::storage::warp_table::WarpTable;
use alloc::vec::Vec;

/// A program's closed table vocabulary. Implementations must be deterministic
/// functions of their arguments, with no shared interior mutation or I/O.
/// The schema identifies both the command representation and its meaning.
pub trait TableProtocol<Row: PersistentRow> {
    const SCHEMA: [u8; 16];
    const VERSION: u32;
    type Query;
    type Value;
    type Mutation;
    type Outcome;
    type Refusal;

    fn query(query: &Self::Query, table: &WarpTable<Row>) -> Result<Self::Value, Self::Refusal>;

    /// Prepare one atomic operation against the current authoritative state.
    /// No change is published unless the entire preparation and admission pass.
    /// A domain refusal discards all prepared changes and retains the refusal.
    fn prepare(
        command: &Self::Mutation,
        table: &WarpTable<Row>,
        changes: &mut ChangeSet<Row>,
    ) -> Result<Self::Outcome, Self::Refusal>;
}

/// One synchronous preparation turn. The physical adapter encodes the retained
/// result before submission; the internal expected revision prevents publication
/// if another mutation has executed between preparation and submission.
pub struct PrepareCommand<'a, Row: PersistentRow, P: TableProtocol<Row>> {
    pub operation: OperationId,
    pub guarantee: Guarantee,
    pub command: &'a P::Mutation,
}
pub struct PreparedCommand<Row: PersistentRow, Outcome, Refusal> {
    pub expected: Revision,
    pub changes: Vec<Change<Row, Row::Id>>,
    pub outcome: Result<Outcome, Refusal>,
}
impl<Row: PersistentRow, P: TableProtocol<Row>> StepInputOf<Authority<Row>>
    for PrepareCommand<'_, Row, P>
{
    type Outcome = Result<PreparedCommand<Row, P::Outcome, P::Refusal>, Error>;
    fn step(self, machine: &mut Authority<Row>) -> Self::Outcome {
        machine.admit_command(self.operation, self.guarantee)?;
        let mut changes = ChangeSet::new(machine.limits().changes)?;
        let table = match machine.read(ReadRequest {
            guarantee: Guarantee::Accepted,
        }) {
            ReadOutcome::Ready { table, .. } => table,
            ReadOutcome::Pending => return Err(Error::Busy),
            ReadOutcome::Refused(error) => return Err(error),
        };
        let outcome = P::prepare(self.command, table, &mut changes);
        let mut changes = changes.finish()?;
        if outcome.is_err() {
            changes.clear();
        }
        Ok(PreparedCommand {
            expected: machine.revision(),
            changes,
            outcome,
        })
    }
}

/// Bounded staging owned by one command preparation. Successful submission
/// transfers its allocation into the retained operation record.
pub struct ChangeSet<Row: PersistentRow> {
    changes: Vec<Change<Row, Row::Id>>,
    limit: usize,
    refused: bool,
}
impl<Row: PersistentRow> ChangeSet<Row> {
    pub fn new(limit: usize) -> Result<Self, Error> {
        if limit == 0 {
            return Err(Error::InvalidBounds);
        }
        let mut changes = Vec::new();
        changes
            .try_reserve_exact(limit)
            .map_err(|_| Error::Allocation)?;
        Ok(Self {
            changes,
            limit,
            refused: false,
        })
    }

    /// Even if an author ignores this refusal, `finish` refuses the whole set.
    pub fn push(&mut self, change: Change<Row, Row::Id>) -> Result<(), Change<Row, Row::Id>> {
        if self.changes.len() == self.limit {
            self.refused = true;
            return Err(change);
        }
        self.changes.push(change);
        Ok(())
    }

    pub fn finish(self) -> Result<Vec<Change<Row, Row::Id>>, Error> {
        if self.refused {
            Err(Error::Full)
        } else {
            Ok(self.changes)
        }
    }
}