Struct async_executors::exec::TokioTp

pub struct TokioTp { /* private fields */ }

An executor that uses tokio::runtime::Runtime.

Example

The following example shows how to pass an executor to a library function.

use
{
   futures          :: { task::{ Spawn, SpawnExt } } ,
   async_executors  :: { TokioTpBuilder            } ,
   tokio::runtime   :: { Builder                   } ,
   std::convert     :: { TryFrom                   } ,
   futures::channel :: { oneshot, oneshot::Sender  } ,
};


fn lib_function( exec: impl Spawn, tx: Sender<&'static str> )
{
   exec.spawn( async
   {
      tx.send( "I can spawn from a library" ).expect( "send string" );

   }).expect( "spawn task" );
}


fn main()
{
   // You must use the builder. This guarantees that TokioTp is always backed up by a threadpool.
   // You can set other configurations by calling `tokio_builder()` on TokioTpBuilder, so you get
   // access to the `tokio::runtime::Builder`.
   //
   let exec = TokioTpBuilder::new().build().expect( "create tokio threadpool" );

   let program = async
   {
      let (tx, rx) = oneshot::channel();

      lib_function( &exec, tx );
      assert_eq!( "I can spawn from a library", rx.await.expect( "receive on channel" ) );
   };

   exec.block_on( program );
}

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.

If a future is run with block_on as opposed to spawn, the panic will not be caught and the thread calling block_on will be unwound.

Note that unwind safety is related to logic errors, not related to the memory safety issues that cannot happen in safe rust (memory safety, undefined behavior, unsoundness, data races, …). See the relevant catch_unwind RFC and it’s discussion threads for more info as well as the documentation of std::panic::UnwindSafe.

Implementations

impl TokioTp

pub fn block_on<F: Future>(&self, f: F) -> F::Output

Forwards to Runtime::block_on.

pub fn shutdown_timeout(self, duration: Duration) -> Result<(), Self>

See: tokio::runtime::Runtime::shutdown_timeout

This tries to unwrap the Arc we hold, so that works only if no other clones are around. If this is not the only reference, self will be returned to you as an error. It means you cannot shutdown the runtime because there are other clones of the executor still alive.

pub fn shutdown_background(self) -> Result<(), Self>

See: tokio::runtime::Runtime::shutdown_background

This tries to unwrap the Arc we hold, so that works only if no other clones are around. If this is not the only reference, self will be returned to you as an error. It means you cannot shutdown the runtime because there are other clones of the executor still alive.

Trait Implementations

impl Clone for TokioTp

fn clone(&self) -> TokioTp

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for TokioTp

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

Formats the value using the given formatter.

impl Spawn for TokioTp

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<R: Send + 'static> SpawnBlocking<R> for TokioTp

fn spawn_blocking<F>(&self, f: F) -> BlockingHandle<R> where
    F: FnOnce() -> R + Send + 'static, 

Runs the provided closure on a thread where blocking is acceptable.

fn spawn_blocking_dyn(
    &self,
    f: Box<dyn FnOnce() -> R + Send>
) -> BlockingHandle<R>

Runs the provided closure on a thread where blocking is acceptable. This part of the trait is object safe but your closure must be boxed and you cannot have a return value.

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

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.

impl YieldNow for TokioTp

fn yield_now(&self) -> YieldNowFut

Await this future in order to yield to the executor.