Upgrade rust/crates/futures-channel to 0.3.5

Test: None
Change-Id: Id5112b347ceb42aab512c2ae348b230f59ac5ba1

3 files changed, 47 insertions, 20 deletions

diff --git a/src/lib.rs b/src/lib.rs
index d33c919..f3d93d8 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -17,7 +17,7 @@
 
 #![doc(test(attr(deny(warnings), allow(dead_code, unused_assignments, unused_variables))))]
 
-#![doc(html_root_url = "https://docs.rs/futures-channel/0.3.0")]
+#![doc(html_root_url = "https://docs.rs/futures-channel/0.3.5")]
 
 #[cfg(all(feature = "cfg-target-has-atomic", not(feature = "unstable")))]
 compile_error!("The `cfg-target-has-atomic` feature requires the `unstable` feature as an explicit opt-in to unstable features");
diff --git a/src/mpsc/mod.rs b/src/mpsc/mod.rs
index f69f440..bce5e2e 100644
--- a/src/mpsc/mod.rs
+++ b/src/mpsc/mod.rs
@@ -109,7 +109,7 @@ struct BoundedSenderInner<T> {
     // unblocked.
     sender_task: Arc<Mutex<SenderTask>>,
 
-    // True if the sender might be blocked. This is an optimization to avoid
+    // `true` if the sender might be blocked. This is an optimization to avoid
     // having to lock the mutex most of the time.
     maybe_parked: bool,
 }
@@ -189,7 +189,7 @@ impl fmt::Display for SendError {
 impl std::error::Error for SendError {}
 
 impl SendError {
-    /// Returns true if this error is a result of the channel being full.
+    /// Returns `true` if this error is a result of the channel being full.
     pub fn is_full(&self) -> bool {
         match self.kind {
             SendErrorKind::Full => true,
@@ -197,7 +197,7 @@ impl SendError {
         }
     }
 
-    /// Returns true if this error is a result of the receiver being dropped.
+    /// Returns `true` if this error is a result of the receiver being dropped.
     pub fn is_disconnected(&self) -> bool {
         match self.kind {
             SendErrorKind::Disconnected => true,
@@ -227,12 +227,12 @@ impl<T> fmt::Display for TrySendError<T> {
 impl<T: core::any::Any> std::error::Error for TrySendError<T> {}
 
 impl<T> TrySendError<T> {
-    /// Returns true if this error is a result of the channel being full.
+    /// Returns `true` if this error is a result of the channel being full.
     pub fn is_full(&self) -> bool {
         self.err.is_full()
     }
 
-    /// Returns true if this error is a result of the receiver being dropped.
+    /// Returns `true` if this error is a result of the receiver being dropped.
     pub fn is_disconnected(&self) -> bool {
         self.err.is_disconnected()
     }
@@ -536,7 +536,7 @@ impl<T> BoundedSenderInner<T> {
         // This operation will also atomically determine if the sender task
         // should be parked.
         //
-        // None is returned in the case that the channel has been closed by the
+        // `None` is returned in the case that the channel has been closed by the
         // receiver. This happens when `Receiver::close` is called or the
         // receiver is dropped.
         let park_self = match self.inc_num_messages() {
@@ -997,7 +997,7 @@ impl<T> Receiver<T> {
     /// no longer empty.
     ///
     /// This function will panic if called after `try_next` or `poll_next` has
-    /// returned None.
+    /// returned `None`.
     pub fn try_next(&mut self) -> Result<Option<T>, TryRecvError> {
         match self.next_message() {
             Poll::Ready(msg) => {
@@ -1127,7 +1127,7 @@ impl<T> UnboundedReceiver<T> {
     /// no longer empty.
     ///
     /// This function will panic if called after `try_next` or `poll_next` has
-    /// returned None.
+    /// returned `None`.
     pub fn try_next(&mut self) -> Result<Option<T>, TryRecvError> {
         match self.next_message() {
             Poll::Ready(msg) => {
diff --git a/src/oneshot.rs b/src/oneshot.rs
index d3be67e..5f76cee 100644
--- a/src/oneshot.rs
+++ b/src/oneshot.rs
@@ -82,22 +82,23 @@ struct Inner<T> {
 ///
 /// ```
 /// use futures::channel::oneshot;
-/// use futures::future::FutureExt;
-/// use std::thread;
+/// use std::{thread, time::Duration};
 ///
 /// let (sender, receiver) = oneshot::channel::<i32>();
 ///
-/// # let t =
 /// thread::spawn(|| {
-///     let future = receiver.map(|i| {
-///         println!("got: {:?}", i);
-///     });
-///     // ...
-/// # return future;
+///     println!("THREAD: sleeping zzz...");
+///     thread::sleep(Duration::from_millis(1000));
+///     println!("THREAD: i'm awake! sending.");
+///     sender.send(3).unwrap();
 /// });
 ///
-/// sender.send(3).unwrap();
-/// # futures::executor::block_on(t.join().unwrap());
+/// println!("MAIN: doing some useful stuff");
+///
+/// futures::executor::block_on(async {
+///     println!("MAIN: waiting for msg...");
+///     println!("MAIN: got: {:?}", receiver.await)
+/// });
 /// ```
 pub fn channel<T>() -> (Sender<T>, Receiver<T>) {
     let inner = Arc::new(Inner::new());
@@ -126,7 +127,7 @@ impl<T> Inner<T> {
         }
 
         // Note that this lock acquisition may fail if the receiver
-        // is closed and sets the `complete` flag to true, whereupon
+        // is closed and sets the `complete` flag to `true`, whereupon
         // the receiver may call `poll()`.
         if let Some(mut slot) = self.data.try_lock() {
             assert!(slot.is_none());
@@ -358,6 +359,15 @@ impl<T> Sender<T> {
         self.inner.poll_canceled(cx)
     }
 
+    /// Creates a future that resolves when this `Sender`'s corresponding
+    /// [`Receiver`](Receiver) half has hung up.
+    ///
+    /// This is a utility wrapping [`poll_canceled`](Sender::poll_canceled)
+    /// to expose a [`Future`](core::future::Future). 
+    pub fn cancellation(&mut self) -> Cancellation<'_, T> {
+        Cancellation { inner: self }
+    }
+
     /// Tests to see whether this `Sender`'s corresponding `Receiver`
     /// has been dropped.
     ///
@@ -375,6 +385,23 @@ impl<T> Drop for Sender<T> {
     }
 }
 
+/// A future that resolves when the receiving end of a channel has hung up.
+///
+/// This is an `.await`-friendly interface around [`poll_canceled`](Sender::poll_canceled).
+#[must_use = "futures do nothing unless you `.await` or poll them"]
+#[derive(Debug)]
+pub struct Cancellation<'a, T> {
+    inner: &'a mut Sender<T>,
+}
+
+impl<T> Future for Cancellation<'_, T> {
+    type Output = ();
+
+    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
+        self.inner.poll_canceled(cx)
+    }
+}
+
 /// Error returned from a [`Receiver`](Receiver) when the corresponding
 /// [`Sender`](Sender) is dropped.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]