Auto merge of #52936 - felixrabe:patch-1, r=alexcrichton

Document #39364 – Panic in mpsc::Receiver::recv_timeout

I can still reproduce #39364 with the example code at https://github.com/rust-lang/rust/issues/39364#issuecomment-320637702.

I'm opening this PR in an attempt to document this bug as a known issue in [libstd/sync/mpsc/mod.rs](https://github.com/rust-lang/rust/blob/master/src/libstd/sync/mpsc/mod.rs).

Inputs very much welcome. ([Nightly docs for `recv_timeout`.](https://doc.rust-lang.org/nightly/std/sync/mpsc/struct.Receiver.html?search=#method.recv_timeout))

1 files changed, 28 insertions, 0 deletions

diff --git a/src/libstd/sync/mpsc/mod.rs b/src/libstd/sync/mpsc/mod.rs
index 02a96b01cca..59cf741487e 100644
--- a/src/libstd/sync/mpsc/mod.rs
+++ b/src/libstd/sync/mpsc/mod.rs
@@ -1247,6 +1247,34 @@ impl<T> Receiver<T> {
     /// [`SyncSender`]: struct.SyncSender.html
     /// [`Err`]: ../../../std/result/enum.Result.html#variant.Err
     ///
+    /// # Known Issues
+    ///
+    /// There is currently a known issue (see [`#39364`]) that causes `recv_timeout`
+    /// to panic unexpectedly with the following example:
+    ///
+    /// ```no_run
+    /// use std::sync::mpsc::channel;
+    /// use std::thread;
+    /// use std::time::Duration;
+    ///
+    /// let (tx, rx) = channel::<String>();
+    ///
+    /// thread::spawn(move || {
+    ///     let d = Duration::from_millis(10);
+    ///     loop {
+    ///         println!("recv");
+    ///         let _r = rx.recv_timeout(d);
+    ///     }
+    /// });
+    ///
+    /// thread::sleep(Duration::from_millis(100));
+    /// let _c1 = tx.clone();
+    ///
+    /// thread::sleep(Duration::from_secs(1));
+    /// ```
+    ///
+    /// [`#39364`]: https://github.com/rust-lang/rust/issues/39364
+    ///
     /// # Examples
     ///
     /// Successfully receiving value before encountering timeout: