sync: oneshot::Receiver::is_empty()

this commit introduces a new method to
`tokio::sync::oneshot::Receiver<T>`.

this method returns true if the channel has no messages waiting to be
received. this is similar to the existing
`tokio::sync::mpsc::Receiver::is_empty()` and
`tokio::sync::broadcast::Receiver::is_empty()` methods.

see:
* https://docs.rs/tokio/latest/tokio/sync/broadcast/struct.Receiver.html#method.is_empty
* https://docs.rs/tokio/latest/tokio/sync/mpsc/struct.Receiver.html#method.is_empty
* tokio-rs#7137 (comment)

Signed-off-by: katelyn martin <[email protected]>

Author: cratelyn

tokio/src/sync/oneshot.rs

@@ -931,6 +931,51 @@ impl<T> Receiver<T> {
         }
     }
 
+    /// Checks if a channel is empty.
+    ///
+    /// This method returns `true` if the channel has no messages.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use tokio::sync::oneshot;
+    ///
+    /// #[tokio::main]
+    /// async fn main() {
+    ///     let (tx, mut rx) = oneshot::channel();
+    ///     assert!(rx.is_empty());
+    ///
+    ///     tx.send(0).unwrap();
+    ///     assert!(!rx.is_empty());
+    ///
+    ///     let _ = (&mut rx).await;
+    ///     assert!(rx.is_empty());
+    /// }
+    /// ```
+    pub fn is_empty(&self) -> bool {
+        if let Some(inner) = self.inner.as_ref() {
+            let state = State::load(&inner.state, Acquire);
+            if state.is_complete() {
+                // SAFETY: If `state.is_complete()` returns true, then the
+                // `VALUE_SENT` bit has been set and the sender side of the
+                // channel will no longer attempt to access the inner
+                // `UnsafeCell`. Therefore, it is now safe for us to access the
+                // cell.
+                //
+                // The channel is empty if it does not have a value.
+                unsafe { !inner.has_value() }
+            } else if state.is_closed() {
+                // The receiver closed the channel...
+                true
+            } else {
+                // No value has been sent yet.
+                true
+            }
+        } else {
+            true
+        }
+    }
+
     /// Attempts to receive a value.
     ///
     /// If a pending value exists in the channel, it is returned. If no value
@@ -1233,6 +1278,19 @@ impl<T> Inner<T> {
     unsafe fn consume_value(&self) -> Option<T> {
         self.value.with_mut(|ptr| (*ptr).take())
     }
+
+    /// Returns true if there is a value. This function does not check `state`.
+    ///
+    /// # Safety
+    ///
+    /// Calling this method concurrently on multiple threads will result in a
+    /// data race. The `VALUE_SENT` state bit is used to ensure that only the
+    /// sender *or* the receiver will call this method at a given point in time.
+    /// If `VALUE_SENT` is not set, then only the sender may call this method;
+    /// if it is set, then only the receiver may call this method.
+    unsafe fn has_value(&self) -> bool {
+        self.value.with(|ptr| (*ptr).is_some())
+    }
 }
 
 unsafe impl<T: Send> Send for Inner<T> {}

tokio/tests/sync_oneshot.rs

@@ -292,3 +292,41 @@ fn sender_changes_task() {
 
     assert_ready!(task2.enter(|cx, _| tx.poll_closed(cx)));
 }
+
+#[test]
+fn receiver_is_empty_send() {
+    let (tx, mut rx) = oneshot::channel::<i32>();
+
+    assert!(rx.is_empty(), "channel IS empty before value is sent");
+    tx.send(17).unwrap();
+    assert!(!rx.is_empty(), "channel is NOT empty after value is sent");
+
+    let mut task = task::spawn(());
+    let poll = task.enter(|cx, _| Pin::new(&mut rx).poll(cx));
+    assert_ready_eq!(poll, Ok(17));
+
+    assert!(rx.is_empty(), "channel IS empty after value is read");
+}
+
+#[test]
+fn receiver_is_empty_drop() {
+    let (tx, mut rx) = oneshot::channel::<i32>();
+
+    assert!(rx.is_empty(), "channel IS empty before sender is dropped");
+    drop(tx);
+    assert!(rx.is_empty(), "channel IS empty after sender is dropped");
+
+    let mut task = task::spawn(());
+    let poll = task.enter(|cx, _| Pin::new(&mut rx).poll(cx));
+    assert_ready_err!(poll);
+
+    assert!(rx.is_empty(), "channel IS empty after value is read");
+}
+
+#[test]
+fn receiver_is_empty_rx_close() {
+    let (_tx, mut rx) = oneshot::channel::<i32>();
+    assert!(rx.is_empty());
+    rx.close();
+    assert!(rx.is_empty());
+}