Skip to content

windows-future.md

Latest commit

 

History

History
98 lines (69 loc) · 4.01 KB

windows-future.md

File metadata and controls

98 lines (69 loc) · 4.01 KB
Raw

windows-future

Stock async types for Windows APIs.

windows-future provides IAsyncOperation and the related WinRT async interfaces, with conveniences for producing and consuming them from Rust.

When to use

Use this crate when an API returns one of the four WinRT async interfaces, or when your own WinRT API must return one:

  • IAsyncAction
  • IAsyncOperation<T>
  • IAsyncActionWithProgress<P>
  • IAsyncOperationWithProgress<T, P>

Use an async runtime's native task type for Rust-only work that does not cross a WinRT boundary. windows-future adapts WinRT operations to Rust futures; it is not an async executor.

Getting started

The crate README has the dependency declaration and a minimal ready/spawn example. A typical first workflow is to receive an IAsyncOperation<T> from a Windows API, choose how the surrounding code should wait for it, and propagate its windows_core::Result<T>:

async fn consume(operation: windows_future::IAsyncOperation<i32>) -> windows_core::Result<i32> {
    let value = operation.await?;
    Ok(value + 1)
}

The operation begins according to the WinRT API's rules; converting it into a future does not create or schedule the operation.

Consuming an operation

Choose one completion style and let it own the operation's completion handler:

Style Use it when
.await The caller is already async and the default std feature is enabled.
join() Synchronous code may block the current thread until completion.
when(callback) Completion should invoke a Send + 'static callback without blocking.

All three paths return or receive a Result, including failures reported by the WinRT operation. Avoid join() on a UI thread or another thread that must continue pumping work.

Producing an operation

ready wraps a result that is already available. spawn runs a Send + 'static closure on the Windows thread pool and exposes its result as a WinRT async object. Pick IAsyncAction for () and IAsyncOperation<T> for a value. The progress variants provide the corresponding interface shape, but closures passed to spawn do not report intermediate progress.

The std feature is enabled by default and supplies ready, spawn, and the IntoFuture implementation used by .await. Without it, the interface types and the join/when consumption helpers remain available.

Platform constraints and pitfalls

  • The crate targets Windows and WinRT async interfaces.
  • A WinRT completion handler can be assigned only once. These helpers may assign that handler while an operation is running, so do not combine them or a direct SetCompleted call on one operation.
  • spawn is for blocking or synchronous work that is safe on a pool thread. It does not make thread-affine UI or COM work safe to move off its owning thread.
  • ready and spawn expose Cancel and Close through IAsyncInfo, but these constructors do not interrupt the supplied closure.

Sample and next steps

The spawn sample contrasts an immediately ready operation with work submitted to the Windows thread pool. Next, inspect the API that produces your operation to determine its result type, error behavior, cancellation support, and any thread affinity.

Internal documentation

The remainder of this page covers how the crate is built and maintained. It is for contributors and is not needed to use windows-future.

How it's built

src/bindings.rs is generated by tool-bindings from crates/tools/bindings/src/future.txt and future_impl.txt; the Future bridge is hand-written.

Testing

Run cargo test -p windows-future; see also the workspace test crates.