rollup merge of #20615: aturon/stab-2-thread

This commit takes a first pass at stabilizing `std::thread`:

* It removes the `detach` method in favor of two constructors -- `spawn`
  for detached threads, `scoped` for "scoped" (i.e., must-join)
  threads. This addresses some of the surprise/frustrating debug
  sessions with the previous API, in which `spawn` produced a guard that
  on destruction joined the thread (unless `detach` was called).

  The reason to have the division in part is that `Send` will soon not
  imply `'static`, which means that `scoped` thread creation can take a
  closure over *shared stack data* of the parent thread. On the other
  hand, this means that the parent must not pop the relevant stack
  frames while the child thread is running. The `JoinGuard` is used to
  prevent this from happening by joining on drop (if you have not
  already explicitly `join`ed.) The APIs around `scoped` are
  future-proofed for the `Send` changes by taking an additional lifetime
  parameter. With the current definition of `Send`, this is forced to be
  `'static`, but when `Send` changes these APIs will gain their full
  flexibility immediately.

  Threads that are `spawn`ed, on the other hand, are detached from the
  start and do not yield an RAII guard.

  The hope is that, by making `scoped` an explicit opt-in with a very
  suggestive name, it will be drastically less likely to be caught by a
  surprising deadlock due to an implicit join at the end of a scope.

* The module itself is marked stable.

* Existing methods other than `spawn` and `scoped` are marked stable.

The migration path is:

```rust
Thread::spawn(f).detached()
```

becomes

```rust
Thread::spawn(f)
```

while

```rust
let res = Thread::spawn(f);
res.join()
```

becomes

```rust
let res = Thread::scoped(f);
res.join()
```

[breaking-change]

2 files changed, 20 insertions, 18 deletions

diff --git a/src/libstd/io/net/pipe.rs b/src/libstd/io/net/pipe.rs
index 738c70412f7..29295b5751c 100644
--- a/src/libstd/io/net/pipe.rs
+++ b/src/libstd/io/net/pipe.rs
@@ -608,7 +608,7 @@ mod tests {
             let mut a = a;
             let _s = a.accept().unwrap();
             let _ = rx.recv();
-        }).detach();
+        });
 
         let mut b = [0];
         let mut s = UnixStream::connect(&addr).unwrap();
@@ -645,7 +645,7 @@ mod tests {
             let mut a = a;
             let _s = a.accept().unwrap();
             let _ = rx.recv();
-        }).detach();
+        });
 
         let mut s = UnixStream::connect(&addr).unwrap();
         let s2 = s.clone();
@@ -672,7 +672,7 @@ mod tests {
             rx.recv().unwrap();
             assert!(s.write(&[0]).is_ok());
             let _ = rx.recv();
-        }).detach();
+        });
 
         let mut s = a.accept().unwrap();
         s.set_timeout(Some(20));
@@ -716,7 +716,7 @@ mod tests {
                 }
             }
             let _ = rx.recv();
-        }).detach();
+        });
 
         let mut s = a.accept().unwrap();
         s.set_read_timeout(Some(20));
@@ -739,7 +739,7 @@ mod tests {
             rx.recv().unwrap();
             assert!(s.write(&[0]).is_ok());
             let _ = rx.recv();
-        }).detach();
+        });
 
         let mut s = a.accept().unwrap();
         s.set_write_timeout(Some(20));
@@ -766,7 +766,7 @@ mod tests {
             rx.recv().unwrap();
             assert!(s.write(&[0]).is_ok());
             let _ = rx.recv();
-        }).detach();
+        });
 
         let mut s = a.accept().unwrap();
         let s2 = s.clone();
diff --git a/src/libstd/io/net/tcp.rs b/src/libstd/io/net/tcp.rs
index 3e59aaa05ef..b1762ff26fc 100644
--- a/src/libstd/io/net/tcp.rs
+++ b/src/libstd/io/net/tcp.rs
@@ -146,7 +146,7 @@ impl TcpStream {
     ///     timer::sleep(Duration::seconds(1));
     ///     let mut stream = stream2;
     ///     stream.close_read();
-    /// }).detach();
+    /// });
     ///
     /// // wait for some data, will get canceled after one second
     /// let mut buf = [0];
@@ -295,10 +295,12 @@ impl sys_common::AsInner<TcpStreamImp> for TcpStream {
 /// for stream in acceptor.incoming() {
 ///     match stream {
 ///         Err(e) => { /* connection failed */ }
-///         Ok(stream) => Thread::spawn(move|| {
-///             // connection succeeded
-///             handle_client(stream)
-///         }).detach()
+///         Ok(stream) => {
+///             Thread::spawn(move|| {
+///                 // connection succeeded
+///                 handle_client(stream)
+///             });
+///         }
 ///     }
 /// }
 ///
@@ -432,7 +434,7 @@ impl TcpAcceptor {
     ///             Err(e) => panic!("unexpected error: {}", e),
     ///         }
     ///     }
-    /// }).detach();
+    /// });
     ///
     /// # fn wait_for_sigint() {}
     /// // Now that our accept loop is running, wait for the program to be
@@ -1186,7 +1188,7 @@ mod test {
             let mut a = a;
             let _s = a.accept().unwrap();
             let _ = rx.recv().unwrap();
-        }).detach();
+        });
 
         let mut b = [0];
         let mut s = TcpStream::connect(addr).unwrap();
@@ -1223,7 +1225,7 @@ mod test {
             let mut a = a;
             let _s = a.accept().unwrap();
             let _ = rx.recv().unwrap();
-        }).detach();
+        });
 
         let mut s = TcpStream::connect(addr).unwrap();
         let s2 = s.clone();
@@ -1250,7 +1252,7 @@ mod test {
             rx.recv().unwrap();
             assert!(s.write(&[0]).is_ok());
             let _ = rx.recv();
-        }).detach();
+        });
 
         let mut s = a.accept().unwrap();
         s.set_timeout(Some(20));
@@ -1289,7 +1291,7 @@ mod test {
                 }
             }
             let _ = rx.recv();
-        }).detach();
+        });
 
         let mut s = a.accept().unwrap();
         s.set_read_timeout(Some(20));
@@ -1312,7 +1314,7 @@ mod test {
             rx.recv().unwrap();
             assert!(s.write(&[0]).is_ok());
             let _ = rx.recv();
-        }).detach();
+        });
 
         let mut s = a.accept().unwrap();
         s.set_write_timeout(Some(20));
@@ -1340,7 +1342,7 @@ mod test {
             rx.recv().unwrap();
             assert_eq!(s.write(&[0]), Ok(()));
             let _ = rx.recv();
-        }).detach();
+        });
 
         let mut s = a.accept().unwrap();
         let s2 = s.clone();