oneshot channel first commit

Author: connortsui20

library/std/src/sync/mod.rs

@@ -224,6 +224,8 @@ pub use self::poison::{MappedMutexGuard, MappedRwLockReadGuard, MappedRwLockWrit
 #[unstable(feature = "mpmc_channel", issue = "126840")]
 pub mod mpmc;
 pub mod mpsc;
+#[unstable(feature = "oneshot_channel", issue = "143674")]
+pub mod oneshot;
 
 #[unstable(feature = "sync_poison_mod", issue = "134646")]
 pub mod poison;

library/std/src/sync/oneshot.rs

@@ -0,0 +1,232 @@
+//! A single-producer, single-consumer (oneshot) channel.
+//!
+//! TODO more docs.
+
+use crate::sync::mpmc;
+use crate::sync::mpsc::{RecvError, SendError};
+use crate::time::{Duration, Instant};
+use crate::{error, fmt};
+
+/// Creates a new oneshot channel, returning the sender/receiver halves.
+///
+/// TODO more docs.
+#[must_use]
+#[unstable(feature = "oneshot_channel", issue = "143674")]
+pub fn channel<T>() -> (Sender<T>, Receiver<T>) {
+    let (tx, rx) = mpmc::channel();
+    (Sender { inner: tx }, Receiver { inner: rx })
+}
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+// Sender
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+/// The sending half of a oneshot channel.
+///
+/// TODO more docs.
+#[unstable(feature = "oneshot_channel", issue = "143674")]
+pub struct Sender<T> {
+    /// The `oneshot` channel is simply a wrapper around a `mpmc` channel.
+    inner: mpmc::Sender<T>,
+}
+
+/// The sending end of the channel can be sent between threads, as long as it is not used to
+/// receive non-sendable things.
+#[unstable(feature = "oneshot_channel", issue = "143674")]
+unsafe impl<T: Send> Send for Sender<T> {}
+
+/// FIXME: Try to boil down <https://github.com/rust-lang/rust/pull/111087> into a doc comment.
+#[unstable(feature = "oneshot_channel", issue = "143674")]
+unsafe impl<T: Send> Sync for Sender<T> {}
+
+impl<T> Sender<T> {
+    /// Attempts to send a value through this channel. This can only fail if the corresponding
+    /// `Receiver<T>` has been dropped.
+    ///
+    /// This method is non-blocking (wait-free).
+    #[unstable(feature = "oneshot_channel", issue = "143674")]
+    pub fn send(self, t: T) -> Result<(), SendError<T>> {
+        self.inner.send(t)
+    }
+}
+
+#[unstable(feature = "oneshot_channel", issue = "143674")]
+impl<T> fmt::Debug for Sender<T> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.pad("Sender { .. }")
+    }
+}
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+// Receiver
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+/// The receiving half of a oneshot channel.
+///
+/// TODO more docs.
+#[unstable(feature = "oneshot_channel", issue = "143674")]
+pub struct Receiver<T> {
+    /// The `oneshot` channel is simply a wrapper around a `mpmc` channel.
+    inner: mpmc::Receiver<T>,
+}
+
+/// The receiving end of the channel can be sent between threads, as long as it is not used to
+/// receive non-sendable things.
+#[unstable(feature = "oneshot_channel", issue = "143674")]
+unsafe impl<T: Send> Send for Receiver<T> {}
+
+/// FIXME: Why is `mpsc::Receiver` !Sync but `mpmc::Receiver` is? Write this in a doc comment.
+#[unstable(feature = "oneshot_channel", issue = "143674")]
+impl<T> !Sync for Receiver<T> {}
+
+impl<T> Receiver<T> {
+    /// Receives the value from the sending end, blocking the calling thread until it gets it.
+    ///
+    /// Can only fail if the corresponding `Sender<T>` has been dropped.
+    #[unstable(feature = "oneshot_channel", issue = "143674")]
+    pub fn recv(self) -> Result<T, RecvError> {
+        self.inner.recv()
+    }
+
+    // Fallable methods.
+
+    /// Attempts to return a pending value on this receiver without blocking.
+    ///
+    /// TODO examples.
+    #[unstable(feature = "oneshot_channel", issue = "143674")]
+    pub fn try_recv(self) -> Result<T, TryRecvError<T>> {
+        self.inner.try_recv().map_err(|err| match err {
+            mpmc::TryRecvError::Empty => TryRecvError::Empty(self),
+            mpmc::TryRecvError::Disconnected => TryRecvError::Disconnected,
+        })
+    }
+
+    /// Attempts to wait for a value on this receiver, returning an error if the corresponding
+    /// [`Sender`] half of this channel has been dropped, or if it waits more than `timeout`.
+    ///
+    /// TODO examples.
+    #[unstable(feature = "oneshot_channel", issue = "143674")]
+    pub fn recv_timeout(self, timeout: Duration) -> Result<T, RecvTimeoutError<T>> {
+        self.inner.recv_timeout(timeout).map_err(|err| match err {
+            mpmc::RecvTimeoutError::Timeout => RecvTimeoutError::Timeout(self),
+            mpmc::RecvTimeoutError::Disconnected => RecvTimeoutError::Disconnected,
+        })
+    }
+
+    /// Attempts to wait for a value on this receiver, returning an error if the corresponding
+    /// [`Sender`] half of this channel has been dropped, or if `deadline` is reached.
+    ///
+    /// TODO examples.
+    #[unstable(feature = "oneshot_channel", issue = "143674")]
+    pub fn recv_deadline(self, deadline: Instant) -> Result<T, RecvTimeoutError<T>> {
+        self.inner.recv_deadline(deadline).map_err(|err| match err {
+            mpmc::RecvTimeoutError::Timeout => RecvTimeoutError::Timeout(self),
+            mpmc::RecvTimeoutError::Disconnected => RecvTimeoutError::Disconnected,
+        })
+    }
+}
+
+#[unstable(feature = "oneshot_channel", issue = "143674")]
+impl<T> fmt::Debug for Receiver<T> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.pad("Receiver { .. }")
+    }
+}
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+// Receiver Errors
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+/// An error returned from the [`try_recv`](Receiver::try_recv) method.
+#[unstable(feature = "oneshot_channel", issue = "143674")]
+pub enum TryRecvError<T> {
+    /// The [`Sender`] has not sent a message yet, but it might in the future (as it has not yet
+    /// disconnected). This variant contains the [`Receiver`] that [`try_recv`](Receiver::try_recv)
+    /// took ownership over.
+    Empty(Receiver<T>),
+    /// The corresponding [`Sender`] half of this channel has become disconnected, and there will
+    /// never be any more data sent over the channel.
+    Disconnected,
+}
+
+/// An error returned from the [`recv_timeout`](Receiver::recv_timeout) or
+/// [`recv_deadline`](Receiver::recv_deadline) methods.
+#[unstable(feature = "oneshot_channel", issue = "143674")]
+pub enum RecvTimeoutError<T> {
+    /// The [`Sender`] has not sent a message yet, but it might in the future (as it has not yet
+    /// disconnected). This variant contains the [`Receiver`] that either
+    /// [`recv_timeout`](Receiver::recv_timeout) or [`recv_deadline`](Receiver::recv_deadline) took
+    /// ownership over.
+    Timeout(Receiver<T>),
+    /// The corresponding [`Sender`] half of this channel has become disconnected, and there will
+    /// never be any more data sent over the channel.
+    Disconnected,
+}
+
+#[unstable(feature = "oneshot_channel", issue = "143674")]
+impl<T> fmt::Debug for TryRecvError<T> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        "TryRecvError(..)".fmt(f)
+    }
+}
+
+#[unstable(feature = "oneshot_channel", issue = "143674")]
+impl<T> fmt::Display for TryRecvError<T> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match *self {
+            TryRecvError::Empty(..) => "receiving on an empty channel".fmt(f),
+            TryRecvError::Disconnected => "receiving on a closed channel".fmt(f),
+        }
+    }
+}
+
+#[unstable(feature = "oneshot_channel", issue = "143674")]
+impl<T> error::Error for TryRecvError<T> {}
+
+#[unstable(feature = "oneshot_channel", issue = "143674")]
+impl<T> From<RecvError> for TryRecvError<T> {
+    /// Converts a `RecvError` into a `TryRecvError`.
+    ///
+    /// This conversion always returns `TryRecvError::Disconnected`.
+    ///
+    /// No data is allocated on the heap.
+    fn from(err: RecvError) -> TryRecvError<T> {
+        match err {
+            RecvError => TryRecvError::Disconnected,
+        }
+    }
+}
+
+#[unstable(feature = "oneshot_channel", issue = "143674")]
+impl<T> fmt::Debug for RecvTimeoutError<T> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        "RecvTimeoutError(..)".fmt(f)
+    }
+}
+
+#[unstable(feature = "oneshot_channel", issue = "143674")]
+impl<T> fmt::Display for RecvTimeoutError<T> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match *self {
+            RecvTimeoutError::Timeout(..) => "timed out waiting on channel".fmt(f),
+            RecvTimeoutError::Disconnected => "receiving on a closed channel".fmt(f),
+        }
+    }
+}
+
+#[unstable(feature = "oneshot_channel", issue = "143674")]
+impl<T> error::Error for RecvTimeoutError<T> {}
+
+#[unstable(feature = "oneshot_channel", issue = "143674")]
+impl<T> From<RecvError> for RecvTimeoutError<T> {
+    /// Converts a `RecvError` into a `RecvTimeoutError`.
+    ///
+    /// This conversion always returns `RecvTimeoutError::Disconnected`.
+    ///
+    /// No data is allocated on the heap.
+    fn from(err: RecvError) -> RecvTimeoutError<T> {
+        match err {
+            RecvError => RecvTimeoutError::Disconnected,
+        }
+    }
+}