Struct Builder

struct Builder { ... }

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:

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

Implementations

impl Builder

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(32 * 1024);

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

handler.join().unwrap();

fn name(self: Self, name: String) -> Builder

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

fn stack_size(self: 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 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);

fn no_hooks(self: Self) -> Builder

Disables running and inheriting spawn hooks.

Use this if the parent thread is in no way relevant for the child thread. For example, when lazily spawning threads for a thread pool.

fn spawn<F, T>(self: Self, f: F) -> Result<JoinHandle<T>>
where
    F: FnOnce() -> T + 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 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();

unsafe fn spawn_unchecked<F, T>(self: Self, f: F) -> Result<JoinHandle<T>>
where
    F: FnOnce() -> T + Send,
    T: Send

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]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 the spawned thread does not outlive any references in the supplied thread closure and its return type. This can be guaranteed in two ways:

  • ensure that [join]JoinHandle::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]Builder::spawn and thread::spawn enforce this property statically)

Examples

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

impl Builder

fn spawn_scoped<'scope, 'env, F, T>(self: Self, scope: &'scope Scope<'scope, 'env>, f: F) -> Result<ScopedJoinHandle<'scope, T>>
where
    F: FnOnce() -> T + Send + 'scope,
    T: Send + 'scope

Spawns a new scoped thread using the settings set through this Builder.

Unlike Scope::spawn, 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.

Example

use std::thread;

let mut a = vec![1, 2, 3];
let mut x = 0;

thread::scope(|s| {
    thread::Builder::new()
        .name("first".to_string())
        .spawn_scoped(s, ||
    {
        println!("hello from the {:?} scoped thread", thread::current().name());
        // We can borrow `a` here.
        dbg!(&a);
    })
    .unwrap();
    thread::Builder::new()
        .name("second".to_string())
        .spawn_scoped(s, ||
    {
        println!("hello from the {:?} scoped thread", thread::current().name());
        // We can even mutably borrow `x` here,
        // because no other threads are using it.
        x += a[0] + a[2];
    })
    .unwrap();
    println!("hello from the main thread");
});

// After the scope, we can modify and access our variables again:
a.push(4);
assert_eq!(x, a.len());

impl Debug for Builder

fn fmt(self: &Self, f: &mut Formatter<'_>) -> Result

impl Freeze for Builder

impl RefUnwindSafe for Builder

impl Send for Builder

impl Sync for Builder

impl Unpin for Builder

impl UnsafeUnpin for Builder

impl UnwindSafe for Builder

impl<T> Any for Builder

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for Builder

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for Builder

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> From for Builder

fn from(t: T) -> T

Returns the argument unchanged.

impl<T, U> Into for Builder

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom for Builder

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for Builder

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>