Struct blocking_permit::DispatchPool

pub struct DispatchPool { /* fields omitted */ }

A specialized thread pool and queue for dispatching blocking (synchronous, long running) operations.

This pool is not an executor, has no waking facilities, etc. As compared with other thread pools supporting spawn, or spawn_blocking in tokio, here also called dispatch() or dispatch_rx() this pool has some unique features:

• A configurable, fixed number of threads created before return from construction and terminated on Drop::drop. Consistent memory footprint. No warmup required. No per-task thread management overhead.

• Configurable panic handling policy: Either catches and logs dispatch panics, or aborts the process, on panic unwind.

• Supports fixed (bounded) or unbounded queue length.

• When the queue is bounded and becomes full, DispatchPool::spawn pops the oldest operation off the queue before pushing the newest passed operation, to ensure space while holding a lock. Then as a fallback it runs the old operation. Thus we enlist calling threads once the queue reaches limit, but operation order (at least from perspective of a single thread) is preserved.

Usage

By default, the pool uses an unbounded queue, with the assumption that resource/capacity is externally constrained. Once constructed, a fixed number of threads are spawned and the instance acts as a handle to the pool. This may be inexpensively cloned for additional handles to the same pool.

See DispatchPoolBuilder for an extensive set of options.

With tokio’s threaded runtime

One can schedule a clone of the DispatchPool (handle) on each tokio runtime thread (tokio’s rt-threaded feature).

use blocking_permit::{
    DispatchPool, register_dispatch_pool, deregister_dispatch_pool
};

let pool = DispatchPool::builder().create();

let mut rt = tokio::runtime::Builder::new_multi_thread()
    .on_thread_start(move || {
        register_dispatch_pool(pool.clone());
    })
    .on_thread_stop(|| {
        deregister_dispatch_pool();
    })
    .build()
    .unwrap();

Implementations

impl DispatchPool

pub fn new() -> DispatchPool

Create new pool using defaults.

pub fn builder() -> DispatchPoolBuilder

Create a new builder for configuring a new pool.

pub fn spawn(&self, f: Box<dyn FnOnce() + Send>)

Enqueue a blocking operation to be executed.

This first attempts to send to the associated queue, which will always succeed if unbounded, e.g. no DispatchPoolBuilder::queue_length is set, the default. If however the queue is bounded and at capacity, then this task will be pushed after taking the oldest task, which is then run on the calling thread.

Trait Implementations

impl Clone for DispatchPool

fn clone(&self) -> DispatchPool

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for DispatchPool

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

Formats the value using the given formatter.

impl Default for DispatchPool

fn default() -> Self

Returns the “default value” for a type.