Struct Builder

pub struct Builder { /* private fields */ }

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

pub fn new() -> Self

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

Examples

let builder = async_thread::Builder::new()
                              .name("foo".into())
                              .stack_size(32 * 1024);

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

handler.join().await.unwrap();

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

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 the std::thread documentation.

Examples

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

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

handler.join().await.unwrap();

pub fn stack_size(self, size: usize) -> Self

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 the std::thread documentation.

Examples

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

pub fn spawn<F, T>(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 child thread, including recovering its panics.

For a more complete documentation see async_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

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

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

handler.join().await.unwrap();

Trait Implementations

impl Debug for Builder

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

Formats the value using the given formatter.