Struct Builder

pub struct Builder<'a> { /* private fields */ }

Available on tokio_unstable and crate feature tracing only.

Factory which is used to configure the properties of a new task.

Note: This is an unstable API. The public API of this type may break in 1.x releases. See the documentation on unstable features for details.

Methods can be chained in order to configure it.

Currently, there is only one configuration option:

• name, which specifies an associated name for the task

There are three types of task that can be spawned from a Builder:

• spawn_local for executing futures on the current thread
• spawn for executing Send futures on the runtime
• spawn_blocking for executing blocking code in the blocking thread pool.

Example

use tokio::net::{TcpListener, TcpStream};

use std::io;

async fn process(socket: TcpStream) {
    // ...
}

#[tokio::main]
async fn main() -> io::Result<()> {
    let listener = TcpListener::bind("127.0.0.1:8080").await?;

    loop {
        let (socket, _) = listener.accept().await?;

        tokio::task::Builder::new()
            .name("tcp connection handler")
            .spawn(async move {
                // Process each socket concurrently.
                process(socket).await
            })?;
    }
}

Implementations

impl<'a> Builder<'a>

pub fn new() -> Self

Creates a new task builder.

pub fn name(&self, name: &'a str) -> Self

Assigns a name to the task which will be spawned.

pub fn spawn<Fut>(self, future: Fut) -> Result<JoinHandle<Fut::Output>>

where Fut: Future + Send + 'static, Fut::Output: Send + 'static,

Spawns a task with this builder’s settings on the current runtime.

Panics

This method panics if called outside of a Tokio runtime.

See task::spawn for more details.

pub fn spawn_on<Fut>( self, future: Fut, handle: &Handle, ) -> Result<JoinHandle<Fut::Output>>

where Fut: Future + Send + 'static, Fut::Output: Send + 'static,

Spawn a task with this builder’s settings on the provided runtime handle.

See Handle::spawn for more details.

pub fn spawn_local<Fut>(self, future: Fut) -> Result<JoinHandle<Fut::Output>>

where Fut: Future + 'static, Fut::Output: 'static,

Spawns !Send a task on the current LocalSet with this builder’s settings.

The spawned future will be run on the same thread that called spawn_local. This may only be called from the context of a local task set.

Panics

This function panics if called outside of a local task set.

See task::spawn_local for more details.

pub fn spawn_local_on<Fut>( self, future: Fut, local_set: &LocalSet, ) -> Result<JoinHandle<Fut::Output>>

where Fut: Future + 'static, Fut::Output: 'static,

Spawns !Send a task on the provided LocalSet with this builder’s settings.

See LocalSet::spawn_local for more details.

pub fn spawn_blocking<Function, Output>( self, function: Function, ) -> Result<JoinHandle<Output>>

where Function: FnOnce() -> Output + Send + 'static, Output: Send + 'static,

Spawns blocking code on the blocking threadpool.

Panics

This method panics if called outside of a Tokio runtime.

See task::spawn_blocking for more details.

pub fn spawn_blocking_on<Function, Output>( self, function: Function, handle: &Handle, ) -> Result<JoinHandle<Output>>

where Function: FnOnce() -> Output + Send + 'static, Output: Send + 'static,

Spawns blocking code on the provided runtime handle’s blocking threadpool.

See Handle::spawn_blocking for more details.

Trait Implementations

impl<'a> Debug for Builder<'a>

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

Formats the value using the given formatter.

impl<'a> Default for Builder<'a>

fn default() -> Builder<'a>

Returns the “default value” for a type.