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}