From cb381c7a9568820ae0f55421ccdbfb79b91b6d67 Mon Sep 17 00:00:00 2001
From: Henry Gomersall <henry.gomersall@smartacoustics.co.uk>
Date: Mon, 8 Mar 2021 12:39:55 +0000
Subject: [PATCH 1/2] docs - added additional documenation on the oneshot, both
 to the module and the receiver, including the receiver fail on sender drop.

---
 tokio/src/sync/oneshot.rs | 106 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 101 insertions(+), 5 deletions(-)

diff --git a/tokio/src/sync/oneshot.rs b/tokio/src/sync/oneshot.rs
index 4954da67ec2..4d3ae6232c3 100644
--- a/tokio/src/sync/oneshot.rs
+++ b/tokio/src/sync/oneshot.rs
@@ -1,6 +1,57 @@
 #![cfg_attr(not(feature = "sync"), allow(dead_code, unreachable_pub))]
 
-//! A channel for sending a single message between asynchronous tasks.
+//! A one-shot channel is used for sending a single message between
+//! asynchronous tasks. The [`channel`] function is used to create a 
+//! [`Sender`] and [`Receiver`] handle pair that form the channel.
+//!
+//! The `Sender` handle is used by the producer to send the value.
+//! The `Receiver` handle is used by the consumer to receive the value.
+//!
+//! Each handle can be used on separate tasks.
+//!
+//! # Examples
+//!
+//! ```
+//! use tokio::sync::oneshot;
+//!
+//! #[tokio::main]
+//! async fn main() {
+//!     let (tx, rx) = oneshot::channel();
+//!
+//!     tokio::spawn(async move {
+//!         if let Err(_) = tx.send(3) {
+//!             println!("the receiver dropped");
+//!         }
+//!     });
+//!
+//!     match rx.await {
+//!         Ok(v) => println!("got = {:?}", v),
+//!         Err(_) => println!("the sender dropped"),
+//!     }
+//! }
+//! ```
+//!
+//! If the sender is dropped without sending, the receiver will fail with
+//! [`error::RecvError`]:
+//!
+//! ```
+//! use tokio::sync::oneshot;
+//!
+//! #[tokio::main]
+//! async fn main() {
+//!     let (tx, rx) = oneshot::channel::<u32>();
+//!
+//!     tokio::spawn(async move {
+//!         drop(tx);
+//!     });
+//!
+//!     match rx.await {
+//!         Ok(_) => panic!("This doesn't happen"),
+//!         Err(_) => println!("the sender dropped"),
+//!     }
+//! }
+//! ```
+
 
 use crate::loom::cell::UnsafeCell;
 use crate::loom::sync::atomic::AtomicUsize;
@@ -14,17 +65,62 @@ use std::sync::atomic::Ordering::{self, AcqRel, Acquire};
 use std::task::Poll::{Pending, Ready};
 use std::task::{Context, Poll, Waker};
 
-/// Sends a value to the associated `Receiver`.
+/// Sends a value to the associated [`Receiver`].
 ///
-/// Instances are created by the [`channel`](fn@channel) function.
+/// A pair of both a [`Sender`] and a [`Receiver`]  are created by the
+/// [`channel`](fn@channel) function.
 #[derive(Debug)]
 pub struct Sender<T> {
     inner: Option<Arc<Inner<T>>>,
 }
 
-/// Receive a value from the associated `Sender`.
+/// Receive a value from the associated [`Sender`].
+///
+/// A pair of both a [`Sender`] and a [`Receiver`]  are created by the
+/// [`channel`](fn@channel) function.
+///
+/// # Examples
+///
+/// ```
+/// use tokio::sync::oneshot;
+///
+/// #[tokio::main]
+/// async fn main() {
+///     let (tx, rx) = oneshot::channel();
+///
+///     tokio::spawn(async move {
+///         if let Err(_) = tx.send(3) {
+///             println!("the receiver dropped");
+///         }
+///     });
 ///
-/// Instances are created by the [`channel`](fn@channel) function.
+///     match rx.await {
+///         Ok(v) => println!("got = {:?}", v),
+///         Err(_) => println!("the sender dropped"),
+///     }
+/// }
+/// ```
+///
+/// If the sender is dropped without sending, the receiver will fail with
+/// [`error::RecvError`]:
+///
+/// ```
+/// use tokio::sync::oneshot;
+///
+/// #[tokio::main]
+/// async fn main() {
+///     let (tx, rx) = oneshot::channel::<u32>();
+///
+///     tokio::spawn(async move {
+///         drop(tx);
+///     });
+///
+///     match rx.await {
+///         Ok(_) => panic!("This doesn't happen"),
+///         Err(_) => println!("the sender dropped"),
+///     }
+/// }
+/// ```
 #[derive(Debug)]
 pub struct Receiver<T> {
     inner: Option<Arc<Inner<T>>>,

From 3465dfbdf42c973ef70115b1e5ccbeed6fdbae87 Mon Sep 17 00:00:00 2001
From: Henry Gomersall <henry.gomersall@smartacoustics.co.uk>
Date: Mon, 8 Mar 2021 13:19:01 +0000
Subject: [PATCH 2/2] Fixed to pass fmt tests.

---
 tokio/src/sync/oneshot.rs | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/tokio/src/sync/oneshot.rs b/tokio/src/sync/oneshot.rs
index 4d3ae6232c3..a2bf5f9b4fb 100644
--- a/tokio/src/sync/oneshot.rs
+++ b/tokio/src/sync/oneshot.rs
@@ -1,7 +1,7 @@
 #![cfg_attr(not(feature = "sync"), allow(dead_code, unreachable_pub))]
 
 //! A one-shot channel is used for sending a single message between
-//! asynchronous tasks. The [`channel`] function is used to create a 
+//! asynchronous tasks. The [`channel`] function is used to create a
 //! [`Sender`] and [`Receiver`] handle pair that form the channel.
 //!
 //! The `Sender` handle is used by the producer to send the value.
@@ -52,7 +52,6 @@
 //! }
 //! ```
 
-
 use crate::loom::cell::UnsafeCell;
 use crate::loom::sync::atomic::AtomicUsize;
 use crate::loom::sync::Arc;