diff options
author | Carl Lerche <me@carllerche.com> | 2019-11-30 09:35:23 -0800 |
---|---|---|
committer | GitHub <noreply@github.com> | 2019-11-30 09:35:23 -0800 |
commit | 417460cf8618452717af625bcbb7649a2698f099 (patch) | |
tree | b409392f108b068720b4f53566001c2cac2a19f0 /tokio/src/sync/mpsc | |
parent | adaba1a0bc16d56af3c0314cbe6b7db0aae8a253 (diff) |
doc: expand `mpsc::Sender::send` API documentation (#1865)
Includes more description, lists errors, and examples.
Closes #1579
Diffstat (limited to 'tokio/src/sync/mpsc')
-rw-r--r-- | tokio/src/sync/mpsc/bounded.rs | 81 |
1 files changed, 79 insertions, 2 deletions
diff --git a/tokio/src/sync/mpsc/bounded.rs b/tokio/src/sync/mpsc/bounded.rs index d635e138..b2b2df9f 100644 --- a/tokio/src/sync/mpsc/bounded.rs +++ b/tokio/src/sync/mpsc/bounded.rs @@ -181,8 +181,68 @@ impl<T> Sender<T> { self.chan.poll_ready(cx).map_err(|_| ClosedError::new()) } - /// Attempts to send a message on this `Sender`, returning the message - /// if there was an error. + /// Attempts to immediately send a message on this `Sender` + /// + /// This method differs from [`send`] by returning immediately if the channel's + /// buffer is full or no receiver is waiting to acquire some data. Compared + /// with [`send`], this function has two failure cases instead of one (one for + /// disconnection, one for a full buffer). + /// + /// This function may be paired with [`poll_ready`] in order to wait for + /// channel capacity before trying to send a value. + /// + /// # Errors + /// + /// If the channel capacity has been reached, i.e., the channel has `n` + /// buffered values where `n` is the argument passed to [`channel`], then an + /// error is returned. + /// + /// If the receive half of the channel is closed, either due to [`close`] + /// being called or the [`Receiver`] handle dropping, the function returns + /// an error. The error includes the value passed to `send`. + /// + /// [`send`]: Sender::send + /// [`poll_ready`]: Sender::poll_ready + /// [`channel`]: channel + /// [`close`]: Receiver::close + /// + /// # Examples + /// + /// ``` + /// use tokio::sync::mpsc; + /// + /// #[tokio::main] + /// async fn main() { + /// // Create a channel with buffer size 1 + /// let (mut tx1, mut rx) = mpsc::channel(1); + /// let mut tx2 = tx1.clone(); + /// + /// tokio::spawn(async move { + /// tx1.send(1).await.unwrap(); + /// tx1.send(2).await.unwrap(); + /// // task waits until the receiver receives a value. + /// }); + /// + /// tokio::spawn(async move { + /// // This will return an error and send + /// // no message if the buffer is full + /// let _ = tx2.try_send(3); + /// }); + /// + /// let mut msg; + /// msg = rx.recv().await.unwrap(); + /// println!("message {} received", msg); + /// + /// msg = rx.recv().await.unwrap(); + /// println!("message {} received", msg); + /// + /// // Third message may have never been sent + /// match rx.recv().await { + /// Some(msg) => println!("message {} received", msg), + /// None => println!("the third message was never sent"), + /// } + /// } + /// ``` pub fn try_send(&mut self, message: T) -> Result<(), TrySendError<T>> { self.chan.try_send(message)?; Ok(()) @@ -190,6 +250,23 @@ impl<T> Sender<T> { /// Send a value, waiting until there is capacity. /// + /// A successful send occurs when it is determined that the other end of the + /// channel has not hung up already. An unsuccessful send would be one where + /// the corresponding receiver has already been closed. Note that a return + /// value of `Err` means that the data will never be received, but a return + /// value of `Ok` does not mean that the data will be received. It is + /// possible for the corresponding receiver to hang up immediately after + /// this function returns `Ok`. + /// + /// # Errors + /// + /// If the receive half of the channel is closed, either due to [`close`] + /// being called or the [`Receiver`] handle dropping, the function returns + /// an error. The error includes the value passed to `send`. + /// + /// [`close`]: Receiver::close + /// [`Receiver`]: Receiver + /// /// # Examples /// /// In the following example, each call to `send` will block until the |