Struct async_executors::exec::TokioCt [−][src]
pub struct TokioCt { /* fields omitted */ }
tokio_ct
only.Expand description
An executor that uses a tokio::runtime::Runtime
with the current thread
and a tokio::task::LocalSet
. Can spawn !Send
futures.
Creation of the runtime
You must use TokioCtBuilder
to create the executor.
// Make sure to set the `tokio_ct` feature on async_executors.
//
use
{
async_executors :: { TokioCt, TokioCtBuilder, LocalSpawnHandleExt } ,
tokio :: { runtime::Builder } ,
std :: { rc::Rc } ,
};
// You must use the builder. This guarantees that TokioCt is always backed by a single threaded runtime.
// You can set other configurations by calling `tokio_builder()` on TokioCtBuilder, so you get
// access to the `tokio::runtime::Builder`.
//
let exec = TokioCtBuilder::new().build().expect( "create tokio runtime" );
// block_on takes a &self, so if you need to `async move`,
// just clone it for use inside the async block.
//
exec.block_on( async
{
let not_send = async { let rc = Rc::new(()); };
// We can spawn !Send futures here.
//
let join_handle = exec.spawn_handle_local( not_send ).expect( "spawn" );
join_handle.await;
});
Unwind Safety.
When a future spawned on this wrapper panics, the panic will be caught by tokio in the poll function.
You must only spawn futures to this API that are unwind safe. Tokio will wrap spawned tasks 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 task. 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 panic, nor any destructors called during the unwind can observe data in an inconsistent state.
Note: the future running from within block_on
as opposed to spawn
does not exhibit this behavior and will panic
the current thread.
Note that these are logic errors, not related to the class of problems 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 for more information.
Implementations
This is the entry point for this executor. Once this call returns, no remaining tasks shall be polled anymore.
However the tasks stay in the executor, so if you make a second call to block_on
with a new task, the older
tasks will start making progress again.
For simplicity, it’s advised to just create top level task that you run through block_on
and make sure your
program is done when it returns.
See: tokio::runtime::Runtime::block_on
Panics
This function will panic if it is called from an async context, including but not limited to making a nested call. It will also panic if the provided future panics.
Trait Implementations
fn spawn_handle_local_obj(
&self,
future: LocalFutureObj<'static, Out>
) -> Result<JoinHandle<Out>, SpawnError>
fn spawn_handle_local_obj(
&self,
future: LocalFutureObj<'static, Out>
) -> Result<JoinHandle<Out>, SpawnError>
Spawn a future and return a JoinHandle
that can be awaited for the output of the future.
fn spawn_blocking<F>(&self, f: F) -> BlockingHandle<R>ⓘNotable traits for BlockingHandle<T>impl<T: 'static> Future for BlockingHandle<T> type Output = T;
where
F: FnOnce() -> R + Send + 'static,
fn spawn_blocking<F>(&self, f: F) -> BlockingHandle<R>ⓘNotable traits for BlockingHandle<T>impl<T: 'static> Future for BlockingHandle<T> type Output = T;
where
F: FnOnce() -> R + Send + 'static,
impl<T: 'static> Future for BlockingHandle<T> type Output = T;
Runs the provided closure on a thread where blocking is acceptable.
fn spawn_blocking_dyn(
&self,
f: Box<dyn FnOnce() -> R + Send>
) -> BlockingHandle<R>ⓘNotable traits for BlockingHandle<T>impl<T: 'static> Future for BlockingHandle<T> type Output = T;
fn spawn_blocking_dyn(
&self,
f: Box<dyn FnOnce() -> R + Send>
) -> BlockingHandle<R>ⓘNotable traits for BlockingHandle<T>impl<T: 'static> Future for BlockingHandle<T> type Output = T;
impl<T: 'static> Future for BlockingHandle<T> type Output = T;
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. Read more
fn spawn_handle_obj(
&self,
future: FutureObj<'static, Out>
) -> Result<JoinHandle<Out>, SpawnError>
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.
fn yield_now(&self) -> YieldNowFutⓘNotable traits for YieldNowFutimpl Future for YieldNowFut type Output = ();
fn yield_now(&self) -> YieldNowFutⓘNotable traits for YieldNowFutimpl Future for YieldNowFut type Output = ();
impl Future for YieldNowFut type Output = ();
Await this future in order to yield to the executor.
Auto Trait Implementations
impl !RefUnwindSafe for TokioCt
impl !UnwindSafe for TokioCt
Blanket Implementations
Mutably borrows from an owned value. Read more
Instruments this type with the provided Span
, returning an
Instrumented
wrapper. Read more
fn spawn_local<Fut>(&self, future: Fut) -> Result<(), SpawnError> where
Fut: 'static + Future<Output = ()>,
fn spawn_local<Fut>(&self, future: Fut) -> Result<(), SpawnError> where
Fut: 'static + Future<Output = ()>,
Spawns a task that polls the given future with output ()
to
completion. Read more
fn spawn_local_with_handle<Fut>(
&self,
future: Fut
) -> Result<RemoteHandle<<Fut as Future>::Output>, SpawnError> where
Fut: 'static + Future,
fn spawn_local_with_handle<Fut>(
&self,
future: Fut
) -> Result<RemoteHandle<<Fut as Future>::Output>, SpawnError> where
Fut: 'static + Future,
Spawns a task that polls the given future to completion and returns a future that resolves to the spawned future’s output. Read more
Spawns a task that polls the given future with output ()
to
completion. Read more
fn spawn_with_handle<Fut>(
&self,
future: Fut
) -> Result<RemoteHandle<<Fut as Future>::Output>, SpawnError> where
Fut: 'static + Future + Send,
<Fut as Future>::Output: Send,
fn spawn_with_handle<Fut>(
&self,
future: Fut
) -> Result<RemoteHandle<<Fut as Future>::Output>, SpawnError> where
Fut: 'static + Future + Send,
<Fut as Future>::Output: Send,
Spawns a task that polls the given future to completion and returns a future that resolves to the spawned future’s output. Read more
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more