[−][src]Struct tokio::task::LocalSet
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:
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]
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]
F: Future + 'static,
F::Output: 'static,
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,
[src]
F: Future,
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
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> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = !
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,