Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Rewrite/reorganize docs for stack size/thread names for spawned threads. #43848

Merged
merged 3 commits into from
Aug 15, 2017
Merged

Rewrite/reorganize docs for stack size/thread names for spawned threads. #43848

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
150713c
Rewrite docs for stack size/thread names for spawned threads.
frewsxcv Aug 13, 2017
10bd80d
Indicate thread names get passed to the OS.
frewsxcv Aug 13, 2017
6594601
Indicate which stack size option has precedence.
frewsxcv Aug 14, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 41 additions & 10 deletions src/libstd/thread/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,25 @@
//! 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`].
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd note here that the name is also provided to the OS where applicable (e.g. pthread_setname_np).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this seem fine? 10bd80d

//!
//! ## 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).
//!
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't make it clear which method takes priority, in case the env var is set but you also use Builder (I assume the Builder wins).

//! 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
Expand All @@ -123,11 +142,14 @@
//! [`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
Expand Down Expand Up @@ -187,16 +209,8 @@ pub use self::local::{LocalKey, LocalKeyState, AccessError};
///
/// 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.
Expand Down Expand Up @@ -228,6 +242,8 @@ pub use self::local::{LocalKey, LocalKeyState, AccessError};
/// [`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 {
Expand Down Expand Up @@ -267,6 +283,9 @@ impl 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
///
/// ```
Expand All @@ -281,6 +300,8 @@ impl Builder {
///
/// 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);
Expand All @@ -292,13 +313,18 @@ impl Builder {
/// 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
///
/// ```
/// use std::thread;
///
/// 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);
Expand Down Expand Up @@ -987,6 +1013,9 @@ impl Thread {

/// 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:
Expand Down Expand Up @@ -1017,6 +1046,8 @@ impl Thread {
///
/// 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()) } )
Expand Down