blocking_permit/
lib.rs

1//! This crate provides:
2//!
3//! * A specialized, custom thread pool, [`DispatchPool`], for offloading
4//!   blocking or otherwise long running operations from a main or reactor
5//!   thread(s). Once registered, it is used via [`dispatch_rx()`] (to await a
6//!   return value) or [`dispatch()`] for background tasks (fire and forget).
7//!
8//! * A [`BlockingPermit`], obtained via [`blocking_permit_future()`] for
9//!   limiting the number of concurrent blocking operations via a re-exported
10//!   [`Semaphore`] type selected by one of the (non-default) features
11//!   _futures-intrusive_, or _tokio-semaphore_ (or _tokio-omnibus_).
12//!
13//! * A [`Cleaver`] for splitting `Stream` buffers into more manageable sizes.
14//!
15//! * A [`YieldStream`] for yielding between `Stream` items.
16//!
17//! ## Optional Features
18//!
19//! The following features may be enabled at build time. **All are disabled by
20//! default, unless otherwise noted.**
21//!
22//! _futures-channel_
23//! : Use this oneshot channel implementation (Default
24//!   enabled, but overridden by _tokio-oneshot_ or _tokio-omnibus_.)
25//!
26//! _tokio-oneshot_
27//! : Use tokio's oneshot channel implementation (Overrides _futures-channel_
28//!   default.).
29//!
30//! _futures-intrusive_
31//! : Include `BlockingPermit` and re-export `Semaphore` from the
32//!   _futures-intrusive_ crate. (Works with all prominent runtimes.)
33//!
34//! _tokio-semaphore_
35//! : Include `BlockingPermit` and re-export tokio's `Semaphore`
36//!   type. (Overrides _futures-intrusive_.)
37//!
38//! _tokio-threaded_
39//! : Add `block_in_place` support, exposed via [`BlockingPermit::run`].
40//!
41//! _tokio-omnibus_
42//! : A simpler way to include all above and, we expect, any future added
43//!   _tokio-*_ features in this crate.
44//!
45//! _cleaver_
46//! : Include the [`Cleaver`] wrapper stream.
47//!
48//! _yield-stream_
49//! : Include the [`YieldStream`] wrapper.
50
51#![warn(rust_2018_idioms)]
52
53mod dispatch;
54mod dispatch_pool;
55mod errors;
56
57#[cfg(any(feature = "tokio-semaphore", feature = "futures-intrusive"))]
58mod permit;
59
60#[cfg(any(feature = "tokio-semaphore", feature = "futures-intrusive"))]
61#[macro_use] mod macros;
62
63pub use dispatch::{
64    dispatch,
65    dispatch_rx,
66    is_dispatch_pool_registered,
67    register_dispatch_pool,
68    deregister_dispatch_pool,
69    Dispatched,
70    DispatchRx,
71};
72
73pub use dispatch_pool::{DispatchPool, DispatchPoolBuilder};
74
75pub use errors::Canceled;
76
77#[cfg(any(feature = "tokio-semaphore", feature = "futures-intrusive"))]
78pub use permit::{
79    blocking_permit_future,
80    BlockingPermit,
81    BlockingPermitFuture,
82    Semaphorish,
83    SyncBlockingPermitFuture,
84};
85
86#[cfg(feature = "cleaver")]
87mod cleaver;
88
89#[cfg(feature = "cleaver")]
90pub use cleaver::{
91    Cleaver,
92    Splittable,
93};
94
95#[cfg(feature = "yield-stream")]
96mod yield_stream;
97
98#[cfg(feature = "yield-stream")]
99pub use yield_stream::YieldStream;
100
101/// An async-aware semaphore for constraining the number of concurrent blocking
102/// operations.
103///
104/// This re-exported type is either `futures_intrusive::sync::Semaphore`
105/// (_futures-intrusive_ feature) or `tokio::sync::Semaphore`
106/// (_tokio-semaphore_ or _tokio-omnibus_ features).
107///
108/// ----------
109///
110#[cfg(any(feature = "tokio-semaphore", feature = "futures-intrusive"))]
111#[doc(inline)]
112pub use permit::Semaphore;
113
114#[cfg(test)]
115mod tests;
116
117#[cfg(any(feature = "tokio-semaphore", feature = "futures-intrusive"))]
118#[cfg(test)]
119mod fs;
blocking_permit/lib.rs

blocking_permit/
lib.rs
