From c655348f26a179193f5d6d1a3a2fbe000a046699 Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Tue, 9 May 2017 13:20:04 +0200 Subject: [PATCH 1/5] Add more examples to `thread::spawn` Part of #29378 --- src/libstd/thread/mod.rs | 57 +++++++++++++++++++++++++++++++++++----- 1 file changed, 51 insertions(+), 6 deletions(-) diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 4cbcfdbc2d7f6..c1e894510b912 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -315,6 +315,8 @@ impl Builder { /// thread finishes). The join handle can be used to block on /// termination of the child thread, including recovering its panics. /// + /// For a more complete documentation see [`thread::spawn`][`spawn`]. + /// /// # Errors /// /// Unlike the [`spawn`] free function, this method yields an @@ -392,14 +394,10 @@ impl Builder { /// Panics if the OS fails to create a thread; use [`Builder::spawn`] /// to recover from such errors. /// -/// [`JoinHandle`]: ../../std/thread/struct.JoinHandle.html -/// [`join`]: ../../std/thread/struct.JoinHandle.html#method.join -/// [`Err`]: ../../std/result/enum.Result.html#variant.Err -/// [`panic`]: ../../std/macro.panic.html -/// [`Builder::spawn`]: ../../std/thread/struct.Builder.html#method.spawn -/// /// # Examples /// +/// Simple thread creation. +/// /// ``` /// use std::thread; /// @@ -409,6 +407,53 @@ impl Builder { /// /// handler.join().unwrap(); /// ``` +/// +/// As mentionned in the module documentation, threads are usualy made to +/// communicate using [`channel`s][`channels`], here is how it usually looks. +/// +/// This example also shows how to use `move`, in order to give ownership +/// of values to a thread. +/// +/// ``` +/// use std::thread; +/// use std::sync::mpsc::channel; +/// +/// let (tx, rx) = channel(); +/// +/// let sender = thread::spawn(move || { +/// tx.send("Hello, thread".to_owned()); +/// }); +/// +/// let receiver = thread::spawn(move || { +/// println!("{}", rx.recv().unwrap()); +/// }); +/// +/// sender.join(); +/// receiver.join(); +/// ``` +/// +/// A thread can also return a value through its [`JoinHandle`], you can use +/// this to make asynchronous computations (futures might be more appropriate +/// though). +/// +/// ``` +/// use std::thread; +/// +/// let computation = thread::spawn(|| { +/// // Some expensive computation. +/// 42 +/// }); +/// +/// let result = computation.join().unwrap(); +/// println!("{}", v); +/// ``` +/// +/// [`channels`]: ../../std/sync/mpsc/index.html +/// [`JoinHandle`]: ../../std/thread/struct.JoinHandle.html +/// [`join`]: ../../std/thread/struct.JoinHandle.html#method.join +/// [`Err`]: ../../std/result/enum.Result.html#variant.Err +/// [`panic`]: ../../std/macro.panic.html +/// [`Builder::spawn`]: ../../std/thread/struct.Builder.html#method.spawn #[stable(feature = "rust1", since = "1.0.0")] pub fn spawn(f: F) -> JoinHandle where F: FnOnce() -> T, F: Send + 'static, T: Send + 'static From 9db31206f597444258a46220f39fde13a76453e2 Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Tue, 9 May 2017 13:27:22 +0200 Subject: [PATCH 2/5] Add a link to `thread::Builder` in `thread::spawn` --- src/libstd/thread/mod.rs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index c1e894510b912..19adf3e3c3fd7 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -389,6 +389,10 @@ impl Builder { /// panics, [`join`] will return an [`Err`] containing the argument given to /// [`panic`]. /// +/// This will create a thread using default parameters of [`Builder`], if you +/// want to specify the stack size or the name of the thread, use this API +/// instead. +/// /// # Panics /// /// Panics if the OS fails to create a thread; use [`Builder::spawn`] @@ -454,6 +458,7 @@ impl Builder { /// [`Err`]: ../../std/result/enum.Result.html#variant.Err /// [`panic`]: ../../std/macro.panic.html /// [`Builder::spawn`]: ../../std/thread/struct.Builder.html#method.spawn +/// [`Builder`]: ../../std/thread/struct.Builder.html #[stable(feature = "rust1", since = "1.0.0")] pub fn spawn(f: F) -> JoinHandle where F: FnOnce() -> T, F: Send + 'static, T: Send + 'static From 656efcd3ab029491fd0bd01f3b596516884cabe1 Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Tue, 9 May 2017 16:57:03 +0200 Subject: [PATCH 3/5] Address review comments --- src/libstd/thread/mod.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 19adf3e3c3fd7..dd8892d6660f3 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -400,7 +400,7 @@ impl Builder { /// /// # Examples /// -/// Simple thread creation. +/// Creating a thread. /// /// ``` /// use std::thread; @@ -413,7 +413,7 @@ impl Builder { /// ``` /// /// As mentionned in the module documentation, threads are usualy made to -/// communicate using [`channel`s][`channels`], here is how it usually looks. +/// communicate using [`channels`], here is how it usually looks. /// /// This example also shows how to use `move`, in order to give ownership /// of values to a thread. From 202086e48ff3ca955a52137d71ca8713f39cd5ff Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Tue, 9 May 2017 19:06:56 +0200 Subject: [PATCH 4/5] Fix warnings in examples --- src/libstd/thread/mod.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index dd8892d6660f3..425cb0ada08eb 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -425,15 +425,15 @@ impl Builder { /// let (tx, rx) = channel(); /// /// let sender = thread::spawn(move || { -/// tx.send("Hello, thread".to_owned()); +/// let _ = tx.send("Hello, thread".to_owned()); /// }); /// /// let receiver = thread::spawn(move || { /// println!("{}", rx.recv().unwrap()); /// }); /// -/// sender.join(); -/// receiver.join(); +/// let _ = sender.join(); +/// let _ = receiver.join(); /// ``` /// /// A thread can also return a value through its [`JoinHandle`], you can use @@ -449,7 +449,7 @@ impl Builder { /// }); /// /// let result = computation.join().unwrap(); -/// println!("{}", v); +/// println!("{}", result); /// ``` /// /// [`channels`]: ../../std/sync/mpsc/index.html From fe7b6db39b6efa064ab795103342ca3d298dc943 Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Wed, 10 May 2017 10:44:58 +0200 Subject: [PATCH 5/5] Fix typos in doc --- src/libstd/thread/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 425cb0ada08eb..e81300d6dc89f 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -412,7 +412,7 @@ impl Builder { /// handler.join().unwrap(); /// ``` /// -/// As mentionned in the module documentation, threads are usualy made to +/// As mentioned in the module documentation, threads are usually made to /// communicate using [`channels`], here is how it usually looks. /// /// This example also shows how to use `move`, in order to give ownership