Crate blocking_permit

Expand description

This crate provides:

A specialized, custom thread pool, DispatchPool, for offloading blocking or otherwise long running operations from a main or reactor thread(s). Once registered, it is used via dispatch_rx() (to await a return value) or dispatch() for background tasks (fire and forget).
A BlockingPermit, obtained via blocking_permit_future() for limiting the number of concurrent blocking operations via a re-exported Semaphore type selected by one of the (non-default) features futures-intrusive, or tokio-semaphore (or tokio-omnibus).
A Cleaver for splitting Stream buffers into more manageable sizes.
A YieldStream for yielding between Stream items.

The following features may be enabled at build time. All are disabled by default, unless otherwise noted.

futures-channel : Use this oneshot channel implementation (Default enabled, but overridden by tokio-oneshot or tokio-omnibus.)

tokio-oneshot : Use tokio’s oneshot channel implementation (Overrides futures-channel default.).

futures-intrusive : Include BlockingPermit and re-export Semaphore from the futures-intrusive crate. (Works with all prominent runtimes.)

tokio-semaphore : Include BlockingPermit and re-export tokio’s Semaphore type. (Overrides futures-intrusive.)

tokio-threaded : Add block_in_place support, exposed via BlockingPermit::run.

tokio-omnibus : A simpler way to include all above and, we expect, any future added tokio-* features in this crate.

cleaver : Include the Cleaver wrapper stream.

yield-stream : Include the YieldStream wrapper.

Macros§

dispatch_or_permit: Attempt to dispatch a blocking operation, or otherwise obtain a permit and run on thread, returning the result of the closure.

BlockingPermit: A scoped permit for blocking operations. When dropped (out of scope or manually), the permit is released.
BlockingPermitFuture: A future which resolves to a BlockingPermit.
Canceled: Error type returned as output from the BlockingPermitFuture or Dispatched futures if they are canceled.
Cleaver: A Stream adapter that splits buffers from a source to a given, maximum length.
DispatchPool: A specialized thread pool and queue for dispatching blocking (synchronous, long running) operations.
DispatchPoolBuilder: A builder for DispatchPool supporting an extenstive set of configuration options.
Dispatched: A future type created by dispatch_rx.
SyncBlockingPermitFuture: A Sync wrapper available via BlockingPermitFuture::make_sync.
YieldStream: A Stream adapter that yields after every Poll::Ready(Some(_)) result from its source.

Semaphorish: Extension trait for uniform construction of the re-exported Semaphore types.
Splittable: Trait for buffer types that may be split at a maximum length.

blocking_permit_future: Request a permit to perform a blocking operation on the current thread.
deregister_dispatch_pool: Deregister and return any DispatchPool on the current thread.
dispatch: Dispatch a blocking operation closure to a pool, if registered.
dispatch_rx: Dispatch a blocking operation closure to a registered pool, returning a future for awaiting the result.
is_dispatch_pool_registered: Return true if a DispatchPool is registered to the current thread.
register_dispatch_pool: Register a DispatchPool on the calling thread.

Semaphore: An async-aware semaphore for constraining the number of concurrent blocking operations.