Crate future_handles

Overview

A crate to complete futures via a remote handle.

Although it’s design shouldn’t restrain future_handles use cases, this crate was primarily conceived to bridge asynchronous functions running callbacks at competition with rust’s async/await paradigm.

Features

• No locking overhead for single-threaded environments.
• Optional thread-safety with spin-locks.
• Futures always complete with an error if the handle is dropped.
• Both channel-like and scoped APIs.

Examples

Channel-like API:

async fn func() -> Option<u32> {
    let (future, handle) = unsync::create();

    func_with_callback(|res| {
        handle.complete(res);
    });

    future.await.ok()
}

Scoped API:

async fn func() -> Option<u32> {
    let future = unsync::scoped(|handle| {
        func_with_callback(|res| {
            handle.complete(res);
        });
    });

    future.await.ok()
}

Thread safety

This crate comes a non thread-safe unsync implementation by default. To make the sync thread-safe implementation available, enable the sync feature.

Danger!

Do NOT do this!

async fn func() {
    let (future, handle) = unsync::create();

    // Start awaiting here...
    future.await.unwrap();
    // Now we'll never be able set the result!
    handle.complete(1);
}

Awaiting a CompletableFuture before setting the result or dropping the associated CompleteHandle will cause a deadlock!

Modules

syncsync

A thread-safe CompletableFuture and CompleteHandle implementation.

unsync

A non thread-safe CompletableFuture and CompleteHandle implementation.

Enums

HandleError

The error returned by CompletableFutures.

Type Aliases

HandleResult

A convenience type to wrap a HandleError in a Result.