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

    pub struct LocalSet { /* fields omitted */ }

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;

    #[tokio::main]
    async fn main() {
        // `Rc` does not implement `Send`, and thus may not be sent between
        // threads safely.
        let unsend_data = Rc::new("my unsend data...");

        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;

    #[tokio::main]
    async fn main() {
        let unsend_data = Rc::new("my unsend data...");

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

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

## Awaiting a `LocalSet`

Additionally, a `LocalSet` itself implements `Future`, completing when all tasks spawned on the `LocalSet` complete. This can be used to run several futures on a `LocalSet` and drive the whole set until they complete. For example,

    use tokio::{task, time};
    use std::rc::Rc;

    #[tokio::main]
    async fn main() {
        let unsend_data = Rc::new("world");
        let local = task::LocalSet::new();

        let unsend_data2 = unsend_data.clone();
        local.spawn_local(async move {
            // ...
            println!("hello {}", unsend_data2)
        });

        local.spawn_local(async move {
            time::sleep(time::Duration::from_millis(100)).await;
            println!("goodbye {}", unsend_data)
        });

        // ...

        local.await;
    }

## Implementations

### `impl LocalSet` [src]

#### `pub fn new() -> LocalSetⓘ

### Notable traits for LocalSet

`impl Future for LocalSet type Output = ();`
` [src]

Returns a new local task set.

#### `pub fn spawn_local<F>(&self, future: F) -> JoinHandle<F::Output>ⓘ

### Notable traits for JoinHandle<T>

`impl<T> Future for JoinHandle<T> type Output = Result<T, JoinError>;`
where
F: Future + 'static,
F::Output: 'static,` [src]

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 task set is not running. For example:

    use tokio::task;

    #[tokio::main]
    async fn main() {
        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;
    }

#### `pub fn block_on<F>(&self, rt: &Runtime, future: F) -> F::Output where
F: Future,` [src]

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:

ⓘThis example panics

    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();
    })

#### `pub async fn run_until<F, '_>(&'_ self, future: F) -> F::Output where
F: Future,` [src]

Run 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` 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.

# Examples

    use tokio::task;

    #[tokio::main]
    async fn main() {
        task::LocalSet::new().run_until(async {
            task::spawn_local(async move {
                // ...
            }).await.unwrap();
            // ...
        }).await;
    }

## Trait Implementations

### `impl Debug for LocalSet` [src]

#### `fn fmt(&self, fmt: &mut Formatter<'_>) -> Result` [src]

Formats the value using the given formatter. Read more

### `impl Default for LocalSet` [src]

#### `fn default() -> LocalSetⓘ

### Notable traits for LocalSet

`impl Future for LocalSet type Output = ();`
` [src]

Returns the "default value" for a type. Read more

### `impl Drop for LocalSet` [src]

#### `fn drop(&mut self)` [src]

Executes the destructor for this type. Read more

### `impl Future for LocalSet` [src]

#### `type Output = ()`

The type of value produced on completion.

#### `fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>` [src]

Attempt to resolve the future to a final value, registering the current task for wakeup if the value is not yet available. Read more

## Auto Trait Implementations

### `impl !RefUnwindSafe for LocalSet`

### `impl !Send for LocalSet`

### `impl !Sync for LocalSet`

### `impl Unpin for LocalSet`

### `impl !UnwindSafe for LocalSet`

## Blanket Implementations

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

#### `pub fn type_id(&self) -> TypeId` [src]

Gets the `TypeId` of `self`. Read more

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

#### `pub fn borrow(&self) -> &Tⓘ

### Notable traits for &'_ mut F

`impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;`
` [src]

Immutably borrows from an owned value. Read more

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

#### `pub fn borrow_mut(&mut self) -> &mut Tⓘ

### Notable traits for &'_ mut F

`impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;`
` [src]

Mutably borrows from an owned value. Read more

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

#### `pub fn from(t: T) -> T` [src]

Performs the conversion.

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

#### `pub fn into(self) -> U` [src]

Performs the conversion.

### `impl<F> IntoFuture for F where
F: Future,` [src]

#### `type Output = <F as Future>::Output`

🔬 This is a nightly-only experimental API. (`into_future`)

The output that the future will produce on completion.

#### `type Future = F`

🔬 This is a nightly-only experimental API. (`into_future`)

Which kind of future are we turning this into?

#### `pub fn into_future(self) -> <F as IntoFuture>::Future` [src]

🔬 This is a nightly-only experimental API. (`into_future`)

Creates a future from a value.

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

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>` [src]

Performs the conversion.

### `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.

#### `pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>` [src]

Performs the conversion.