Crate owned_future 

This tiny crate contains helpers to turn a borrowed future into an owned one.

Motivation

Take tokio::sync::Notify as an example. A common paradigm is to call Notify::notified before a relevant threading update/check, then perform the update/check, and then wait on the resulting Notified future. Doing this guarantees the Notified is watching for calls to Notify::notify_waiters prior to the update/check. This paradigm would be useful when dealing with thread spawning (i.e. calling notified and moving the resulting future into the thread), but this isn’t possible with notified as it borrows the Notify.

use std::sync::Arc;
use tokio::sync::Notify;

let notify = Arc::new(Notify::new());

// Spawn a thread that waits to be notified
{
    // Copy the Arc
    let notify = notify.clone();

    // Start listening before we spawn
    let notified = notify.notified();

    // Spawn the thread
    tokio::spawn(async move {
        // Wait for our listen to complete
        notified.await; // <-- fails because we can't move `notified`
    });
}

// Notify the waiting threads
notify.notify_waiters();

At present, there’s no easy way to do this kind of borrow-then-move. While there are many crates available to help turn this problem into a self-borrowing one, those solutions require unsafe code with complicated covariance implications. This crate is instead able to solve this simple case with no unsafe, and more complex cases are solved with only 1-2 lines of unsafe code with no covariance meddling. Here is the solution to the above problem:

use std::sync::Arc;
use tokio::sync::Notify;
use owned_future::make;

// Make the constructor for our future
let get_notified = owned_future::get!(fn(n: &mut Arc<Notify>) -> () {
    n.notified()
});

let notify = Arc::new(Notify::new());

// Spawn a thread that waits to be notified
{
    // Copy the Arc
    let notify = notify.clone();

    // Start listening before we spawn
    let notified = make(notify, get_notified);

    // Spawn the thread
    tokio::spawn(async move {
        // wait for our listen to complete
        notified.await;
    });
}

// notify the waiting threads
notify.notify_waiters();

Technical Details

So how does this work exactly? Rust doesn’t usually let you move a borrowed value, but there’s one exception. Pinned async blocks. Once a value has been moved into an async block, and the the block has been transformed into a Pinned Future, during the execution of the future, the borrow can be executed, but the pointer anchoring the future can still be freely moved around. All that may sound a little confusing, but essentially what this crate does is a prettied up version of this:

// Copy the Arc
let notify = notify.clone();

let mut wrapped_notified = Box::pin(async move {
    let notified = notify.notified();

    // This prevents us from driving the future to completion on the first poll
    force_pause().await;

    future.await
});

// Drive the future up to just past our `force_pause`.
// This will start listening before we spawn
wrapped_notified.poll_once()

// Spawn the thread
tokio::spawn(async move {
    // wait for our listen to complete
    wrapped_notified.await;
});

// notify the waiting threads
notify.notify_waiters();

The more complex wrappers have a little bit more machinery to handle auxiliary values and errors, and the Async* helpers do a little bit of pin-projection and poll handling, but ultimately the core logic boils down to something like the above.

Macros

async_send_try_get

A macro for quickly implementing crate::AsyncSendTryGetFut without capturing.

async_try_get

A macro for quickly implementing crate::AsyncTryGetFut without capturing.

get

A macro for quickly implementing crate::GetFut without capturing.

try_get

A macro for quickly implementing crate::TryGetFut without capturing.

Structs

AsyncSendTry

Try to encapsulate an async-constructed borrowed-future along with it’s owner.

AsyncTry

Try to encapsulate an async-constructed borrowed-future along with it’s owner.

Traits

ApplyGetFut

An extension trait to call crate::get

AsyncSendTryApplyGetFut

An extension trait to call crate::AsyncSendTry

AsyncSendTryGetFut

A functor trait for trying to get a complex future from an input.

AsyncTryApplyGetFut

An extension trait to call crate::AsyncTry

AsyncTryGetFut

A functor trait for trying to get a complex future from an input.

GetFut

A functor trait for getting a simple future from an input.

TryApplyGetFut

An extension trait to call crate::try_get

TryGetFut

A functor trait for trying to get a complex future from an input.

Functions

make

Encapsulate a borrowed-future along with it’s owner.

try_make

Try to encapsulate a borrowed-future along with it’s owner.

Type Aliases

AsyncSendTryOutput

An alias for the output type of AsyncSendTry

AsyncTryOutput

An alias for the output type of AsyncTry