Skip to main content

bombay_entity/
protocol.rs

1//! Pure entity-specific behavior protocol composition.
2
3use behavior::{
4    Actions, Behavior, ChildEvent, ChildStopped, CreationEvent, CreationResolved, Delivery,
5    PeerEvent, PeerStopped, Recipient, SendAlgebra, SendProduct, ShutdownEvent, ShutdownRequested,
6    TimeEvent, TimerElapsed, User, UserEvent, WorkerCreationEvent, WorkerCreationResolved,
7    WorkerEvent, WorkerStopped,
8};
9
10/// Confirmation that an entity drain fence reached its behavior transition.
11#[derive(Debug, Clone, Copy, PartialEq, Eq)]
12pub struct DrainFenceAcknowledged;
13
14/// Commands accepted by an entity-wrapped behavior.
15#[derive(Clone, PartialEq, Eq)]
16pub enum EntityProtocol<A: behavior::Address, C> {
17    /// An application command forwarded unchanged to the inner behavior.
18    Command(C),
19    /// An ordered processing fence acknowledged after preceding transitions.
20    DrainFence {
21        /// Typed destination for the fence acknowledgement.
22        reply_to: Recipient<A, DrainFenceAcknowledged>,
23    },
24}
25
26/// Complete event protocol for an entity-wrapped behavior.
27#[derive(Clone, PartialEq, Eq)]
28pub enum EntityEvent<E: UserEvent> {
29    /// An event belonging to the wrapped behavior.
30    Inner(E),
31    /// An entity drain fence with its original sender.
32    DrainFence {
33        /// Actor address that submitted the fence.
34        from: E::Addr,
35        /// Typed destination for acknowledgement.
36        reply_to: Recipient<E::Addr, DrainFenceAcknowledged>,
37    },
38}
39
40impl<E: UserEvent> UserEvent for EntityEvent<E> {
41    type Addr = E::Addr;
42    type Message = EntityProtocol<E::Addr, E::Message>;
43
44    fn user(from: Self::Addr, message: Self::Message) -> Self {
45        match message {
46            EntityProtocol::Command(command) => Self::Inner(E::user(from, command)),
47            EntityProtocol::DrainFence { reply_to } => Self::DrainFence { from, reply_to },
48        }
49    }
50
51    fn into_user(self) -> Result<User<Self::Addr, Self::Message>, Self> {
52        match self {
53            Self::Inner(event) => event
54                .into_user()
55                .map(|user| User::new(user.from, EntityProtocol::Command(user.message)))
56                .map_err(Self::Inner),
57            Self::DrainFence { from, reply_to } => {
58                Ok(User::new(from, EntityProtocol::DrainFence { reply_to }))
59            }
60        }
61    }
62}
63
64macro_rules! forward_optional_event {
65    ($trait:ident, $method:ident, $event:ty) => {
66        impl<E> $trait for EntityEvent<E>
67        where
68            E: UserEvent + $trait,
69        {
70            fn $method(event: $event) -> Option<Self> {
71                E::$method(event).map(Self::Inner)
72            }
73        }
74    };
75}
76
77forward_optional_event!(TimeEvent, time_reached, TimerElapsed);
78forward_optional_event!(PeerEvent, peer_stopped, PeerStopped<E::Addr>);
79forward_optional_event!(ChildEvent, child_stopped, ChildStopped<E::Addr>);
80forward_optional_event!(WorkerEvent, worker_stopped, WorkerStopped<E::Addr>);
81forward_optional_event!(
82    CreationEvent,
83    creation_resolved,
84    CreationResolved<<E::Addr as behavior::Address>::Nonce>
85);
86forward_optional_event!(
87    WorkerCreationEvent,
88    worker_creation_resolved,
89    WorkerCreationResolved<<E::Addr as behavior::Address>::Nonce>
90);
91forward_optional_event!(ShutdownEvent, shutdown_requested, ShutdownRequested);
92
93/// Entity-runtime protocol composition around an application behavior.
94pub struct EntityBehavior<B> {
95    inner: B,
96}
97
98impl<B> EntityBehavior<B> {
99    /// Wrap an application behavior with entity command and drain protocols.
100    pub const fn new(inner: B) -> Self {
101        Self { inner }
102    }
103
104    /// Borrow the wrapped behavior.
105    pub const fn inner(&self) -> &B {
106        &self.inner
107    }
108
109    /// Return the wrapped behavior.
110    pub fn into_inner(self) -> B {
111        self.inner
112    }
113}
114
115impl<B: Behavior> Behavior for EntityBehavior<B> {
116    type Addr = B::Addr;
117    type Msg = EntityProtocol<B::Addr, B::Msg>;
118    type Event = EntityEvent<B::Event>;
119    type Sends = SendProduct<B::Sends, Vec<Delivery<B::Addr, DrainFenceAcknowledged>>>;
120    type Ph = B::Ph;
121    type Error = B::Error;
122    type Birth = B::Birth;
123
124    fn init(&mut self) -> behavior::BehaviorActed<Self> {
125        self.inner
126            .init()
127            .map(|actions| actions.map_sends(|sends| SendProduct::new(sends, Vec::new())))
128    }
129
130    fn transition(&mut self, event: Self::Event) -> behavior::BehaviorActed<Self> {
131        match event {
132            EntityEvent::Inner(event) => self
133                .inner
134                .transition(event)
135                .map(|actions| actions.map_sends(|sends| SendProduct::new(sends, Vec::new()))),
136            EntityEvent::DrainFence { reply_to, .. } => Ok(Actions::new(
137                SendProduct::new(
138                    B::Sends::empty(),
139                    vec![Delivery::new(reply_to, DrainFenceAcknowledged)],
140                ),
141                Vec::new(),
142                behavior::Step::Continue,
143            )),
144        }
145    }
146}
147
148#[cfg(test)]
149mod tests {
150    use behavior::{
151        Actions, ChildEvent, ChildStopped, CreationEvent, CreationKind, CreationResolved, Exit,
152        Handler, MailAddr, Never, NoBirths, PeerEvent, PeerStopped, Pure, Route, ShutdownEvent,
153        ShutdownRequested, TimeEvent, TimerElapsed, TimerGeneration, TimerId, WorkerCreationEvent,
154        WorkerCreationResolved, WorkerEvent, WorkerStopped,
155    };
156
157    use super::{DrainFenceAcknowledged, EntityBehavior, EntityEvent, EntityProtocol};
158    use behavior::{Behavior, Recipient, UserEvent};
159
160    struct Counter(usize);
161
162    #[derive(Debug, Clone, PartialEq, Eq)]
163    enum SystemEvent {
164        Time(TimerElapsed),
165        Peer(PeerStopped<MailAddr>),
166        Child(ChildStopped<MailAddr>),
167        Worker(WorkerStopped<MailAddr>),
168        Creation(CreationResolved<u64>),
169        WorkerCreation(WorkerCreationResolved<u64>),
170        Shutdown,
171    }
172
173    impl UserEvent for SystemEvent {
174        type Addr = MailAddr;
175        type Message = Never;
176
177        fn user(_: MailAddr, message: Never) -> Self {
178            match message {}
179        }
180
181        fn into_user(self) -> Result<behavior::User<MailAddr, Never>, Self> {
182            Err(self)
183        }
184    }
185
186    impl TimeEvent for SystemEvent {
187        fn time_reached(event: TimerElapsed) -> Option<Self> {
188            Some(Self::Time(event))
189        }
190    }
191
192    impl PeerEvent for SystemEvent {
193        fn peer_stopped(event: PeerStopped<MailAddr>) -> Option<Self> {
194            Some(Self::Peer(event))
195        }
196    }
197
198    impl ChildEvent for SystemEvent {
199        fn child_stopped(event: ChildStopped<MailAddr>) -> Option<Self> {
200            Some(Self::Child(event))
201        }
202    }
203
204    impl WorkerEvent for SystemEvent {
205        fn worker_stopped(event: WorkerStopped<MailAddr>) -> Option<Self> {
206            Some(Self::Worker(event))
207        }
208    }
209
210    impl CreationEvent for SystemEvent {
211        fn creation_resolved(event: CreationResolved<u64>) -> Option<Self> {
212            Some(Self::Creation(event))
213        }
214    }
215
216    impl WorkerCreationEvent for SystemEvent {
217        fn worker_creation_resolved(event: WorkerCreationResolved<u64>) -> Option<Self> {
218            Some(Self::WorkerCreation(event))
219        }
220    }
221
222    impl ShutdownEvent for SystemEvent {
223        fn shutdown_requested(_: ShutdownRequested) -> Option<Self> {
224            Some(Self::Shutdown)
225        }
226    }
227
228    fn forwarded(event: Option<EntityEvent<SystemEvent>>) -> SystemEvent {
229        match event {
230            Some(EntityEvent::Inner(event)) => event,
231            Some(EntityEvent::DrainFence { .. }) | None => {
232                panic!("system event was not forwarded to the inner protocol")
233            }
234        }
235    }
236
237    impl Handler for Counter {
238        type Addr = MailAddr;
239        type Msg = u8;
240
241        fn receive(
242            &mut self,
243            _from: MailAddr,
244            _message: u8,
245        ) -> behavior::Acted<
246            MailAddr,
247            Never,
248            Vec<behavior::Delivery<MailAddr, Never>>,
249            NoBirths,
250            Never,
251        > {
252            self.0 += 1;
253            Ok(Actions::cont())
254        }
255    }
256
257    #[test]
258    fn command_is_forwarded_unchanged_to_inner_behavior() {
259        let mut behavior = EntityBehavior::new(Pure::new(Counter(0)));
260        let event = UserEvent::user(MailAddr(1), EntityProtocol::Command(7));
261
262        let actions = behavior.transition(event).unwrap();
263
264        assert_eq!(behavior.inner().state().0, 1);
265        assert!(actions.sends.inner.is_empty());
266        assert!(actions.sends.own.is_empty());
267    }
268
269    #[test]
270    fn drain_fence_preserves_inner_state_and_emits_only_acknowledgement() {
271        let mut behavior = EntityBehavior::new(Pure::new(Counter(0)));
272        let reply_to = Recipient::global(MailAddr(9));
273        let event = EntityEvent::user(MailAddr(1), EntityProtocol::DrainFence { reply_to });
274
275        let actions = behavior.transition(event).unwrap();
276
277        assert_eq!(behavior.inner().state().0, 0);
278        assert!(actions.sends.inner.is_empty());
279        assert_eq!(actions.sends.own.len(), 1);
280        assert_eq!(actions.sends.own[0].to.route(), Route::Global(MailAddr(9)));
281        assert_eq!(actions.sends.own[0].message, DrainFenceAcknowledged);
282        assert!(actions.creates.is_empty());
283        assert!(matches!(actions.become_, behavior::Step::Continue));
284    }
285
286    #[test]
287    fn every_optional_system_event_is_forwarded_unchanged() {
288        let elapsed = TimerElapsed::new(TimerId(7), TimerGeneration(3));
289        let peer = PeerStopped::new(MailAddr(9), Ok(Exit::Normal));
290        let child = ChildStopped::new(11, Ok(Exit::Normal), std::time::Instant::now().into());
291        let worker = WorkerStopped::new(13, 17, Ok(Exit::Normal), std::time::Instant::now().into());
292        let creation = CreationResolved::replacement_incarnation(19, 18);
293        let worker_creation = WorkerCreationResolved::new(
294            23,
295            29,
296            CreationKind::ReplacementIncarnation { replaces: 28 },
297            Ok(()),
298        );
299
300        assert_eq!(
301            forwarded(EntityEvent::<SystemEvent>::time_reached(elapsed)),
302            SystemEvent::Time(elapsed)
303        );
304        assert_eq!(
305            forwarded(EntityEvent::<SystemEvent>::peer_stopped(peer.clone())),
306            SystemEvent::Peer(peer)
307        );
308        assert_eq!(
309            forwarded(EntityEvent::<SystemEvent>::child_stopped(child.clone())),
310            SystemEvent::Child(child)
311        );
312        assert_eq!(
313            forwarded(EntityEvent::<SystemEvent>::worker_stopped(worker.clone())),
314            SystemEvent::Worker(worker)
315        );
316        assert_eq!(
317            forwarded(EntityEvent::<SystemEvent>::creation_resolved(creation)),
318            SystemEvent::Creation(creation)
319        );
320        assert_eq!(
321            forwarded(EntityEvent::<SystemEvent>::worker_creation_resolved(
322                worker_creation
323            )),
324            SystemEvent::WorkerCreation(worker_creation)
325        );
326        assert_eq!(
327            forwarded(EntityEvent::<SystemEvent>::shutdown_requested(
328                ShutdownRequested
329            )),
330            SystemEvent::Shutdown
331        );
332    }
333}