std::thread::Builder - Rust
Description: API documentation for the Rust `Builder` struct in crate `std`.
Keywords: rust, rustlang, rust-lang, Builder

# Struct std::thread::Builder 1.0.0 [−] [src]

    pub struct Builder { /* fields omitted */ }

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

    use std::thread;

    let builder = thread::Builder::new();

    let handler = builder.spawn(|| {
        // thread code
    }).unwrap();

    handler.join().unwrap();Run

## Methods

### `impl Builder`
[src]

#### `fn new() -> Builder`

Generates the base configuration for spawning a thread, from which configuration methods can be chained.

# Examples

    use std::thread;

    let builder = thread::Builder::new()
                                  .name("foo".into())
                                  .stack_size(10);

    let handler = builder.spawn(|| {
        // thread code
    }).unwrap();

    handler.join().unwrap();Run

#### `fn name(self, name: String) -> Builder`

Names the thread-to-be. Currently the name is used for identification only in panic messages.

# Examples

    use std::thread;

    let builder = thread::Builder::new()
        .name("foo".into());

    let handler = builder.spawn(|| {
        assert_eq!(thread::current().name(), Some("foo"))
    }).unwrap();

    handler.join().unwrap();Run

#### `fn stack_size(self, size: usize) -> Builder`

Sets the size of the stack (in bytes) for the new thread.

The actual stack size may be greater than this value if the platform specifies minimal stack size.

# Examples

    use std::thread;

    let builder = thread::Builder::new().stack_size(32 * 1024);Run

#### `fn spawn<F, T>(self, f: F) -> Result<JoinHandle<T>> where
F: FnOnce() -> T,
F: Send + 'static,
T: Send + 'static,`

Spawns a new thread by taking ownership of the `Builder`, and returns an `io::Result` to its `JoinHandle`.

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.

For a more complete documentation see `thread::spawn`.

# Errors

Unlike the `spawn` free function, this method yields an `io::Result` to capture any failure to create the thread at the OS level.

# Examples

    use std::thread;

    let builder = thread::Builder::new();

    let handler = builder.spawn(|| {
        // thread code
    }).unwrap();

    handler.join().unwrap();Run

## Trait Implementations

### `impl Debug for Builder`
[src]

#### `fn fmt(&self, __arg_0: &mut Formatter) -> Result`

Formats the value using the given formatter.

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result
+
  Collapse/expand all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)