Struct async_executors::TokioHandle

pub struct TokioHandle { /* fields omitted */ }

A handle to a TokioCt or TokioTp executor. It implements Spawn and SpawnHandle traits. You can obtain one from TokioCt::handle or TokioTp::handle.

For TokioTp this can be used to avoid a drop order problem for the tokio Runtime. See the documentation for TokioTp for an explanation.

For TokioCt this can be used to send a future from another thread to run on the TokioCt.

The handle is only operational as long as the parent executor is alive. There is no compiler assisted lifetime tracking for this as generally spawned futures you would like to give the handle to need to be 'static, so usability would be rather hampered. You must make sure you manage the lifetimes manually.

If the parent executor is already dropped when spawn is called, the future just get's dropped silently without ever being polled.

Unwind Safety.

You must only spawn futures to this API that are unwind safe. Tokio will wrap it in std::panic::AssertUnwindSafe and wrap the poll invocation with std::panic::catch_unwind.

They reason that this is fine because they require Send + 'static on the future. As far as I can tell this is wrong. Unwind safety can be circumvented in several ways even with Send + 'static (eg. parking_lot::Mutex is Send + 'static but !UnwindSafe).

You should make sure that if your future panics, no code that lives on after the spawned task has unwound, nor any destructors called during the unwind can observe data in an inconsistent state.

See the relevant catch_unwind RFC and it's discussion threads for more info as well as the documentation of std::panic::UnwindSafe.

Trait Implementations

impl Clone for TokioHandle

fn clone(&self) -> TokioHandle

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TokioHandle

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

Formats the value using the given formatter.

impl Spawn for TokioHandle

fn spawn_obj(&self, future: FutureObj<'static, ()>) -> Result<(), SpawnError>

Spawns a future that will be run to completion.

fn status(&self) -> Result<(), SpawnError>

Determines whether the executor is able to spawn new tasks.

impl<Out: 'static + Send> SpawnHandle<Out> for TokioHandle

fn spawn_handle_obj(
    &self,
    future: FutureObj<'static, Out>
) -> Result<JoinHandle<Out>, SpawnError>

Spawn a future and return a JoinHandle that can be awaited for the output of the future.