async_utils/
mutex_ticket.rs

1// Copyright 2021 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5use futures::lock::{Mutex, MutexGuard, MutexLockFuture};
6use futures::prelude::*;
7use std::task::{Context, Poll};
8
9/// Helper to poll a mutex.
10///
11/// Since Mutex::lock futures keep track of where in queue the lock request is,
12/// this is different to `mutex.lock().poll(ctx)` as that construction will create
13/// a new lock request at each poll.
14/// This can often be useful when we need to poll something that is contained under
15/// this mutex.
16///
17/// Typical usage:
18///   let mut ticket = MutexTicket::new();
19///   poll_fn(|ctx| {
20///     let mutex_guard = ready!(ticket.poll(ctx));
21///     mutex_guard.some_child_future.poll(ctx)
22///   }).await;
23///
24/// What this means:
25///   Attempt to acquire the mutex. If it's not available, wait until it's available.
26///   With the mutex acquired, check some_child_future.
27///   If it's completed, complete the poll_fn.
28///   *If it's not completed* drop the mutex guard (unblock other tasks) and wait for
29///   some_child_future to be awoken.
30#[derive(Debug)]
31pub struct MutexTicket<'a, T> {
32    mutex: &'a Mutex<T>,
33    lock: Option<MutexLockFuture<'a, T>>,
34}
35
36impl<'a, T> MutexTicket<'a, T> {
37    /// Create a new `MutexTicket`
38    pub fn new(mutex: &'a Mutex<T>) -> MutexTicket<'a, T> {
39        MutexTicket { mutex, lock: None }
40    }
41
42    /// Poll once to see if the lock has been acquired.
43    /// This is not Future::poll because it's intended to be a helper used during a Future::poll
44    /// implementation, but never as a Future itself -- one can simply call Mutex::lock.await in that
45    /// case!
46    pub fn poll(&mut self, ctx: &mut Context<'_>) -> Poll<MutexGuard<'a, T>> {
47        let mut lock_fut = match self.lock.take() {
48            None => self.mutex.lock(),
49            Some(lock_fut) => lock_fut,
50        };
51        match lock_fut.poll_unpin(ctx) {
52            Poll::Pending => {
53                self.lock = Some(lock_fut);
54                Poll::Pending
55            }
56            Poll::Ready(g) => Poll::Ready(g),
57        }
58    }
59
60    /// Finish locking. This should be used instead of the Mutex.lock function *if* there
61    /// is a `MutexTicket` constructed already - it may be that said `MutexTicket` has already been
62    /// granted ownership of the Mutex - if this is the case, the Mutex.lock call will never succeed.
63    pub async fn lock(&mut self) -> MutexGuard<'a, T> {
64        match self.lock.take() {
65            None => self.mutex.lock(),
66            Some(lock_fut) => lock_fut,
67        }
68        .await
69    }
70}
71
72#[cfg(test)]
73mod tests {
74
75    use super::MutexTicket;
76    use anyhow::{Error, format_err};
77    use assert_matches::assert_matches;
78    use fuchsia_async::Timer;
79    use futures::channel::oneshot;
80    use futures::future::{poll_fn, try_join};
81    use futures::lock::Mutex;
82    use std::task::{Context, Poll, Waker};
83    use std::time::Duration;
84
85    #[fuchsia_async::run_singlethreaded(test)]
86    async fn basics(run: usize) {
87        let mutex = Mutex::new(run);
88        let mut ctx = Context::from_waker(Waker::noop());
89        let mut poll_mutex = MutexTicket::new(&mutex);
90        assert_matches!(poll_mutex.poll(&mut ctx), Poll::Ready(_));
91        assert_matches!(poll_mutex.poll(&mut ctx), Poll::Ready(_));
92        assert_matches!(poll_mutex.poll(&mut ctx), Poll::Ready(_));
93        let mutex_guard = mutex.lock().await;
94        assert_matches!(poll_mutex.poll(&mut ctx), Poll::Pending);
95        assert_matches!(poll_mutex.poll(&mut ctx), Poll::Pending);
96        drop(mutex_guard);
97        assert_matches!(poll_mutex.poll(&mut ctx), Poll::Ready(_));
98    }
99
100    #[fuchsia_async::run_singlethreaded(test)]
101    async fn wakes_up(run: usize) -> Result<(), Error> {
102        let mutex = Mutex::new(run);
103        let (tx_saw_first_pending, rx_saw_first_pending) = oneshot::channel();
104        let mut poll_mutex = MutexTicket::new(&mutex);
105        let mutex_guard = mutex.lock().await;
106        try_join(
107            async move {
108                assert_matches!(
109                    poll_mutex.poll(&mut Context::from_waker(Waker::noop())),
110                    Poll::Pending
111                );
112                tx_saw_first_pending.send(()).map_err(|_| format_err!("cancelled"))?;
113                assert_eq!(*poll_fn(|ctx| poll_mutex.poll(ctx)).await, run);
114                Ok(())
115            },
116            async move {
117                rx_saw_first_pending.await?;
118                Timer::new(Duration::from_millis(300)).await;
119                drop(mutex_guard);
120                Ok(())
121            },
122        )
123        .await
124        .map(|_| ())
125    }
126}
async_utils/mutex_ticket.rs

async_utils/
mutex_ticket.rs
