Struct LocalSet

Returns a new local task set.

Enters the context of this LocalSet.

The spawn_local method will spawn tasks on the LocalSet whose context you are inside.

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 tasks when the LocalSet is not running. The provided future will start running once the LocalSet is next started, even if you don’t await the returned JoinHandle.

Examples

use tokio::task;

let local = task::LocalSet::new();

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

// Run the local task set.
local.run_until(async move {
    // ...
}).await;

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

local.run_until(async move {
    // ...
}).await;

Runs 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 rt  = Runtime::new().unwrap();
let local = task::LocalSet::new();
local.block_on(&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 rt  = Runtime::new().unwrap();
let local = task::LocalSet::new();
local.block_on(&rt, async {
    let join = task::spawn_local(async {
        let blocking_result = task::spawn_blocking(|| {
            // ...
        }).await;
        // ...
    });
    join.await.unwrap();
})

Runs a future to completion on the local set, returning its output.

This returns a future that runs the given future with a local set, allowing it to call spawn_local to spawn additional !Send futures. Any local futures spawned on the local set will be driven in the background until the future passed to run_until completes. When the future passed to run_until finishes, any local futures which have not completed will remain on the local set, and will be driven on subsequent calls to run_until or when awaiting the local set itself.

Cancel safety

This method is cancel safe when future is cancel safe.

Examples

use tokio::task;

task::LocalSet::new().run_until(async {
    task::spawn_local(async move {
        // ...
    }).await.unwrap();
    // ...
}).await;

Returns the Id of the current LocalSet runtime.

Examples

use tokio::task;

let local_set = task::LocalSet::new();
println!("Local set id: {}", local_set.id());

Configure how the LocalSet responds to an unhandled panic on a spawned task.

By default, an unhandled panic (i.e. a panic not caught by std::panic::catch_unwind) has no impact on the LocalSet’s execution. The panic is error value is forwarded to the task’s JoinHandle and all other spawned tasks continue running.

The unhandled_panic option enables configuring this behavior.

• UnhandledPanic::Ignore is the default behavior. Panics on spawned tasks have no impact on the LocalSet’s execution.
• UnhandledPanic::ShutdownRuntime will force the LocalSet to shutdown immediately when a spawned task panics even if that task’s JoinHandle has not been dropped. All other spawned tasks will immediately terminate and further calls to LocalSet::block_on and LocalSet::run_until will panic.

Panics

This method panics if called after the LocalSet has started running.

Unstable

This option is currently unstable and its implementation is incomplete. The API may change or be removed in the future. See tokio-rs/tokio#4516 for more details.

Examples

The following demonstrates a LocalSet configured to shutdown on panic. The first spawned task panics and results in the LocalSet shutting down. The second spawned task never has a chance to execute. The call to run_until will panic due to the runtime being forcibly shutdown.

use tokio::runtime::UnhandledPanic;

tokio::task::LocalSet::new()
    .unhandled_panic(UnhandledPanic::ShutdownRuntime)
    .run_until(async {
        tokio::task::spawn_local(async { panic!("boom"); });
        tokio::task::spawn_local(async {
            // This task never completes
        });

        // Do some work, but `run_until` will panic before it completes
    })
    .await;

Returns the argument unchanged.

Calls U::from(self).

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