Revise std::thread API to join by default

This commit is part of a series that introduces a `std::thread` API to
replace `std::task`.

In the new API, `spawn` returns a `JoinGuard`, which by default will
join the spawned thread when dropped. It can also be used to join
explicitly at any time, returning the thread's result. Alternatively,
the spawned thread can be explicitly detached (so no join takes place).

As part of this change, Rust processes now terminate when the main
thread exits, even if other detached threads are still running, moving
Rust closer to standard threading models. This new behavior may break code
that was relying on the previously implicit join-all.

In addition to the above, the new thread API also offers some built-in
support for building blocking abstractions in user space; see the module
doc for details.

Closes #18000

[breaking-change]

1 files changed, 6 insertions, 4 deletions

diff --git a/src/libstd/sync/atomic.rs b/src/libstd/sync/atomic.rs
index fe5b962fa4b..26778ef70b3 100644
--- a/src/libstd/sync/atomic.rs
+++ b/src/libstd/sync/atomic.rs
@@ -42,14 +42,15 @@
 //! ```
 //! use std::sync::Arc;
 //! use std::sync::atomic::{AtomicUint, SeqCst};
+//! use std::thread::Thread;
 //!
 //! fn main() {
 //!     let spinlock = Arc::new(AtomicUint::new(1));
 //!
 //!     let spinlock_clone = spinlock.clone();
-//!     spawn(move|| {
+//!     Thread::spawn(move|| {
 //!         spinlock_clone.store(0, SeqCst);
-//!     });
+//!     }).detach();
 //!
 //!     // Wait for the other task to release the lock
 //!     while spinlock.load(SeqCst) != 0 {}
@@ -61,6 +62,7 @@
 //! ```
 //! use std::sync::Arc;
 //! use std::sync::atomic::{AtomicOption, SeqCst};
+//! use std::thread::Thread;
 //!
 //! fn main() {
 //!     struct BigObject;
@@ -68,14 +70,14 @@
 //!     let shared_big_object = Arc::new(AtomicOption::empty());
 //!
 //!     let shared_big_object_clone = shared_big_object.clone();
-//!     spawn(move|| {
+//!     Thread::spawn(move|| {
 //!         let unwrapped_big_object = shared_big_object_clone.take(SeqCst);
 //!         if unwrapped_big_object.is_some() {
 //!             println!("got a big object from another task");
 //!         } else {
 //!             println!("other task hasn't sent big object yet");
 //!         }
-//!     });
+//!     }).detach();
 //!
 //!     shared_big_object.swap(box BigObject, SeqCst);
 //! }