Struct std::thread::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(32 * 1024);

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

handler.join().unwrap();

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();

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 a 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);

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 spawned 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();

Spawns a new thread without any lifetime restrictions 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 spawned thread, including recovering its panics.

This method is identical to thread::Builder::spawn, except for the relaxed lifetime bounds, which render it unsafe. 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.

Safety

The caller has to ensure that no references in the supplied thread closure or its return type can outlive the spawned thread’s lifetime. This can be guaranteed in two ways:

• ensure that join is called before any referenced data is dropped
• use only types with 'static lifetime bounds, i.e., those with no or only 'static references (both thread::Builder::spawn and thread::spawn enforce this property statically)

Examples

#![feature(thread_spawn_unchecked)]
use std::thread;

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

let x = 1;
let thread_x = &x;

let handler = unsafe {
    builder.spawn_unchecked(move || {
        println!("x = {}", *thread_x);
    }).unwrap()
};

// caller has to ensure `join()` is called, otherwise
// it is possible to access freed memory if `x` gets
// dropped before the thread closure is executed!
handler.join().unwrap();