Struct DedicatedExecutor 

pub struct DedicatedExecutor { /* private fields */ }

Manages a separate tokio runtime (thread pool) for executing tasks.

A DedicatedExecutor runs futures (and any tasks that are tokio::task::spawned by them) on a separate tokio Executor

Background

Tokio has the notion of the “current” runtime, which runs the current future and any tasks spawned by it. Typically, this is the runtime created by tokio::main and is used for the main application logic and I/O handling

For CPU bound work, such as DataFusion plan execution, it is important to run on a separate thread pool to avoid blocking the I/O handling for extended periods of time in order to avoid long poll latencies (which decreases the throughput of small requests under concurrent load).

IO Scheduling

I/O, such as network calls, should not be performed on the runtime managed by DedicatedExecutor. As tokio is a cooperative scheduler, long-running CPU tasks will not be preempted and can therefore starve servicing of other tasks. This manifests in long poll-latencies, where a task is ready to run but isn’t being scheduled to run. For CPU-bound work this isn’t a problem as there is no external party waiting on a response, however, for I/O tasks, long poll latencies can prevent timely servicing of IO, which can have a significant detrimental effect.

Details

The worker thread priority is set to low so that such tasks do not starve other more important tasks (such as answering health checks)

Follows the example from stack overflow and spawns a new thread to install a Tokio runtime “context” https://stackoverflow.com/questions/62536566

Trouble Shooting:

“No IO runtime registered. Call register_io_runtime/register_current_runtime_for_io in current thread!

This means that IO was attempted on a tokio runtime that was not registered for IO. One solution is to run the task using DedicatedExecutor::spawn.

“Cannot drop a runtime in a context where blocking is not allowed”`

If you try to use this structure from an async context you see something like thread ‘plan::stringset::tests::test_builder_plan’ panicked at ‘Cannot drop a runtime in a context where blocking is not allowed. This happens when a runtime is dropped from within an asynchronous context.’, …/tokio-1.4.0/src/runtime/blocking/shutdown.rs:51:21

Implementations

impl DedicatedExecutor

pub fn new( name: &str, config: ExecutionConfig, runtime_builder: Builder, ) -> Self

Creates a new DedicatedExecutor with a dedicated tokio executor that is separate from the threadpool created via [tokio::main] or similar.

See the documentation on DedicatedExecutor for more details.

If DedicatedExecutor::new is called from an existing tokio runtime, it will assume that the existing runtime should be used for I/O, and is thus set, via register_io_runtime by all threads spawned by the executor. This will allow scheduling IO outside the context of DedicatedExecutor using [spawn_io].

pub fn new_testing() -> Self

Create new executor for testing purposes.

Internal state may be shared with other tests.

pub fn spawn<T>( &self, task: T, ) -> impl Future<Output = Result<T::Output, JobError>>

where T: Future + Send + 'static, T::Output: Send + 'static,

Runs the specified Future (and any tasks it spawns) on the thread pool managed by this DedicatedExecutor.

Notes

UNLIKE tokio::task::spawn, the returned future is cancelled when it is dropped. Thus, you need ensure the returned future lives until it completes (call await) or you wish to cancel it.

Currently all tasks are added to the tokio executor immediately and compete for the threadpool’s resources.

pub fn shutdown(&self)

signals shutdown of this executor and any Clones

pub async fn join(&self)

Stops all subsequent task executions, and waits for the worker thread to complete. Note this will shutdown all clones of this DedicatedExecutor as well.

Only the first all to join will actually wait for the executing thread to complete. All other calls to join will complete immediately.

Panic / Drop

DedicatedExecutor implements shutdown on Drop. You should just use this behavior and NOT call join manually during Drop or panics because this might lead to another panic, see https://github.com/rust-lang/futures-rs/issues/2575.

Trait Implementations

impl Clone for DedicatedExecutor

fn clone(&self) -> DedicatedExecutor

Returns a duplicate of the value.

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

Performs copy-assignment from source.