[][src]Struct tokio::task::LocalSet

pub struct LocalSet { /* fields omitted */ }
This is supported on feature="rt-core" and feature="rt-util" only.

A set of tasks which are executed on the same thread.

In some cases, it is necessary to run one or more futures that do not implement Send and thus are unsafe to send between threads. In these cases, a local task set may be used to schedule one or more !Send futures to run together on the same thread.

For example, the following code will not compile:

This example deliberately fails to compile
use std::rc::Rc;

// `Rc` does not implement `Send`, and thus may not be sent between
// threads safely.
let unsend_data = Rc::new("my unsend data...");

let mut rt = Runtime::new().unwrap();

rt.block_on(async move {
    let unsend_data = unsend_data.clone();
    // Because the `async` block here moves `unsend_data`, the future is `!Send`.
    // Since `tokio::spawn` requires the spawned future to implement `Send`, this
    // will not compile.
    tokio::spawn(async move {
        println!("{}", unsend_data);
        // ...
    }).await.unwrap();
});

In order to spawn !Send futures, we can use a local task set to schedule them on the thread calling Runtime::block_on. When running inside of the local task set, we can use task::spawn_local, which can spawn !Send futures. For example:

use std::rc::Rc;
use tokio::task;

let unsend_data = Rc::new("my unsend data...");

let mut rt = Runtime::new().unwrap();
// Construct a local task set that can run `!Send` futures.
let local = task::LocalSet::new();

// Run the local task group.
local.block_on(&mut rt, async move {
    let unsend_data = unsend_data.clone();
    // `spawn_local` ensures that the future is spawned on the local
    // task group.
    task::spawn_local(async move {
        println!("{}", unsend_data);
        // ...
    }).await.unwrap();
});

Methods

impl LocalSet[src]

pub fn new() -> Self[src]

This is supported on feature="rt-core" and feature="rt-util" only.

Returns a new local task set.

Important traits for JoinHandle<T>
pub fn spawn_local<F>(&self, future: F) -> JoinHandle<F::Output> where
    F: Future + 'static,
    F::Output: 'static, 
[src]

This is supported on feature="rt-core" and feature="rt-util" only.

Spawns a !Send task onto the local task set.

This task is guaranteed to be run on the current thread.

Unlike the free function spawn_local, this method may be used to spawn_local local tasks when the task set is not running. For example:

use tokio::task;

let mut rt = Runtime::new().unwrap();
let local = task::LocalSet::new();

// Spawn a future on the local set. This future will be run when
// we call `block_on` to drive the task set.
local.spawn_local(async {
   // ...
});

// Run the local task set.
local.block_on(&mut rt, async move {
    // ...
});

// When `block_on` finishes, we can spawn_local _more_ futures, which will
// run in subsequent calls to `block_on`.
local.spawn_local(async {
   // ...
});

local.block_on(&mut rt, async move {
    // ...
});

pub fn block_on<F>(&self, rt: &mut Runtime, future: F) -> F::Output where
    F: Future + 'static,
    F::Output: 'static, 
[src]

This is supported on feature="rt-core" and feature="rt-util" only.

Run a future to completion on the provided runtime, driving any local futures spawned on this task set on the current thread.

This runs the given future on the runtime, blocking until it is complete, and yielding its resolved result. Any tasks or timers which the future spawns internally will be executed on the runtime. The future may also call spawn_local to spawn_local additional local futures on the current thread.

This method should not be called from an asynchronous context.

Panics

This function panics if the executor is at capacity, if the provided future panics, or if called within an asynchronous execution context.

Notes

Since this function internally calls Runtime::block_on, and drives futures in the local task set inside that call to block_on, the local futures may not use in-place blocking. If a blocking call needs to be issued from a local task, the spawn_blocking API may be used instead.

For example, this will panic:

use tokio::runtime::Runtime;
use tokio::task;

let mut rt = Runtime::new().unwrap();
let local = task::LocalSet::new();
local.block_on(&mut rt, async {
    let join = task::spawn_local(async {
        let blocking_result = task::block_in_place(|| {
            // ...
        });
        // ...
    });
    join.await.unwrap();
})

This, however, will not panic:

use tokio::runtime::Runtime;
use tokio::task;

let mut rt = Runtime::new().unwrap();
let local = task::LocalSet::new();
local.block_on(&mut rt, async {
    let join = task::spawn_local(async {
        let blocking_result = task::spawn_blocking(|| {
            // ...
        }).await;
        // ...
    });
    join.await.unwrap();
})

Trait Implementations

impl Default for LocalSet[src]

impl Debug for LocalSet[src]

Auto Trait Implementations

impl !Send for LocalSet

impl !Sync for LocalSet

impl Unpin for LocalSet

impl !UnwindSafe for LocalSet

impl !RefUnwindSafe for LocalSet

Blanket Implementations

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T> From<T> for T[src]

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = !

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

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

The type returned in the event of a conversion error.

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> Any for T where
    T: 'static + ?Sized
[src]