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`: specifies an associated name for the thread
- `stack_size`: specifies the desired stack size for the thread

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]

#### `pub fn new() -> Builder`
[src]

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

#### `pub fn name(self, name: String) -> Builder`
[src]

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

The name must not contain null bytes (`\0`).

For more information about named threads, see this module-level documentation.

# 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

#### `pub fn stack_size(self, size: usize) -> Builder`
[src]

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.

For more information about the stack size for threads, see this module-level documentation.

# Examples

    use std::thread;

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

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

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.

# Panics

Panics if a thread name was set and it contained null bytes.

# 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`
[src]

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`)