2 unstable releases
new 0.4.0 | Oct 26, 2024 |
---|---|
0.1.0 | Feb 7, 2023 |
#2211 in Asynchronous
3,826 downloads per month
Used in 17 crates
(via pollster)
10KB
81 lines
Pollster
Pollster is an incredibly minimal async executor for Rust that lets you block a thread until a future completes.
use pollster::FutureExt as _;
let my_fut = async {};
let result = my_fut.block_on();
That's it. That's all it does. Nothing more, nothing less. No need to pull in 50 crates to evaluate a future.
Why is this useful?
Now that async
functions are stable, we're increasingly seeing libraries all over the Rust ecosystem expose async
APIs. This is great for those wanting to build highly concurrent web applications!
However, many of us are not building highly concurrent web applications, but end up faced with an async
function
that we can't easily call from synchronous code. If you're in this position, then pollster
is for you: it allows you
to evaluate a future in-place without spinning up a heavyweight runtime like tokio
or async_std
.
Minimalism
Pollster is built with the UNIX ethos in mind: do one thing, and do it well. It has no dependencies, compiles quickly, and is composed of only ~100 lines of well-audited code.
Behaviour
Pollster will synchronously block the thread until a future completes. It will not spin: instead, it will place the thread into a waiting state until the future has been polled to completion.
Compatibility
Unfortunately, pollster
will not work for all futures because some require a specific runtime or reactor. See
here for more
information about when and where pollster
may be used. However, if you're already pulling in the required dependencies
to create such a future in the first place, it's likely that you already have a version of block_on
in your dependency
tree that's designed to poll your future, so use that instead.
Macro
When using the macro
crate feature, an attribute-macro can be used to mark async fn main()
:
#[pollster::main]
async fn main() {
let my_fut = async {};
my_fut.await;
}
Additionally if you have re-exported the crate with a different name then pollster
, you have to specify it:
#[pollster::main(crate = renamed_pollster)]
async fn main() {
let my_fut = async {};
my_fut.await;
}
You can also use #[pollster::test]
for tests.
Comparison with futures::executor::block_on
pollster
does approximately the same thing as the block_on
function from the futures
crate. If you already have futures
in your dependency tree, you might as well use it instead. pollster
is primarily for applications that don't care to pull all of futures
or another runtime like tokio
into their dependency tree for the sake of evaluating simple futures.
Minimum Supported Rust Version (MSRV) Policy
Current MSRV: 1.69.0
pollster
has a policy of supporting compiler versions that are at least 18 months old. The crate may compile with
older compilers, but this is not guaranteed.
Dependencies
~245–690KB
~17K SLoC