poll-promise

The poll-promise crate is intended as a high-level building block for applications (like games or GUIs).

Do not use this crate in libraries.

Because the crate provides convenience methods for spawning threads and Tokio tasks, as well as methods that block while waiting for results, it makes decisions about execution environments and thread blocking. These decisions should be left to the application using the library, not the library itself.

To use poll-promise, you can spawn a background operation using Promise::spawn_thread and then call .ready() within your main loop. .ready() returns Some(T) if the operation is complete, or None if it is still running. This allows you to switch between showing a loading state and the actual result seamlessly.

let promise = poll_promise::Promise::spawn_thread("slow_operation", something_slow);

// Then in the game loop or immediate mode GUI code:
if let Some(result) = promise.ready() {
    // Use/show result
} else {
    // Show a loading icon
}

Use spawn_thread to run a blocking closure in a dedicated background thread. This is the preferred method if you are not using an async runtime (like Tokio or Smol). The first argument is a thread name used for identification in panic messages.

Note: If you are using tokio or web features, use spawn_blocking or spawn_async instead.

Constraint: This method is not available when compiling for wasm32 (WebAssembly) as Wasm does not support spawning threads.

# fn something_slow() {}
# use poll_promise::Promise;

let promise = Promise::spawn_thread("slow_operation", move || something_slow());

If you have spawned a task using spawn_async and are using the tokio feature, you can call .abort() on the Promise to cancel the underlying task.

// Requires 'tokio' feature
let promise = Promise::spawn_async(async { ... });

// ... later ...
promise.abort();

Use these methods to check the status of a Promise without blocking execution:

• ready(&self) -> Option<&T>: Returns a reference to the value if ready, otherwise None.
• ready_mut(&mut self) -> Option<&mut T>: Returns a mutable reference to the value if ready, otherwise None.
• poll(&self) -> std::task::Poll<&T>: Returns Poll::Ready(value) or Poll::Pending.
• poll_mut(&mut self) -> std::task::Poll<&mut T>: Returns Poll::Ready(value) or Poll::Pending.

Warning: All polling methods will panic if the connected Sender was dropped before a value was sent.

If you need to halt execution until the background task completes, use these blocking methods.

Warning: These methods are not allowed on Wasm and will not compile/run there.

• block_until_ready(&self) -> &T: Blocks until ready, then returns a reference.
• block_until_ready_mut(&mut self) -> &mut T: Blocks until ready, then returns a mutable reference.
• block_and_take(self) -> T: Blocks until ready, then consumes the Promise and returns the owned value T.

Spawns a Future to run on the local thread. Unlike spawn_async, the future passed to spawn_local does not need to implement Send.

Requirements: Requires tokio, smol, or web features.

Note: If using tokio, you must manually set up tokio::task::LocalSets for this to function correctly.

# async fn something_async() {}
# use poll_promise::Promise;

let promise = Promise::spawn_local(async move { something_async().await });

Offloads heavy CPU-bound work to a thread pool designed for blocking operations. This prevents the async executor from being stalled.

Requirements: Requires tokio or async-std features.

Usage: Use this instead of spawn_async for any task that performs significant computation or synchronous blocking IO.

# fn something_cpu_intensive() {}
# use poll_promise::Promise;

let promise = Promise::spawn_blocking(move || something_cpu_intensive());