mirror of
https://github.com/tokio-rs/tokio.git
synced 2026-08-20 00:00:08 +02:00
doc: Sort methods on mpsc::Sender in doc (#2379)
This commit is contained in:
nasa
+197
-200
@@ -196,6 +196,203 @@ impl<T> Sender<T> {
|
||||
Sender { chan }
|
||||
}
|
||||
|
||||
/// Sends 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
|
||||
/// previously sent value was received.
|
||||
///
|
||||
/// ```rust
|
||||
/// use tokio::sync::mpsc;
|
||||
///
|
||||
/// #[tokio::main]
|
||||
/// async fn main() {
|
||||
/// let (mut tx, mut rx) = mpsc::channel(1);
|
||||
///
|
||||
/// tokio::spawn(async move {
|
||||
/// for i in 0..10 {
|
||||
/// if let Err(_) = tx.send(i).await {
|
||||
/// println!("receiver dropped");
|
||||
/// return;
|
||||
/// }
|
||||
/// }
|
||||
/// });
|
||||
///
|
||||
/// while let Some(i) = rx.recv().await {
|
||||
/// println!("got = {}", i);
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
pub async fn send(&mut self, value: T) -> Result<(), SendError<T>> {
|
||||
use crate::future::poll_fn;
|
||||
|
||||
if poll_fn(|cx| self.poll_ready(cx)).await.is_err() {
|
||||
return Err(SendError(value));
|
||||
}
|
||||
|
||||
match self.try_send(value) {
|
||||
Ok(()) => Ok(()),
|
||||
Err(TrySendError::Full(_)) => unreachable!(),
|
||||
Err(TrySendError::Closed(value)) => Err(SendError(value)),
|
||||
}
|
||||
}
|
||||
|
||||
/// 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(())
|
||||
}
|
||||
|
||||
/// Sends a value, waiting until there is capacity, but only for a limited time.
|
||||
///
|
||||
/// Shares the same success and error conditions as [`send`], adding one more
|
||||
/// condition for an unsuccessful send, which is when the provided timeout has
|
||||
/// elapsed, and there is no capacity available.
|
||||
///
|
||||
/// [`send`]: Sender::send
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// If the receive half of the channel is closed, either due to [`close`]
|
||||
/// being called or the [`Receiver`] having been dropped,
|
||||
/// 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_timeout` will block until the
|
||||
/// previously sent value was received, unless the timeout has elapsed.
|
||||
///
|
||||
/// ```rust
|
||||
/// use tokio::sync::mpsc;
|
||||
/// use tokio::time::{delay_for, Duration};
|
||||
///
|
||||
/// #[tokio::main]
|
||||
/// async fn main() {
|
||||
/// let (mut tx, mut rx) = mpsc::channel(1);
|
||||
///
|
||||
/// tokio::spawn(async move {
|
||||
/// for i in 0..10 {
|
||||
/// if let Err(e) = tx.send_timeout(i, Duration::from_millis(100)).await {
|
||||
/// println!("send error: #{:?}", e);
|
||||
/// return;
|
||||
/// }
|
||||
/// }
|
||||
/// });
|
||||
///
|
||||
/// while let Some(i) = rx.recv().await {
|
||||
/// println!("got = {}", i);
|
||||
/// delay_for(Duration::from_millis(200)).await;
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
#[cfg(feature = "time")]
|
||||
#[cfg_attr(docsrs, doc(cfg(feature = "time")))]
|
||||
pub async fn send_timeout(
|
||||
&mut self,
|
||||
value: T,
|
||||
timeout: Duration,
|
||||
) -> Result<(), SendTimeoutError<T>> {
|
||||
use crate::future::poll_fn;
|
||||
|
||||
match crate::time::timeout(timeout, poll_fn(|cx| self.poll_ready(cx))).await {
|
||||
Err(_) => {
|
||||
return Err(SendTimeoutError::Timeout(value));
|
||||
}
|
||||
Ok(Err(_)) => {
|
||||
return Err(SendTimeoutError::Closed(value));
|
||||
}
|
||||
Ok(_) => {}
|
||||
}
|
||||
|
||||
match self.try_send(value) {
|
||||
Ok(()) => Ok(()),
|
||||
Err(TrySendError::Full(_)) => unreachable!(),
|
||||
Err(TrySendError::Closed(value)) => Err(SendTimeoutError::Closed(value)),
|
||||
}
|
||||
}
|
||||
|
||||
/// Returns `Poll::Ready(Ok(()))` when the channel is able to accept another item.
|
||||
///
|
||||
/// If the channel is full, then `Poll::Pending` is returned and the task is notified when a
|
||||
@@ -279,204 +476,4 @@ impl<T> Sender<T> {
|
||||
false
|
||||
}
|
||||
}
|
||||
|
||||
/// 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(())
|
||||
}
|
||||
|
||||
/// Sends 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`] having been dropped,
|
||||
/// 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
|
||||
/// previously sent value was received.
|
||||
///
|
||||
/// ```rust
|
||||
/// use tokio::sync::mpsc;
|
||||
///
|
||||
/// #[tokio::main]
|
||||
/// async fn main() {
|
||||
/// let (mut tx, mut rx) = mpsc::channel(1);
|
||||
///
|
||||
/// tokio::spawn(async move {
|
||||
/// for i in 0..10 {
|
||||
/// if let Err(_) = tx.send(i).await {
|
||||
/// println!("receiver dropped");
|
||||
/// return;
|
||||
/// }
|
||||
/// }
|
||||
/// });
|
||||
///
|
||||
/// while let Some(i) = rx.recv().await {
|
||||
/// println!("got = {}", i);
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
pub async fn send(&mut self, value: T) -> Result<(), SendError<T>> {
|
||||
use crate::future::poll_fn;
|
||||
|
||||
if poll_fn(|cx| self.poll_ready(cx)).await.is_err() {
|
||||
return Err(SendError(value));
|
||||
}
|
||||
|
||||
match self.try_send(value) {
|
||||
Ok(()) => Ok(()),
|
||||
Err(TrySendError::Full(_)) => unreachable!(),
|
||||
Err(TrySendError::Closed(value)) => Err(SendError(value)),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
cfg_time! {
|
||||
impl<T> Sender<T> {
|
||||
/// Sends a value, waiting until there is capacity, but only for a limited time.
|
||||
///
|
||||
/// Shares the same success and error conditions as [`send`], adding one more
|
||||
/// condition for an unsuccessful send, which is when the provided timeout has
|
||||
/// elapsed, and there is no capacity available.
|
||||
///
|
||||
/// [`send`]: Sender::send
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// If the receive half of the channel is closed, either due to [`close`] being
|
||||
/// called or the [`Receiver`] handle dropping, or if the timeout specified
|
||||
/// elapses before the capacity is available the function returns an error.
|
||||
/// The error includes the value passed to `send_timeout`.
|
||||
///
|
||||
/// [`close`]: Receiver::close
|
||||
/// [`Receiver`]: Receiver
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// In the following example, each call to `send_timeout` will block until the
|
||||
/// previously sent value was received, unless the timeout has elapsed.
|
||||
///
|
||||
/// ```rust
|
||||
/// use tokio::sync::mpsc;
|
||||
/// use tokio::time::{delay_for, Duration};
|
||||
///
|
||||
/// #[tokio::main]
|
||||
/// async fn main() {
|
||||
/// let (mut tx, mut rx) = mpsc::channel(1);
|
||||
///
|
||||
/// tokio::spawn(async move {
|
||||
/// for i in 0..10 {
|
||||
/// if let Err(e) = tx.send_timeout(i, Duration::from_millis(100)).await {
|
||||
/// println!("send error: #{:?}", e);
|
||||
/// return;
|
||||
/// }
|
||||
/// }
|
||||
/// });
|
||||
///
|
||||
/// while let Some(i) = rx.recv().await {
|
||||
/// println!("got = {}", i);
|
||||
/// delay_for(Duration::from_millis(200)).await;
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
pub async fn send_timeout(
|
||||
&mut self,
|
||||
value: T,
|
||||
timeout: Duration,
|
||||
) -> Result<(), SendTimeoutError<T>> {
|
||||
use crate::future::poll_fn;
|
||||
|
||||
match crate::time::timeout(timeout, poll_fn(|cx| self.poll_ready(cx))).await {
|
||||
Err(_) => {
|
||||
return Err(SendTimeoutError::Timeout(value));
|
||||
}
|
||||
Ok(Err(_)) => {
|
||||
return Err(SendTimeoutError::Closed(value));
|
||||
}
|
||||
Ok(_) => {}
|
||||
}
|
||||
|
||||
match self.try_send(value) {
|
||||
Ok(()) => Ok(()),
|
||||
Err(TrySendError::Full(_)) => unreachable!(),
|
||||
Err(TrySendError::Closed(value)) => Err(SendTimeoutError::Closed(value)),
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user