Struct LocalExecutor 

pub struct LocalExecutor { /* private fields */ }

An executor for one session, for futures that are not Send.

Tasks spawned on a LocalExecutor run in order on whichever thread drains the dispatch destination it was built with. That is the main thread for the default session, or a dedicated thread for a session created with LocalExecutor::spawn_dedicated. Futures spawned here are polled and dropped on the thread that spawned them.

Implementations

impl LocalExecutor

pub fn new( session_id: SessionId, scheduler: Arc<dyn Scheduler>, dispatch: impl Fn(Runnable<RunnableMeta>) + Send + Sync + 'static, ) -> Self

Creates a local executor for session_id that sends each spawned task’s runnables to dispatch.

For the default session, dispatch usually calls Scheduler::schedule_local. The dedicated-session path passes a closure that sends to the dedicated thread’s channel. scheduler gives the executor access to clocks, timers and the other scheduler services.

pub fn session_id(&self) -> SessionId

Returns the session this executor runs tasks for.

pub fn scheduler(&self) -> &Arc<dyn Scheduler>

Returns the scheduler that this executor’s timers and clock come from.

pub fn is_test(&self) -> bool

Whether this executor runs on a TestScheduler.

pub fn spawn<F>(&self, future: F) -> Task<F::Output>

where F: Future + 'static, F::Output: 'static,

Spawns a future on this session and returns a Task for its output.

The future doesn’t need to be Send. It is polled on the thread that spawned it, so it runs on the session’s thread when called from there. Dropping the returned task cancels the future; call Task::detach to let it run to completion instead.

pub fn spawn_with_dispatch<F>( &self, future: F, dispatch: impl Fn(Runnable<RunnableMeta>) + Send + Sync + 'static, ) -> Task<F::Output>

where F: Future + 'static, F::Output: 'static,

Like Self::spawn, but sends the task’s runnables to dispatch instead of this executor’s own destination.

dispatch must deliver runnables back to this executor’s thread. The future is polled and dropped on the thread that spawned it.

pub fn block_on<Fut: Future>(&self, future: Fut) -> Fut::Output

Blocks the current thread until future completes, and returns its output.

Use this where async code can’t be used, such as a test or the entry point of a session. Not available on wasm, where the main thread can’t block.

Panics

Panics if the scheduler stops before future completes, for example because future waits on work that can never run.

pub fn block_with_timeout<Fut: Future>( &self, timeout: Duration, future: Fut, ) -> Result<Fut::Output, impl Future<Output = Fut::Output> + use<Fut>>

Blocks the current thread until future completes or timeout elapses.

Returns Ok with the output if the future completed in time. On timeout it returns Err with the unfinished future. Await that future later to keep waiting, or drop it to cancel the work. The future may already have run part of its work.

pub fn timer(&self, duration: Duration) -> Timer

Returns a Timer that completes after duration.

pub fn now(&self) -> Instant

Returns the current time from this scheduler’s clock.

Under the test scheduler this is the simulated clock, which moves only when the test advances it.

pub fn spawn_dedicated<F, Fut>(&self, f: F) -> Task<Fut::Output>

where F: FnOnce(LocalExecutor) -> Fut + Send + 'static, Fut: Future + 'static, Fut::Output: Send + Sync + 'static,

Spawns a closure on a new session that has its own LocalExecutor.

The closure runs on a new OS thread under the platform scheduler, or on the test scheduler’s loop under TestScheduler. Its future can use the executor it receives to spawn more work on that thread.

The returned task is the closure’s work. Dropping it cancels the work, awaiting it yields the closure’s return value, and Task::detach lets the work run on after the caller is done with it.

Trait Implementations

impl Clone for LocalExecutor

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.