pollster

Behavior

Pollster synchronously blocks the thread until a future completes. It does not 'spin' (busy-wait); instead, it places the thread into a waiting state until the future has been polled to completion.

Compatibility

Pollster is not compatible with all futures. Some futures require a specific runtime or reactor (e.g., for I/O or timers). If your future requires a specific ecosystem, you should use the block_on implementation provided by that ecosystem's runtime (like tokio or async_std) rather than pollster.

If you have an async function or future that you need to call from synchronous code, you can use pollster::FutureExt::block_on to synchronously block the current thread until the future completes. This is a lightweight alternative to pulling in a full runtime like tokio or async_std when you only need to evaluate a simple future in-place.

use pollster::FutureExt as _;

let my_fut = async {};

let result = my_fut.block_on();

By enabling the macro crate feature, you can use the #[pollster::main] attribute macro to allow your main function to be async. This handles the boilerplate of blocking the main thread to execute the async entry point.

If you have re-exported the pollster crate under a different name, you must specify the original name using the crate argument.

#[pollster::main]
async fn main() {
    let my_fut = async {};

    my_fut.await;
}

If re-exported:

#[pollster::main(crate = renamed_pollster)]
async fn main() {
    let my_fut = async {};

    my_fut.await;
}

When the macro feature is enabled, you can use the #[pollster::test] attribute to define asynchronous test functions, allowing you to .await futures directly within your tests.

#[pollster::test]
async fn my_async_test() {
    // your async test code here
}

The FutureExt trait provides a convenience method block_on() that can be called directly on any type implementing IntoFuture. To use this, you must bring the trait into scope.

This is a suffix-position method that internally calls pollster::block_on.

use pollster::FutureExt as _;

let my_fut = async {};
let result = my_fut.block_on();

Use pollster::block_on to execute a future to completion by blocking the current thread. This is useful for running asynchronous code within a synchronous context.

Note that this function will park the current thread and wait for the future to signal readiness via a local waker.

let my_fut = async {};
let result = pollster::block_on(my_fut);