OpenE2K/rust
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Rollup merge of #41994 - gamazeps:thread-builder, r=GuillaumeGomez

Browse Source 
[Doc] Implrove `thread::Builder`'s doc.

Part of #29378 .

- Explains *why* we would use the builder instead ofthe free function.
- Changes the parent-child explanation for a spawned-caller in `thread::Builder::spawn`
- Adds a link to `io::Result` in `thread::Builder`
- Corrects the return type doc in `thread::Builder::spawn`

r? @rust-lang/docs
This commit is contained in:
Mark Simulacrum 2017-05-16 08:18:30 -06:00 committed by GitHub
commit 18171a8861
1 changed files with 38 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
src/libstd/thread/mod.rs
View File

@ -180,8 +180,33 @@ pub use self::local::{LocalKey, LocalKeyState};
// Builder
////////////////////////////////////////////////////////////////////////////////
/// Thread configuration. Provides detailed control over the properties
/// and behavior of new threads.
/// Thread factory, which can be used in order to configure the properties of
/// a new thread.
///
/// Methods can be chained on it in order to configure it.
///
/// The two configurations available are:
///
/// - [`name`]: allows to give a name to the thread which is currently
/// only used in `panic` messages.
/// - [`stack_size`]: specifies the desired stack size. Note that this can
/// be overriden by the OS.
///
/// If the [`stack_size`] field is not specified, the stack size
/// will be the `RUST_MIN_STACK` environment variable. If it is
/// not specified either, a sensible default will be set.
///
/// If the [`name`] field is not specified, the thread will not be named.
///
/// The [`spawn`] method will take ownership of the builder and create an
/// [`io::Result`] to the thread handle with the given configuration.
///
/// The [`thread::spawn`] free function uses a `Builder` with default
/// configuration and [`unwrap`]s its return value.
///
/// You may want to use [`spawn`] instead of [`thread::spawn`], when you want
/// to recover from a failure to launch a thread, indeed the free function will
/// panick where the `Builder` method will return a [`io::Result`].
///
/// # Examples
///
@ -196,6 +221,13 @@ pub use self::local::{LocalKey, LocalKeyState};
///
/// handler.join().unwrap();
/// ```
///
/// [`thread::spawn`]: ../../std/thread/fn.spawn.html
/// [`stack_size`]: ../../std/thread/struct.Builder.html#method.stack_size
/// [`name`]: ../../std/thread/struct.Builder.html#method.name
/// [`spawn`]: ../../std/thread/struct.Builder.html#method.spawn
/// [`io::Result`]: ../../std/io/type.Result.html
/// [`unwrap`]: ../../std/result/enum.Result.html#method.unwrap
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Debug)]
pub struct Builder {
@ -209,11 +241,6 @@ impl Builder {
/// Generates the base configuration for spawning a thread, from which
/// configuration methods can be chained.
///
/// If the [`stack_size`] field is not specified, the stack size
/// will be the `RUST_MIN_STACK` environment variable. If it is
/// not specified either, a sensible default will be set (2MB as
/// of the writting of this doc).
///
/// # Examples
///
/// ```
@ -229,8 +256,6 @@ impl Builder {
///
/// handler.join().unwrap();
/// ```
///
/// [`stack_size`]: ../../std/thread/struct.Builder.html#method.stack_size
#[stable(feature = "rust1", since = "1.0.0")]
pub fn new() -> Builder {
Builder {
@ -280,9 +305,10 @@ impl Builder {
self
}
/// Spawns a new thread, and returns a join handle for it.
/// Spawns a new thread by taking ownership of the `Builder`, and returns an
/// [`io::Result`] to its [`JoinHandle`].
///
/// The child thread may outlive the parent (unless the parent thread
/// The spawned thread may outlive the caller (unless the caller thread
/// is the main thread; the whole process is terminated when the main
/// thread finishes). The join handle can be used to block on
/// termination of the child thread, including recovering its panics.
@ -297,6 +323,7 @@ impl Builder {
///
/// [`spawn`]: ../../std/thread/fn.spawn.html
/// [`io::Result`]: ../../std/io/type.Result.html
/// [`JoinHandle`]: ../../std/thread/struct.JoinHandle.html
///
/// # Examples
///