//! will want to make use of some form of **interior mutability** through the
//! [`Cell`] or [`RefCell`] types.
//!
+//! ## Naming threads
+//!
+//! Threads are able to have associated names for identification purposes. For example, the thread
+//! name is used in panic messages. By default, spawned threads are unnamed. To specify a name for
+//! a thread, build the thread with [`Builder`] and pass the desired thread name to
+//! [`Builder::name`]. To retrieve the thread name from within the thread, use [`Thread::name`].
+//!
+//! ## Stack size
+//!
+//! The default stack size for spawned threads is 2 MiB, though this particular stack size is
+//! subject to change in the future. There are two ways to manually specify the stack size for
+//! spawned threads:
+//!
+//! * Build the thread with [`Builder`] and pass the desired stack size to [`Builder::stack_size`].
+//! * Set the `RUST_MIN_STACK` environment variable to an integer representing the desired stack
+//! size (in bytes).
+//!
+//! Note that the stack size of the main thread is *not* determined by Rust.
+//!
//! [channels]: ../../std/sync/mpsc/index.html
//! [`Arc`]: ../../std/sync/struct.Arc.html
//! [`spawn`]: ../../std/thread/fn.spawn.html
//! [`Err`]: ../../std/result/enum.Result.html#variant.Err
//! [`panic!`]: ../../std/macro.panic.html
//! [`Builder`]: ../../std/thread/struct.Builder.html
+//! [`Builder::stack_size`]: ../../std/thread/struct.Builder.html#method.stack_size
+//! [`Builder::name`]: ../../std/thread/struct.Builder.html#method.name
//! [`thread::current`]: ../../std/thread/fn.current.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
+//! [`Thread::name`]: ../../std/thread/struct.Thread.html#method.name
//! [`thread::park_timeout`]: ../../std/thread/fn.park_timeout.html
//! [`Cell`]: ../cell/struct.Cell.html
//! [`RefCell`]: ../cell/struct.RefCell.html
///
/// 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 overridden 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.
+/// - [`name`]: specifies an [associated name for the thread][naming-threads]
+/// - [`stack_size`]: specifies the [desired stack size for the thread][stack-size]
///
/// The [`spawn`] method will take ownership of the builder and create an
/// [`io::Result`] to the thread handle with the given configuration.
/// [`spawn`]: ../../std/thread/struct.Builder.html#method.spawn
/// [`io::Result`]: ../../std/io/type.Result.html
/// [`unwrap`]: ../../std/result/enum.Result.html#method.unwrap
+/// [naming-threads]: ./index.html#naming-threads
+/// [stack-size]: ./index.html#stack-size
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Debug)]
pub struct Builder {
/// Names the thread-to-be. Currently the name is used for identification
/// only in panic messages.
///
+ /// For more information about named threads, see
+ /// [this module-level documentation][naming-threads].
+ ///
/// # Examples
///
/// ```
///
/// handler.join().unwrap();
/// ```
+ ///
+ /// [naming-threads]: ./index.html#naming-threads
#[stable(feature = "rust1", since = "1.0.0")]
pub fn name(mut self, name: String) -> Builder {
self.name = Some(name);
/// The actual stack size may be greater than this value if
/// the platform specifies minimal stack size.
///
+ /// For more information about the stack size for threads, see
+ /// [this module-level documentation][stack-size].
+ ///
/// # Examples
///
/// ```
///
/// let builder = thread::Builder::new().stack_size(32 * 1024);
/// ```
+ ///
+ /// [stack-size]: ./index.html#stack-size
#[stable(feature = "rust1", since = "1.0.0")]
pub fn stack_size(mut self, size: usize) -> Builder {
self.stack_size = Some(size);
/// Gets the thread's name.
///
+ /// For more information about named threads, see
+ /// [this module-level documentation][naming-threads].
+ ///
/// # Examples
///
/// Threads by default have no name specified:
///
/// handler.join().unwrap();
/// ```
+ ///
+ /// [naming-threads]: ./index.html#naming-threads
#[stable(feature = "rust1", since = "1.0.0")]
pub fn name(&self) -> Option<&str> {
self.cname().map(|s| unsafe { str::from_utf8_unchecked(s.to_bytes()) } )