pipecircuit 0.0.12

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

use crate::{Reactor, Switchboard};

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[must_use = "circuit reaction outcomes must be handled"]
pub enum CircuitReactionOutcome<Completion> {
    ContinueReaction,
    AwaitingReaction,
    Completed { completion: Completion },
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[must_use = "circuit send outcomes must be handled"]
pub enum CircuitSendOutcome<From, Completion> {
    Immediate { from: From },
    Submitted,
    Completed { completion: Completion },
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[must_use = "circuit flow outcomes must be handled"]
pub enum CircuitFlowOutcome<Completion> {
    Submitted,
    Completed { completion: Completion },
}

#[inline]
pub fn flow<'message, Board, Completion, Failure>(
    switchboard: &mut Board,
    mut from: Board::From<'message>,
    mut send: impl FnMut(
        Board::To<'message>,
    ) -> Result<CircuitSendOutcome<Board::From<'message>, Completion>, Failure>,
) -> Result<CircuitFlowOutcome<Completion>, Failure>
where
    Board: Switchboard,
{
    loop {
        match send(switchboard.route(from))? {
            CircuitSendOutcome::Immediate { from: next } => from = next,
            CircuitSendOutcome::Submitted => return Ok(CircuitFlowOutcome::Submitted),
            CircuitSendOutcome::Completed { completion } => {
                return Ok(CircuitFlowOutcome::Completed { completion });
            }
        }
    }
}

pub trait Circuit<Board: Switchboard> {
    type Reactor: Reactor;
    type Completion;
    type Failure;

    fn reactor(&mut self) -> &mut Self::Reactor;

    fn react(
        &mut self,
        switchboard: &mut Board,
        reaction: &<Self::Reactor as Reactor>::Reaction,
    ) -> Result<CircuitReactionOutcome<Self::Completion>, Self::Failure>;
}

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

    impl Switchboard for Router {
        type From<'message> = u8;
        type To<'message> = u16;

        fn route<'message>(&mut self, input: Self::From<'message>) -> Self::To<'message> {
            u16::from(input)
        }
    }

    struct TestReactor;

    impl Reactor for TestReactor {
        type Reaction = u8;
        type Failure = core::convert::Infallible;

        fn wait_for_reaction(&mut self) -> Result<Self::Reaction, Self::Failure> {
            Ok(7)
        }
    }

    struct InstalledCircuit {
        reactor: TestReactor,
    }

    impl Circuit<Router> for InstalledCircuit {
        type Reactor = TestReactor;
        type Completion = u16;
        type Failure = core::convert::Infallible;

        fn reactor(&mut self) -> &mut Self::Reactor {
            &mut self.reactor
        }

        fn react(
            &mut self,
            switchboard: &mut Router,
            reaction: &u8,
        ) -> Result<CircuitReactionOutcome<Self::Completion>, Self::Failure> {
            Ok(CircuitReactionOutcome::Completed {
                completion: switchboard.route(*reaction),
            })
        }
    }

    #[test]
    fn a_circuit_reacts_through_only_its_selected_switchboard() {
        let mut circuit = InstalledCircuit {
            reactor: TestReactor,
        };
        let mut switchboard = Router;
        assert_eq!(
            circuit.react(&mut switchboard, &7),
            Ok(CircuitReactionOutcome::Completed { completion: 7 })
        );
    }

    #[test]
    fn flow_routes_every_immediate_output_before_submission() {
        let mut switchboard = Router;
        let mut sent = 0;

        assert_eq!(
            flow(&mut switchboard, 1, |to| {
                sent += 1;
                if to < 3 {
                    let Ok(next) = u8::try_from(to + 1) else {
                        return Ok(CircuitSendOutcome::Completed { completion: () });
                    };
                    Ok::<CircuitSendOutcome<u8, ()>, core::convert::Infallible>(
                        CircuitSendOutcome::Immediate { from: next },
                    )
                } else {
                    Ok(CircuitSendOutcome::Submitted)
                }
            }),
            Ok(CircuitFlowOutcome::Submitted)
        );
        assert_eq!(sent, 3);
    }
}