From 08514b4376eda86f2c05d91334333ebf8caad064 Mon Sep 17 00:00:00 2001 From: Christian Poveda Date: Tue, 25 Apr 2017 17:22:34 -0500 Subject: rewrote the thread struct docs --- src/libstd/thread/mod.rs | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index e37cc7e963e..98452a396aa 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -713,22 +713,27 @@ struct Inner { #[derive(Clone)] #[stable(feature = "rust1", since = "1.0.0")] -/// A handle to a thread. +/// A handle to a thread, its just an abstract reference and as such +/// it can be used to identify a thread (by name, for example). In most +/// usage cases, this struct is not used directly. /// /// # Examples /// /// ``` /// use std::thread; /// -/// let handler = thread::Builder::new() -/// .name("foo".into()) +/// for i in 0..5 { +/// let thread_name = format!("thread_{}", i); +/// thread::Builder::new() +/// .name(thread_name) // Now you can identify which thread panicked +/// // thanks to the handle's name /// .spawn(|| { -/// let thread = thread::current(); -/// println!("thread name: {}", thread.name().unwrap()); +/// if i == 3 { +/// panic!("I'm scared!!!"); +/// } /// }) /// .unwrap(); -/// -/// handler.join().unwrap(); +/// } /// ``` pub struct Thread { inner: Arc, -- cgit 1.4.1-3-g733a5 From bdb6bb9684e5cc874d69d6cd65be3d9fb1e64401 Mon Sep 17 00:00:00 2001 From: Christian Poveda Date: Wed, 26 Apr 2017 00:57:59 -0500 Subject: added move --- src/libstd/thread/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 98452a396aa..aa7ef2da0ae 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -727,7 +727,7 @@ struct Inner { /// thread::Builder::new() /// .name(thread_name) // Now you can identify which thread panicked /// // thanks to the handle's name -/// .spawn(|| { +/// .spawn(move || { /// if i == 3 { /// panic!("I'm scared!!!"); /// } -- cgit 1.4.1-3-g733a5 From cf521211a13ccb7e8ea25af97d0efc3abe6d9070 Mon Sep 17 00:00:00 2001 From: Christian Poveda Date: Wed, 26 Apr 2017 11:54:17 -0500 Subject: restructured docs for thread and added links --- src/libstd/thread/mod.rs | 32 +++++++++++++++++++------------- 1 file changed, 19 insertions(+), 13 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index aa7ef2da0ae..4e49c485f10 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -713,28 +713,34 @@ struct Inner { #[derive(Clone)] #[stable(feature = "rust1", since = "1.0.0")] -/// A handle to a thread, its just an abstract reference and as such -/// it can be used to identify a thread (by name, for example). In most -/// usage cases, this struct is not used directly. +/// A handle to a thread. +/// +/// You can use it to identify a thread (by name, for example). Most of the +/// time, there is no need to directly create a `Thread` struct using the +/// constructor, instead you should use a function like `spawn` to create +/// new threads, see the docs of [`Builder`] and [`spawn`] for more. /// /// # Examples /// /// ``` -/// use std::thread; +/// use std::thread::Builder; /// /// for i in 0..5 { /// let thread_name = format!("thread_{}", i); -/// thread::Builder::new() -/// .name(thread_name) // Now you can identify which thread panicked -/// // thanks to the handle's name -/// .spawn(move || { -/// if i == 3 { -/// panic!("I'm scared!!!"); -/// } -/// }) -/// .unwrap(); +/// Builder::new() +/// .name(thread_name) // Now you can identify which thread panicked +/// // thanks to the handle's name +/// .spawn(move || { +/// if i == 3 { +/// panic!("I'm scared!!!"); +/// } +/// }) +/// .unwrap(); /// } /// ``` +/// [`Builder`]: ../../std/thread/struct.Builder.html +/// [`spawn`]: ../../std/thread/fn.spawn.html + pub struct Thread { inner: Arc, } -- cgit 1.4.1-3-g733a5 From a3998ad6e59a6a833e27e9ea6691d3ecd1e877a1 Mon Sep 17 00:00:00 2001 From: Raphaël Huchet Date: Thu, 4 May 2017 11:11:14 +0200 Subject: Join method returns a thread::Result --- src/libstd/thread/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 4e49c485f10..7fc43a341a8 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -66,7 +66,7 @@ //! let res = child.join(); //! ``` //! -//! The [`join`] method returns a [`Result`] containing [`Ok`] of the final +//! The [`join`] method returns a [`thread::Result`] containing [`Ok`] of the final //! value produced by the child thread, or [`Err`] of the value given to //! a call to [`panic!`] if the child panicked. //! -- cgit 1.4.1-3-g733a5 From 3a07155a9df03ced8c077990a3af0eb7b40d5c8b Mon Sep 17 00:00:00 2001 From: Raphaël Huchet Date: Thu, 4 May 2017 11:33:26 +0200 Subject: create link to Result --- src/libstd/thread/mod.rs | 1 + 1 file changed, 1 insertion(+) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 7fc43a341a8..719b50d1196 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -159,6 +159,7 @@ //! [`panic!`]: ../../std/macro.panic.html //! [`Builder`]: ../../std/thread/struct.Builder.html //! [`thread::current`]: ../../std/thread/fn.current.html +//! [`thread::Result`]: ../../std/thread/struct.Result.html //! [`Thread`]: ../../std/thread/struct.Thread.html //! [`park`]: ../../std/thread/fn.park.html //! [`unpark`]: ../../std/thread/struct.Thread.html#method.unpark -- cgit 1.4.1-3-g733a5 From 93e179a8c132f6aa9790b198cdcdd441424b4a84 Mon Sep 17 00:00:00 2001 From: Raphaël Huchet Date: Thu, 4 May 2017 14:04:03 +0200 Subject: Update mod.rs --- src/libstd/thread/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 719b50d1196..8e7eaa77cd7 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -159,7 +159,7 @@ //! [`panic!`]: ../../std/macro.panic.html //! [`Builder`]: ../../std/thread/struct.Builder.html //! [`thread::current`]: ../../std/thread/fn.current.html -//! [`thread::Result`]: ../../std/thread/struct.Result.html +//! [`thread::Result`]: ../../std/thread/type.Result.html //! [`Thread`]: ../../std/thread/struct.Thread.html //! [`park`]: ../../std/thread/fn.park.html //! [`unpark`]: ../../std/thread/struct.Thread.html#method.unpark -- cgit 1.4.1-3-g733a5 From 68bb5414624d80bec29883c324eb239be73e749d Mon Sep 17 00:00:00 2001 From: Raphaël Huchet Date: Fri, 5 May 2017 12:02:02 +0200 Subject: Add an example to std::thread::Result type --- src/libstd/thread/mod.rs | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 8e7eaa77cd7..2ce5a7262d9 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -863,9 +863,31 @@ impl fmt::Debug for Thread { // JoinHandle //////////////////////////////////////////////////////////////////////////////// +/// A specialized [`Result`] type for threads. +/// /// Indicates the manner in which a thread exited. /// /// A thread that completes without panicking is considered to exit successfully. +/// +/// # Examples +/// +/// ```no_run +/// use std::thread; +/// use std::fs; +/// +/// fn copy_in_thread() -> thread::Result<()> { +/// thread::spawn(move || { fs::copy("foo.txt", "bar.txt").unwrap(); }).join() +/// } +/// +/// fn main() { +/// match copy_in_thread() { +/// Ok(_) => println!("this is fine"), +/// Err(_) => println!("thread panicked"), +/// } +/// } +/// ``` +/// +/// [`Result`]: ../../std/result/enum.Result.html #[stable(feature = "rust1", since = "1.0.0")] pub type Result = ::result::Result>; -- cgit 1.4.1-3-g733a5 From 71aaab1c360f9910238258fb4025b3bd5d5c0645 Mon Sep 17 00:00:00 2001 From: Raphaël Huchet Date: Fri, 5 May 2017 12:07:14 +0200 Subject: Update mod.rs --- src/libstd/thread/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 2ce5a7262d9..279fe0376d2 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -864,7 +864,7 @@ impl fmt::Debug for Thread { //////////////////////////////////////////////////////////////////////////////// /// A specialized [`Result`] type for threads. -/// +/// /// Indicates the manner in which a thread exited. /// /// A thread that completes without panicking is considered to exit successfully. -- cgit 1.4.1-3-g733a5 From 94e4b459efa3e75c190aeb50da88a02661b3d214 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Fri, 5 May 2017 07:02:48 -0700 Subject: std: Prevent deadlocks in doctests on Windows Windows historically has problems with threads panicking and the main thread exiting at the same time, typically causing deadlocks. In the past (#25824) we've joined on threads but this just prevents running the test for now to avoid tampering with the example. --- src/libstd/thread/mod.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 8e7eaa77cd7..9cded2ab289 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -723,7 +723,9 @@ struct Inner { /// /// # Examples /// -/// ``` +/// ```no_run +/// # // Note that this example isn't executed by default because it causes +/// # // deadlocks on Windows unfortunately (see #25824) /// use std::thread::Builder; /// /// for i in 0..5 { -- cgit 1.4.1-3-g733a5 From 12efc9d0faefdd18e715690c7ae30908d92b8fc5 Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Sun, 7 May 2017 16:49:18 +0200 Subject: Improve `thread::panicking` documentaion. Part of #29378 --- src/libstd/thread/mod.rs | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 4cbcfdbc2d7..04cd28df445 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -458,6 +458,16 @@ pub fn yield_now() { /// Determines whether the current thread is unwinding because of panic. /// +/// A common use of this feature is to poison shared resources when writing +/// unsafe code, by checking `panicking` when the `drop` is called. +/// +/// This is usually not needed when writing safe code, as [`Mutex`es][Mutex] +/// already poison themselves when a thread panics while holding the lock. +/// +/// This can also be used in multithreaded applications, in order to send a +/// message to other threads warning that a thread has panicked (e.g. for +/// monitoring purposes). +/// /// # Examples /// /// ```should_panic @@ -486,6 +496,8 @@ pub fn yield_now() { /// panic!() /// } /// ``` +/// +/// [Mutex]: ../../std/sync/struct.Mutex.html #[inline] #[stable(feature = "rust1", since = "1.0.0")] pub fn panicking() -> bool { -- cgit 1.4.1-3-g733a5