Skip to main content

blitz_debug_control/
handoff.rs

1use std::future::{Future, poll_fn};
2use std::pin::Pin;
3use std::sync::{Arc, Mutex};
4use std::task::{Context, Poll, Waker};
5use std::time::Duration;
6
7use super::{ControlRequest, ControlResponse};
8
9/// A command was not immediately available.
10#[derive(Debug, Clone, Copy, PartialEq, Eq)]
11pub enum TryRecvError {
12    Empty,
13    Disconnected,
14}
15
16impl std::fmt::Display for TryRecvError {
17    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
18        f.write_str(match self {
19            Self::Empty => "renderer command queue is empty",
20            Self::Disconnected => "renderer command queue is closed",
21        })
22    }
23}
24
25impl std::error::Error for TryRecvError {}
26
27/// A blocking command receive outlived its deadline or server.
28#[derive(Debug, Clone, Copy, PartialEq, Eq)]
29pub enum RecvTimeoutError {
30    Timeout,
31    Disconnected,
32}
33
34impl std::fmt::Display for RecvTimeoutError {
35    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
36        f.write_str(match self {
37            Self::Timeout => "renderer command receive timed out",
38            Self::Disconnected => "renderer command queue is closed",
39        })
40    }
41}
42
43impl std::error::Error for RecvTimeoutError {}
44
45#[derive(Debug, Clone, Copy, PartialEq, Eq)]
46pub struct RecvError;
47
48impl std::fmt::Display for RecvError {
49    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
50        f.write_str("renderer command queue is closed")
51    }
52}
53
54impl std::error::Error for RecvError {}
55
56/// Value-delivery adapter over the consumer-owned typed command ring.
57pub struct ValueReceiver(pub(crate) CommandReceiver);
58
59impl ValueReceiver {
60    pub fn try_recv(&self) -> Result<ControlRequest, TryRecvError> {
61        self.0.try_recv().map(Self::into_value)
62    }
63
64    pub fn recv(&self) -> Result<ControlRequest, RecvError> {
65        nagoya::block_on(self.0.recv())
66            .map(Self::into_value)
67            .map_err(|_| RecvError)
68    }
69
70    pub fn recv_timeout(&self, timeout: Duration) -> Result<ControlRequest, RecvTimeoutError> {
71        self.0.recv_timeout(timeout).map(Self::into_value)
72    }
73
74    pub fn iter(&self) -> ValueIter<'_> {
75        ValueIter(self)
76    }
77
78    pub fn try_iter(&self) -> TryValueIter<'_> {
79        TryValueIter(self)
80    }
81
82    fn into_value(request: Arc<ControlRequest>) -> ControlRequest {
83        Arc::try_unwrap(request).expect("queued request has one consumer")
84    }
85}
86
87pub struct ValueIter<'a>(&'a ValueReceiver);
88
89impl Iterator for ValueIter<'_> {
90    type Item = ControlRequest;
91
92    fn next(&mut self) -> Option<Self::Item> {
93        self.0.recv().ok()
94    }
95}
96
97pub struct TryValueIter<'a>(&'a ValueReceiver);
98
99impl Iterator for TryValueIter<'_> {
100    type Item = ControlRequest;
101
102    fn next(&mut self) -> Option<Self::Item> {
103        self.0.try_recv().ok()
104    }
105}
106
107impl<'a> IntoIterator for &'a ValueReceiver {
108    type Item = ControlRequest;
109    type IntoIter = ValueIter<'a>;
110
111    fn into_iter(self) -> Self::IntoIter {
112        self.iter()
113    }
114}
115
116pub struct IntoValueIter(ValueReceiver);
117
118impl Iterator for IntoValueIter {
119    type Item = ControlRequest;
120
121    fn next(&mut self) -> Option<Self::Item> {
122        self.0.recv().ok()
123    }
124}
125
126impl IntoIterator for ValueReceiver {
127    type Item = ControlRequest;
128    type IntoIter = IntoValueIter;
129
130    fn into_iter(self) -> Self::IntoIter {
131        IntoValueIter(self)
132    }
133}
134
135struct Ring<T> {
136    producer: spsc::Producer<Arc<T>>,
137    consumer: spsc::Consumer<Arc<T>>,
138    waiter: Option<Waker>,
139    closed: bool,
140}
141
142pub(crate) struct CommandQueue(Mutex<Ring<ControlRequest>>);
143
144pub(crate) enum QueueError {
145    Full,
146    Closed,
147}
148
149impl CommandQueue {
150    pub(crate) fn new(capacity: usize) -> Arc<Self> {
151        let (producer, consumer) = spsc::make(capacity);
152        Arc::new(Self(Mutex::new(Ring {
153            producer,
154            consumer,
155            waiter: None,
156            closed: false,
157        })))
158    }
159
160    pub(crate) fn enqueue(&self, request: Arc<ControlRequest>) -> Result<(), QueueError> {
161        // All producers share this lock. The ring has one producer lane and
162        // one consumer lane even when reactor tasks move between workers.
163        let wake = {
164            let mut ring = self.0.lock().unwrap();
165            if ring.closed {
166                return Err(QueueError::Closed);
167            }
168            if ring.producer.try_push(request).is_some() {
169                return Err(QueueError::Full);
170            }
171            ring.waiter.take()
172        };
173        if let Some(wake) = wake {
174            wake.wake();
175        }
176        Ok(())
177    }
178
179    pub(crate) fn close(&self) {
180        let wake = {
181            let mut ring = self.0.lock().unwrap();
182            ring.closed = true;
183            ring.waiter.take()
184        };
185        if let Some(wake) = wake {
186            wake.wake();
187        }
188    }
189}
190
191/// Single renderer consumer of typed request pointers.
192///
193/// Every returned Arc is the pointer enqueued by the transport. Receiving
194/// does not copy the method, path or JSON body.
195pub struct CommandReceiver(pub(crate) Arc<CommandQueue>);
196
197impl CommandReceiver {
198    /// Take a queued request without waiting.
199    pub fn try_recv(&self) -> Result<Arc<ControlRequest>, TryRecvError> {
200        let ring = self.0.0.lock().unwrap();
201        match ring.consumer.try_pop() {
202            Some(request) => Ok(request),
203            None if ring.closed => Err(TryRecvError::Disconnected),
204            None => Err(TryRecvError::Empty),
205        }
206    }
207
208    /// Await one request. Only one receive future may wait at a time.
209    pub async fn recv(&self) -> Result<Arc<ControlRequest>, TryRecvError> {
210        poll_fn(|cx| {
211            let mut ring = self.0.0.lock().unwrap();
212            if let Some(request) = ring.consumer.try_pop() {
213                Poll::Ready(Ok(request))
214            } else if ring.closed {
215                Poll::Ready(Err(TryRecvError::Disconnected))
216            } else {
217                ring.waiter = Some(cx.waker().clone());
218                Poll::Pending
219            }
220        })
221        .await
222    }
223
224    /// Blocking adapter for an existing headless renderer entry point.
225    pub fn recv_timeout(&self, timeout: Duration) -> Result<Arc<ControlRequest>, RecvTimeoutError> {
226        match nagoya::block_on(nagoya::time::timeout(timeout, self.recv())) {
227            Ok(Ok(request)) => Ok(request),
228            Ok(Err(_)) => Err(RecvTimeoutError::Disconnected),
229            Err(_) => Err(RecvTimeoutError::Timeout),
230        }
231    }
232}
233
234impl Drop for CommandReceiver {
235    fn drop(&mut self) {
236        self.0.close();
237        // Release requests that nobody can now take, waking response waiters.
238        while self.0.0.lock().unwrap().consumer.try_pop().is_some() {}
239    }
240}
241
242#[derive(Debug)]
243struct ReplyState {
244    response: Option<Arc<ControlResponse>>,
245    waiter: Option<Waker>,
246    completed: bool,
247    sender_closed: bool,
248    receiver_alive: bool,
249}
250
251#[derive(Debug)]
252pub(crate) struct Reply(Arc<Mutex<ReplyState>>);
253
254impl Reply {
255    pub(crate) fn new() -> Arc<Self> {
256        Arc::new(Self(Arc::new(Mutex::new(ReplyState {
257            response: None,
258            waiter: None,
259            completed: false,
260            sender_closed: false,
261            receiver_alive: true,
262        }))))
263    }
264
265    pub(crate) fn complete(
266        &self,
267        response: Arc<ControlResponse>,
268    ) -> Result<(), Arc<ControlResponse>> {
269        let wake = {
270            let mut state = self.0.lock().unwrap();
271            if !state.receiver_alive || state.completed || state.sender_closed {
272                return Err(response);
273            }
274            state.response = Some(response);
275            state.completed = true;
276            state.waiter.take()
277        };
278        if let Some(wake) = wake {
279            wake.wake();
280        }
281        Ok(())
282    }
283
284    pub(crate) fn close_sender(&self) {
285        let wake = {
286            let mut state = self.0.lock().unwrap();
287            state.sender_closed = true;
288            state.waiter.take()
289        };
290        if let Some(wake) = wake {
291            wake.wake();
292        }
293    }
294}
295
296impl Drop for Reply {
297    fn drop(&mut self) {
298        self.close_sender();
299    }
300}
301
302pub(crate) struct ResponseWait(Arc<Mutex<ReplyState>>);
303
304impl ResponseWait {
305    pub(crate) fn new(reply: &Arc<Reply>) -> Self {
306        // Own completion state without keeping the request's sender alive.
307        Self(Arc::clone(&reply.0))
308    }
309}
310
311impl Future for ResponseWait {
312    type Output = Result<Arc<ControlResponse>, ()>;
313
314    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
315        let mut state = self.0.lock().unwrap();
316        if let Some(response) = state.response.take() {
317            Poll::Ready(Ok(response))
318        } else if state.sender_closed {
319            Poll::Ready(Err(()))
320        } else {
321            state.waiter = Some(cx.waker().clone());
322            Poll::Pending
323        }
324    }
325}
326
327impl Drop for ResponseWait {
328    fn drop(&mut self) {
329        let mut state = self.0.lock().unwrap();
330        state.receiver_alive = false;
331        state.waiter = None;
332        state.response = None;
333    }
334}