sync: documentation for mpsc channels (#2600)

3 files changed, 42 insertions, 6 deletions

diff --git a/tokio/src/sync/mpsc/mod.rs b/tokio/src/sync/mpsc/mod.rs
index d816557f..52e234a5 100644
--- a/tokio/src/sync/mpsc/mod.rs
+++ b/tokio/src/sync/mpsc/mod.rs
@@ -10,8 +10,13 @@
 //! is rejected and the task will be notified when additional capacity is
 //! available. In other words, the channel provides backpressure.
 //!
-//! Unbounded channels are also available using the `unbounded_channel`
-//! constructor.
+//! This module provides two variants of the channel: A bounded and an unbounded
+//! variant. The bounded variant has a limit on the number of messages that the
+//! channel can store, and if this limit is reached, trying to send another
+//! message will sleep until a message is received from the channel. An unbounded
+//! channel has an infinite capacity, so the `send` method never does any kind of
+//! sleeping. This makes the [`UnboundedSender`] usable from both synchronous and
+//! asynchronous code.
 //!
 //! # Disconnection
 //!
@@ -32,8 +37,32 @@
 //! consumes the channel to completion, at which point the receiver can be
 //! dropped.
 //!
+//! # Communicating between sync and async code
+//!
+//! When you want to communicate between synchronous and asynchronous code, there
+//! are two situations to consider:
+//!
+//! **Bounded channel**: If you need a bounded channel, you should use a bounded
+//! Tokio `mpsc` channel for both directions of communication. To call the async
+//! [`send`][bounded-send] or [`recv`][bounded-recv] methods in sync code, you
+//! will need to use [`Handle::block_on`], which allow you to execute an async
+//! method in synchronous code. This is necessary because a bounded channel may
+//! need to wait for additional capacity to become available.
+//!
+//! **Unbounded channel**: You should use the kind of channel that matches where
+//! the receiver is. So for sending a message _from async to sync_, you should
+//! use [the standard library unbounded channel][std-unbounded] or
+//! [crossbeam][crossbeam-unbounded].  Similarly, for sending a message _from sync
+//! to async_, you should use an unbounded Tokio `mpsc` channel.
+//!
 //! [`Sender`]: crate::sync::mpsc::Sender
 //! [`Receiver`]: crate::sync::mpsc::Receiver
+//! [bounded-send]: crate::sync::mpsc::Sender::send()
+//! [bounded-recv]: crate::sync::mpsc::Receiver::recv()
+//! [`UnboundedSender`]: crate::sync::mpsc::UnboundedSender
+//! [`Handle::block_on`]: crate::runtime::Handle::block_on()
+//! [std-unbounded]: std::sync::mpsc::channel
+//! [crossbeam-unbounded]: https://docs.rs/crossbeam/*/crossbeam/channel/fn.unbounded.html
 
 pub(super) mod block;
 
diff --git a/tokio/src/sync/mpsc/unbounded.rs b/tokio/src/sync/mpsc/unbounded.rs
index ba543fe4..1b2288ab 100644
--- a/tokio/src/sync/mpsc/unbounded.rs
+++ b/tokio/src/sync/mpsc/unbounded.rs
@@ -163,9 +163,13 @@ impl<T> UnboundedSender<T> {
 
     /// Attempts to send a message on this `UnboundedSender` without blocking.
     ///
+    /// This method is not marked async because sending a message to an unbounded channel
+    /// never requires any form of waiting. Because of this, the `send` method can be
+    /// used in both synchronous and asynchronous code without problems.
+    ///
     /// If the receive half of the channel is closed, either due to [`close`]
-    /// being called or the [`UnboundedReceiver`] having been dropped,
-    /// the function returns an error. The error includes the value passed to `send`.
+    /// being called or the [`UnboundedReceiver`] having been dropped, this
+    /// function returns an error. The error includes the value passed to `send`.
     ///
     /// [`close`]: UnboundedReceiver::close
     /// [`UnboundedReceiver`]: UnboundedReceiver
diff --git a/tokio/src/sync/oneshot.rs b/tokio/src/sync/oneshot.rs
index 4b033ac3..54cd5b76 100644
--- a/tokio/src/sync/oneshot.rs
+++ b/tokio/src/sync/oneshot.rs
@@ -144,8 +144,11 @@ impl<T> Sender<T> {
     /// Attempts to send a value on this channel, returning it back if it could
     /// not be sent.
     ///
-    /// The function consumes `self` as only one value may ever be sent on a
-    /// one-shot channel.
+    /// This method consumes `self` as only one value may ever be sent on a oneshot
+    /// channel. It is not marked async because sending a message to an oneshot
+    /// channel never requires any form of waiting.  Because of this, the `send`
+    /// method can be used in both synchronous and asynchronous code without
+    /// problems.
     ///
     /// 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