Skip to main content

tor_async_utils/bw_pool/
reusable_oneshot.rs

1//! A reusable async oneshot channel.
2//!
3//! This is a oneshot channel that can be reinitialized without needing to allocate new memory,
4//! which can be useful when you need to repeatedly initialize a new oneshot channel after a
5//! previous channel is used.
6
7use std::ops::Drop;
8use std::pin::Pin;
9use std::sync::atomic::{AtomicBool, Ordering};
10use std::sync::{Arc, Mutex, Weak};
11use std::task::{Context, Poll};
12
13use futures::task::AtomicWaker;
14
15/// The transmitting end of the oneshot channel.
16#[derive(Debug)]
17pub(crate) struct Sender<T> {
18    /// State shared with the [`Receiver`].
19    shared: Option<Weak<Shared<T>>>,
20}
21
22/// The receiving end of the oneshot channel.
23#[derive(Debug)]
24pub(crate) struct Receiver<T> {
25    /// State shared with the [`Sender`].
26    shared: Arc<Shared<T>>,
27    /// Are we still waiting to receive the message?
28    is_waiting_for_msg: bool,
29}
30
31/// State shared by a [`Sender`] and [`Receiver`].
32#[derive(Debug)]
33struct Shared<T> {
34    /// The message sent from the [`Sender`] to the [`Receiver`].
35    ///
36    /// This is a [`Mutex`], but we only ever use [`try_lock()`](Mutex::try_lock)
37    /// so this will never block.
38    /// An `AtomicRefCell` would be nicer, but a `Mutex` with `try_lock()` does
39    /// effectively the same thing without the extra dependency.
40    /// Other more-performant alternatives are a `OnceLock` (requires an additional spinloop around
41    /// an `Arc::get_mut()`) or `UnsafeCell` (requires unsafe).
42    msg: Mutex<Option<Result<T, SenderDropped>>>,
43    /// Whether the `msg` field is set.
44    ///
45    /// We could just check `msg` directly for a `Some` value,
46    /// but that requires two atomic CAS operations per check
47    /// (one to lock and another to unlock).
48    /// Instead we use this atomic so that there is only a single atomic load.
49    is_msg_set: AtomicBool,
50    /// The receiver's waker.
51    waker: AtomicWaker,
52}
53
54impl<T> Receiver<T> {
55    /// A new receiver without a [`Sender`].
56    pub(crate) fn new() -> Self {
57        let shared = Shared {
58            msg: Mutex::new(None),
59            is_msg_set: AtomicBool::new(false),
60            waker: AtomicWaker::new(),
61        };
62        let shared = Arc::new(shared);
63
64        Receiver {
65            shared,
66            is_waiting_for_msg: false,
67        }
68    }
69
70    /// Is this receiver waiting for a message?
71    ///
72    /// This is true if the receiver has a [`Sender`] that it has not read a message from yet.
73    ///
74    /// If this returns false, then a
75    /// [new `Sender`](Receiver::new_sender) can be successfully created.
76    // Is currently unused.
77    #[expect(unused)]
78    pub(crate) fn is_waiting_for_msg(&self) -> bool {
79        self.is_waiting_for_msg
80    }
81
82    /// Create a new [`Sender`].
83    /// Can only have one sender at a time.
84    ///
85    /// Returns `None` if we've previously created a sender and we haven't read its message yet.
86    // Is currently only used in tests.
87    #[cfg_attr(not(test), expect(unused))]
88    pub(crate) fn new_sender(&mut self) -> Option<Sender<T>> {
89        Some(self.guarantee_new_sender()?.into_sender())
90    }
91
92    /// Provides a type that can be converted into a new [`Sender`].
93    ///
94    /// This can be useful if you don't want a new `Sender` yet,
95    /// but you want a guarantee that a sender can be created later.
96    ///
97    /// Returns `None` if we've previously created a sender and we haven't read its message yet.
98    pub(crate) fn guarantee_new_sender(&mut self) -> Option<SenderGuarantee<'_, T>> {
99        // If we're still waiting for a message from the last sender,
100        // don't allow the creation of a new sender.
101        if self.is_waiting_for_msg {
102            return None;
103        }
104
105        Some(SenderGuarantee(self))
106    }
107
108    /// Receive the message.
109    pub(crate) fn recv<'a>(&'a mut self) -> Result<ReceiverFuture<'a, T>, NoSender> {
110        // If we're not waiting for a message, then there will never be a message.
111        if !self.is_waiting_for_msg {
112            return Err(NoSender);
113        }
114
115        Ok(ReceiverFuture { receiver: self })
116    }
117
118    /// Try to receive a message without blocking.
119    pub(crate) fn try_recv(&mut self) -> Result<Option<T>, RecvError> {
120        // If we're not waiting for a message, then there will never be a message.
121        if !self.is_waiting_for_msg {
122            return Err(RecvError::NoSender);
123        }
124
125        self.recv_impl().transpose().map_err(Into::into)
126    }
127
128    /// The shared implementation to receive the message.
129    ///
130    /// The "message has not yet been set" path is quick (just an atomic load)
131    /// so its cheap to check.
132    ///
133    /// Returns `None` if there's no update.
134    /// Returns `Some` if we have the message or the sender was dropped.
135    fn recv_impl(&mut self) -> Option<Result<T, SenderDropped>> {
136        // An acquire-load so that the `Some` value for `self.shared.msg` as set by
137        // `Sender::send_impl()` is visible here.
138        if !self.shared.is_msg_set.load(Ordering::Acquire) {
139            return None;
140        }
141
142        // There won't ever be contention on the lock, so we can `try_lock().expect()`.
143        let msg = self
144            .shared
145            .msg
146            .try_lock()
147            .expect("msg lock")
148            .take()
149            .expect("msg was set but no msg available");
150
151        // We removed the message, so reset the flag.
152        //
153        // A relaxed-store since the `take()` above doesn't need to be visible to any other
154        // threads (the sender is gone now that it sent the one value).
155        self.shared.is_msg_set.store(false, Ordering::Relaxed);
156
157        self.is_waiting_for_msg = false;
158
159        Some(msg)
160    }
161}
162
163/// Future returned by [`Receiver::recv()`].
164#[derive(Debug)]
165pub(crate) struct ReceiverFuture<'a, T> {
166    /// The receiver.
167    receiver: &'a mut Receiver<T>,
168}
169
170impl<'a, T> Future for ReceiverFuture<'a, T> {
171    type Output = Result<T, SenderDropped>;
172
173    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
174        let self_ = self.get_mut();
175
176        let check_fn = |receiver: &mut Receiver<T>| {
177            // If there was something to receive,
178            // then we return it from the future.
179            if let Some(msg) = receiver.recv_impl() {
180                Poll::Ready(msg)
181            } else {
182                Poll::Pending
183            }
184        };
185
186        // Initial check is for performance, since the check is quick.
187        match check_fn(self_.receiver) {
188            Poll::Ready(msg) => return Poll::Ready(msg),
189            Poll::Pending => {}
190        }
191
192        self_.receiver.shared.waker.register(cx.waker());
193
194        // Must recheck after registering the waker.
195        //
196        // > Consumers should call `register` before checking the result of a computation and
197        // > producers should call `wake` after producing the computation (this differs from the
198        // > usual `thread::park` pattern).
199        check_fn(self_.receiver)
200    }
201}
202
203impl<T> Sender<T> {
204    /// Send the message.
205    pub(crate) fn send(mut self, msg: T) {
206        // Shouldn't panic because `shared` is only taken here in `send()` or `drop()`.
207        let shared = self.shared.take().expect("shared is missing");
208
209        // Send the message.
210        Self::send_impl(shared, Ok(msg));
211    }
212
213    /// The shared implementation to send the message.
214    ///
215    /// It's assumed that a message has not yet been set.
216    /// Otherwise this code will panic.
217    // Semantically it makes more sense to take an owned `Weak` here since we don't want the caller
218    // to keep it. (The caller could clone it, but we're not trying to be foolproof here.)
219    #[allow(clippy::needless_pass_by_value)]
220    fn send_impl(shared: Weak<Shared<T>>, msg: Result<T, SenderDropped>) {
221        let Some(shared) = shared.upgrade() else {
222            // All receivers have dropped; nothing to do.
223            return;
224        };
225
226        // Set the message.
227        {
228            // There won't ever be contention on the lock, so we can `try_lock().expect()`.
229            let mut msg_store = shared.msg.try_lock().expect("msg lock");
230
231            if msg_store.is_some() {
232                // Our channel logic is broken. Not much we can do here but panic.
233                // See the contract in the doc comment of `send_impl()`.
234                panic!("trying to send a message, but msg was already set");
235            }
236
237            *msg_store = Some(msg);
238        }
239
240        // A release-store since the message set above should be visible after the
241        // acquire-load in `Receiver::recv_impl()`.
242        let _ = shared
243            .is_msg_set
244            .compare_exchange(false, true, Ordering::Release, Ordering::Relaxed)
245            .expect("msg was unset, but is_msg_set was true");
246
247        // At this point it's possible that the receiver will see that `is_msg_set` is true,
248        // read the value, and even create a new sender. But this is fine because below the only
249        // thing we do is a `wake()`, which in that case would only cause a spurious wake of the
250        // new sender.
251
252        // Must wake after setting the message.
253        //
254        // > Consumers should call `register` before checking the result of a computation and
255        // > producers should call `wake` after producing the computation (this differs from the
256        // > usual `thread::park` pattern).
257        shared.waker.wake();
258    }
259}
260
261impl<T> Drop for Sender<T> {
262    fn drop(&mut self) {
263        let Some(shared) = self.shared.take() else {
264            // Already sent a message.
265            return;
266        };
267
268        // Send a notification that the sender was dropped.
269        Self::send_impl(shared, Err(SenderDropped));
270    }
271}
272
273/// A guarantee that a new sender can be created.
274///
275/// Returned from [`Receiver::guarantee_new_sender()`].
276/// The guarantee will be voided if this handle is dropped.
277///
278/// Note: Due to non-lexical lifetimes,
279/// it's possible to have multiple different `SenderGuarantee`s at the same time.
280/// But this is okay since the compiler will only allow you to use the latest one.
281pub(crate) struct SenderGuarantee<'a, T>(&'a mut Receiver<T>);
282
283impl<'a, T> SenderGuarantee<'a, T> {
284    /// Convert the guarantee into a new [`Sender`].
285    pub(crate) fn into_sender(self) -> Sender<T> {
286        // Now we're creating a new sender,
287        // which we'll be waiting for a message from.
288        self.0.is_waiting_for_msg = true;
289
290        Sender {
291            shared: Some(Arc::downgrade(&self.0.shared)),
292        }
293    }
294}
295
296/// A sender existed, but was dropped before sending a message.
297#[derive(Debug, PartialEq, Eq)]
298pub(crate) struct SenderDropped;
299
300/// The receiver does not have a sender.
301///
302/// Have not yet created a new sender (see [`Receiver::new_sender()`]),
303/// or we've already read the message from the last sender.
304#[derive(Debug, PartialEq, Eq)]
305pub(crate) struct NoSender;
306
307/// An error when attempting to receive a message.
308#[derive(Debug, PartialEq, Eq)]
309pub(crate) enum RecvError {
310    /// See [`NoSender`].
311    NoSender,
312    /// See [`SenderDropped`].
313    SenderDropped,
314}
315
316impl From<SenderDropped> for RecvError {
317    fn from(_: SenderDropped) -> Self {
318        Self::SenderDropped
319    }
320}
321
322#[cfg(test)]
323mod tests {
324    // @@ begin test lint list maintained by maint/add_warning @@
325    #![allow(clippy::bool_assert_comparison)]
326    #![allow(clippy::clone_on_copy)]
327    #![allow(clippy::dbg_macro)]
328    #![allow(clippy::mixed_attributes_style)]
329    #![allow(clippy::print_stderr)]
330    #![allow(clippy::print_stdout)]
331    #![allow(clippy::single_char_pattern)]
332    #![allow(clippy::unwrap_used)]
333    #![allow(clippy::unchecked_time_subtraction)]
334    #![allow(clippy::useless_vec)]
335    #![allow(clippy::needless_pass_by_value)]
336    #![allow(clippy::string_slice)] // See arti#2571
337    //! <!-- @@ end test lint list maintained by maint/add_warning @@ -->
338
339    use super::*;
340
341    use std::time::Duration;
342
343    use futures::FutureExt as _;
344    use tor_rtcompat::SleepProvider as _;
345    use tor_rtcompat::SpawnExt as _;
346
347    #[test]
348    fn simple() {
349        // New receiver.
350        let mut receiver = Receiver::<u8>::new();
351
352        // New sender, send message, and receive message.
353        let sender = receiver.new_sender().unwrap();
354        sender.send(5);
355        assert_eq!(receiver.recv().unwrap().now_or_never().unwrap(), Ok(5));
356
357        // New sender, send message, and receive message.
358        let sender = receiver.new_sender().unwrap();
359        sender.send(10);
360        assert_eq!(receiver.recv().unwrap().now_or_never().unwrap(), Ok(10));
361
362        // New sender, send message, and try-receive message.
363        let sender = receiver.new_sender().unwrap();
364        sender.send(15);
365        assert_eq!(receiver.try_recv(), Ok(Some(15)));
366    }
367
368    #[test]
369    fn no_senders() {
370        // New receiver without a sender, can't receive a message.
371        let mut receiver = Receiver::<u8>::new();
372        assert_eq!(receiver.recv().unwrap_err(), NoSender);
373        assert_eq!(receiver.try_recv(), Err(RecvError::NoSender));
374
375        // New sender, send message, and receive message.
376        let sender = receiver.new_sender().unwrap();
377        sender.send(5);
378        assert_eq!(receiver.recv().unwrap().now_or_never().unwrap(), Ok(5));
379
380        // New sender, send message, and receive message.
381        let sender = receiver.new_sender().unwrap();
382        sender.send(10);
383        assert_eq!(receiver.try_recv(), Ok(Some(10)));
384
385        // Sent and received a value above, so it has no sender again.
386        assert_eq!(receiver.recv().unwrap_err(), NoSender);
387        assert_eq!(receiver.try_recv(), Err(RecvError::NoSender));
388    }
389
390    #[test]
391    fn two_senders() {
392        // New receiver.
393        let mut receiver = Receiver::<u8>::new();
394
395        // New sender.
396        let sender = receiver.new_sender().unwrap();
397
398        // Cannot get second sender.
399        assert!(receiver.new_sender().is_none());
400
401        // Send message and receive message.
402        sender.send(5);
403        assert_eq!(receiver.recv().unwrap().now_or_never().unwrap(), Ok(5));
404
405        // Can get a sender again now that the first sender sent a message and we received it.
406        let _sender = receiver.new_sender().unwrap();
407    }
408
409    #[test]
410    fn sender_drop() {
411        // New receiver.
412        let mut receiver = Receiver::<u8>::new();
413
414        // New sender, drop sender, and receive message tells us that the sender was dropped.
415        let sender = receiver.new_sender().unwrap();
416        drop(sender);
417        assert_eq!(
418            receiver.recv().unwrap().now_or_never().unwrap(),
419            Err(SenderDropped),
420        );
421        assert_eq!(receiver.recv().unwrap_err(), NoSender);
422
423        // New sender, drop sender, and receive message tells us that the sender was dropped.
424        let sender = receiver.new_sender().unwrap();
425        drop(sender);
426        assert_eq!(receiver.try_recv(), Err(RecvError::SenderDropped));
427        assert_eq!(receiver.try_recv(), Err(RecvError::NoSender));
428
429        // New sender, send message, and receive message.
430        let sender = receiver.new_sender().unwrap();
431        sender.send(5);
432        assert_eq!(receiver.recv().unwrap().now_or_never().unwrap(), Ok(5));
433
434        // New sender, send message, and receive message.
435        let sender = receiver.new_sender().unwrap();
436        sender.send(10);
437        assert_eq!(receiver.try_recv(), Ok(Some(10)));
438    }
439
440    #[test]
441    fn sender_guarantee() {
442        // New receiver.
443        let mut receiver = Receiver::<u8>::new();
444
445        // We don't have a sender, so we should get a guarantee.
446        let _sender_guarantee_1 = receiver.guarantee_new_sender().unwrap();
447
448        // Due to non-lexical lifetimes, rust allows us to get another guarantee.
449        // But this is okay because it won't allow us to use the first again.
450        let sender_guarantee_2 = receiver.guarantee_new_sender().unwrap();
451
452        let _sender = sender_guarantee_2.into_sender();
453
454        // Now that we have a sender, we can't get a new guarantee.
455        assert!(receiver.guarantee_new_sender().is_none());
456    }
457
458    #[test]
459    fn test_async() {
460        tor_rtmock::MockRuntime::test_with_various(|rt| async move {
461            // Have time advance automatically.
462            rt.spawn({
463                let rt = rt.clone();
464                async move { rt.advance_until_stalled().await }
465            })
466            .unwrap();
467
468            let mut receiver = Receiver::<u8>::new();
469
470            // In a new task, wait 100 ms and then send the message.
471            rt.spawn({
472                let sender = receiver.new_sender().unwrap();
473                let rt = rt.clone();
474                async move {
475                    rt.sleep(Duration::from_millis(100)).await;
476                    sender.send(10);
477                }
478            })
479            .unwrap();
480
481            // Wait for the message to arrive.
482            assert_eq!(receiver.recv().unwrap().await, Ok(10));
483
484            // In a new task, wait 2000 ms and then send the message.
485            rt.spawn({
486                let sender = receiver.new_sender().unwrap();
487                let rt = rt.clone();
488                async move {
489                    rt.sleep(Duration::from_millis(2000)).await;
490                    sender.send(20);
491                }
492            })
493            .unwrap();
494
495            // Wait for the message to arrive.
496            assert_eq!(receiver.recv().unwrap().await, Ok(20));
497
498            // In a new task, wait 2000 ms and then drop the sender.
499            rt.spawn({
500                let sender = receiver.new_sender().unwrap();
501                let rt = rt.clone();
502                async move {
503                    rt.sleep(Duration::from_millis(2000)).await;
504                    drop(sender);
505                }
506            })
507            .unwrap();
508
509            // Wait to be notified that the sender was dropped.
510            assert_eq!(receiver.recv().unwrap().await, Err(SenderDropped));
511        });
512    }
513}