Struct Builder

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

Available on tokio_unstable and crate feature rt 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 not Send futures
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 a !Send task on the current LocalSet or LocalRuntime 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 or a LocalRuntime.

Panics

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

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. Read more

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

fn default() -> Builder<'a>

Returns the “default value” for a type. Read more

Auto Trait Implementations

impl<'a> Freeze for Builder<'a>

impl<'a> RefUnwindSafe for Builder<'a>

impl<'a> Send for Builder<'a>

impl<'a> Sync for Builder<'a>

impl<'a> Unpin for Builder<'a>

impl<'a> UnsafeUnpin for Builder<'a>

impl<'a> UnwindSafe for Builder<'a>

Blanket Implementations

impl<T> Any for T
where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more

impl<T> Borrow<T> for T
where T: ?Sized,

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more

impl<T> BorrowMut<T> for T
where T: ?Sized,

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

Mutably borrows from an owned value. Read more

impl<T> From<T> for T

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> Instrument for T

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

impl<T, U> Into for T
where U: From<T>,

fn into(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 T
where U: Into<T>,

type Error = Infallible

The type returned in the event of a conversion error.

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

Performs the conversion.

impl<T, U> TryInto for T
where U: TryFrom<T>,

type Error = >::Error

The type returned in the event of a conversion error.

fn try_into(self) -> Result<U, >::Error>

Performs the conversion.

impl<T> WithSubscriber for T

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more

Struct Builder

Example

Implementations

impl<'a> Builder<'a>

pub fn new() -> Self

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

pub fn spawn<Fut>(self, future: Fut) -> Result<JoinHandle<Fut::Output>>where Fut: Future + Send + 'static, Fut::Output: Send + 'static,

Panics

pub fn spawn_on<Fut>( self, future: Fut, handle: &Handle, ) -> Result<JoinHandle<Fut::Output>>where Fut: Future + Send + 'static, Fut::Output: Send + 'static,

pub fn spawn_local<Fut>(self, future: Fut) -> Result<JoinHandle<Fut::Output>>where Fut: Future + 'static, Fut::Output: 'static,

Panics

pub fn spawn_local_on<Fut>( self, future: Fut, local_set: &LocalSet, ) -> Result<JoinHandle<Fut::Output>>where Fut: Future + 'static, Fut::Output: 'static,

pub fn spawn_blocking<Function, Output>( self, function: Function, ) -> Result<JoinHandle<Output>>where Function: FnOnce() -> Output + Send + 'static, Output: Send + 'static,

Panics

pub fn spawn_blocking_on<Function, Output>( self, function: Function, handle: &Handle, ) -> Result<JoinHandle<Output>>where Function: FnOnce() -> Output + Send + 'static, Output: Send + 'static,

Trait Implementations

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

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

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

fn default() -> Builder<'a>

Auto Trait Implementations

impl<'a> Freeze for Builder<'a>

impl<'a> RefUnwindSafe for Builder<'a>

impl<'a> Send for Builder<'a>

impl<'a> Sync for Builder<'a>

impl<'a> Unpin for Builder<'a>

impl<'a> UnsafeUnpin for Builder<'a>

impl<'a> UnwindSafe for Builder<'a>

Blanket Implementations

impl<T> Any for Twhere T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for Twhere T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for Twhere T: ?Sized,

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

impl<T> From<T> for T

fn from(t: T) -> T

impl<T> Instrument for T

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

fn in_current_span(self) -> Instrumented<Self> ⓘ

impl<T, U> Into<U> for Twhere U: From<T>,

fn into(self) -> U

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

type Error = Infallible

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

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error

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

impl<T> WithSubscriber for T

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘwhere S: Into<Dispatch>,

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

pub fn spawn<Fut>(self, future: Fut) -> Result<JoinHandle<Fut::Output>>
where Fut: Future + Send + 'static, Fut::Output: Send + 'static,

pub fn spawn_on<Fut>( self, future: Fut, handle: &Handle, ) -> Result<JoinHandle<Fut::Output>>
where Fut: Future + Send + 'static, Fut::Output: Send + 'static,

pub fn spawn_local<Fut>(self, future: Fut) -> Result<JoinHandle<Fut::Output>>
where Fut: Future + 'static, Fut::Output: 'static,

pub fn spawn_local_on<Fut>( self, future: Fut, local_set: &LocalSet, ) -> Result<JoinHandle<Fut::Output>>
where Fut: Future + 'static, Fut::Output: 'static,

pub fn spawn_blocking<Function, Output>( self, function: Function, ) -> Result<JoinHandle<Output>>
where Function: FnOnce() -> Output + Send + 'static, Output: Send + 'static,

pub fn spawn_blocking_on<Function, Output>( self, function: Function, handle: &Handle, ) -> Result<JoinHandle<Output>>
where Function: FnOnce() -> Output + Send + 'static, Output: Send + 'static,

impl<T> Any for T
where T: 'static + ?Sized,

impl<T> Borrow<T> for T
where T: ?Sized,

impl<T> BorrowMut<T> for T
where T: ?Sized,

impl<T, U> Into<U> for T
where U: From<T>,

impl<T, U> TryFrom<U> for T
where U: Into<T>,

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,