Struct async_executors::exec::TokioTp

pub struct TokioTp { /* private fields */ }

Available on crate feature tokio_tp only.

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  :: { TokioTp                   } ,
   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()
{
   // This creates the runtime with defaults. It enables io and timers based on
   // the features enabled on _async_executors_. You can also create `TokioTp` from
   // a tokio `Runtime` or a `Handle`.
   //
   let exec = TokioTp::new().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 new() -> Result<Self, TokioTpErr>

Create a new TokioTp. Uses a default multithreaded Runtime setting timers and io depending on the features enabled on async_executors.

pub fn try_current() -> Result<Self, TokioTpErr>

Try to construct a TokioTp from the currently entered Runtime. You can do this if you want to construct your runtime with the tokio macros eg:

#[tokio::main]
async fn main()
{
   // ...
}

Warning

TokioTp::new() is preferred over this. It’s brief, doesn’t require macros and is the intended behavior for this type. The whole library aims at a paradigm without global executors.

The main footgun here is that you are now already in async context, so you must not call TokioTp::block_on. block_on will panic when run from within an existing async context.

Errors

Will fail if trying to construct from a current thread runtime or if no runtime is running.

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

Forwards to Runtime::block_on or Handle::block_on.

Panics

If called when a runtime is already entered (eg. in async context), like when you created this executor with TokioTp::try_current, this will panic.

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

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

This tries to unwrap the Arc<Runtime> 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.

Errors

• TokioTpErr::Cloned: if the the TokioTp has been cloned. You can only shut down the last one.
• TokioTpErr::Handle: if the the TokioTp has been created from a handle. That is we don’t own the Runtime.

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

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

This tries to unwrap the Arc<Runtime> 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.

Errors

• TokioTpErr::Cloned: if the the TokioTp has been cloned. You can only shut down the last one.
• TokioTpErr::Handle: if the the TokioTp has been created from a handle. That is we don’t own the Runtime.

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>

Never fails.

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 Timer for TokioTp

Available on crate feature tokio_timer only.

fn sleep(&self, dur: Duration) -> BoxFuture<'static, ()>

Future that resolves after a given duration.

impl TryFrom<Handle> for TokioTp

Allows to create a TokioTp from a Handle.

Errors

Will fail if you pass a multithreaded runtime. In that case it will return your Handle.

type Error = Handle

The type returned in the event of a conversion error.

fn try_from(handle: Handle) -> Result<Self, Handle>

Performs the conversion.

impl TryFrom<Runtime> for TokioTp

Allows to create a TokioTp from a Runtime.

Errors

Will fail if you pass a multithreaded runtime. In that case it will return your Runtime.

type Error = Runtime

The type returned in the event of a conversion error.

fn try_from(rt: Runtime) -> Result<Self, Runtime>

Performs the conversion.

impl YieldNow for TokioTp

fn yield_now(&self) -> YieldNowFut

Await this future in order to yield to the executor.

impl TokioIo for TokioTp

Available on crate feature tokio_io only.