Struct poll_promise::Promise

pub struct Promise<T: Send + 'static> { /* private fields */ }

A promise that waits for the reception of a single value, presumably from some async task.

A Promise starts out waiting for a value. Each time you call a member method it will check if that value is ready. Once ready, the Promise will store the value until you drop the Promise.

Example:

let promise = Promise::spawn_thread("slow_operation", move || 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 screen
}

If you enable the tokio feature you can use poll-promise with the tokio runtime to run async tasks using Promise::spawn_async, Promise::spawn_local, and Promise::spawn_blocking.

Implementations

impl<T: Send + 'static> Promise<T>

pub fn new() -> (Sender<T>, Self)

Create a Promise and a corresponding Sender.

Put the promised value into the sender when it is ready. If you drop the Sender without putting a value into it, it will cause a panic when polling the Promise.

See also Self::spawn_blocking, Self::spawn_async, Self::spawn_local, and Self::spawn_thread.

pub fn from_ready(value: T) -> Self

Create a promise that already has the result.

pub fn spawn_async(future: impl Future<Output = T> + 'static + Send) -> Self

Available on crate features tokio or smol or async-std only.

Spawn a future. Runs the task concurrently.

See Self::spawn_local.

You need to compile poll-promise with the “tokio” feature for this to be available.

tokio

This should be used for spawning asynchronous work that does not do any heavy CPU computations as that will block other spawned tasks and will delay them. For example network IO, timers, etc.

These type of future can have manually blocking code within it though, but has to then manually use tokio::task::block_in_place on that, or .await that future.

If you have a function or closure that you just want to offload to processed in the background, use the Self::spawn_blocking function instead.

See the tokio docs for more details about CPU-bound tasks vs async IO tasks.

This is a convenience method, using Self::new with tokio::task::spawn.

Example

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

pub fn spawn_local(future: impl Future<Output = T> + 'static) -> Self

Available on crate features tokio or web or smol only.

Spawn a future. Runs it in the local thread.

You need to compile poll-promise with either the “tokio”, “smol”, or “web” feature for this to be available.

This is a convenience method, using Self::new with tokio::task::spawn_local. Unlike Self::spawn_async this method does not require Send. However, you will have to set up tokio::task::LocalSets yourself.

Example

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

pub fn spawn_blocking<F>(f: F) -> Selfwhere F: FnOnce() -> T + Send + 'static,

Available on crate features tokio or async-std only.

Spawn a blocking closure in a background task.

You need to compile poll-promise with the “tokio” feature for this to be available.

tokio

This is a simple mechanism to offload a heavy function/closure to be processed in the thread pool for blocking CPU work.

It can’t do any async code. For that, use Self::spawn_async.

This is a convenience method, using Self::new with tokio::task::spawn and tokio::task::block_in_place.

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

pub fn spawn_thread<F>(thread_name: impl Into<String>, f: F) -> Selfwhere F: FnOnce() -> T + Send + 'static,

Available on non-WebAssembly only.

Spawn a blocking closure in a background thread.

The first argument is the name of the thread you spawn, passed to std::thread::Builder::name. It shows up in panic messages.

This is a convenience method, using Self::new and std::thread::Builder.

If you are compiling with the “tokio” or “web” features, you should use Self::spawn_blocking or Self::spawn_async instead.

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

pub fn ready(&self) -> Option<&T>

Polls the promise and either returns a reference to the data, or None if still pending.

Panics if the connected Sender was dropped before a value was sent.

pub fn ready_mut(&mut self) -> Option<&mut T>

Polls the promise and either returns a mutable reference to the data, or None if still pending.

Panics if the connected Sender was dropped before a value was sent.

pub fn try_take(self) -> Result<T, Self>

Returns either the completed promise object or the promise itself if it is not completed yet.

Panics if the connected Sender was dropped before a value was sent.

pub fn block_until_ready(&self) -> &T

Block execution until ready, then returns a reference to the value.

Panics if the connected Sender was dropped before a value was sent.

pub fn block_until_ready_mut(&mut self) -> &mut T

Block execution until ready, then returns a mutable reference to the value.

Panics if the connected Sender was dropped before a value was sent.

pub fn block_and_take(self) -> T

Block execution until ready, then returns the promised value and consumes the Promise.

Panics if the connected Sender was dropped before a value was sent.

pub fn poll(&self) -> Poll<&T>

Returns either a reference to the ready value std::task::Poll::Ready or std::task::Poll::Pending.

Panics if the connected Sender was dropped before a value was sent.

pub fn poll_mut(&mut self) -> Poll<&mut T>

Returns either a mut reference to the ready value in a std::task::Poll::Ready or a std::task::Poll::Pending.

Panics if the connected Sender was dropped before a value was sent.

pub fn task_type(&self) -> TaskType

Returns the type of task this promise is running. See TaskType.

pub fn abort(self)

Available on crate feature tokio only.

Abort the running task spawned by Self::spawn_async.