Struct UnsafeFuture

pub struct UnsafeFuture { /* private fields */ }

A handle to a future data.

Name contains future, but this struct doesn’t implement Future trait. It provides you poll function instead. You can call poll function on a handle and get the result if the FutureData is ready.

Plus, this is actually a type-erased pointer to a FutureData so that owners must deal with the pointer carefully. See the example below to get a feel for how to use the struct.

Examples

use my_ecs::ds::{WakeSend, UnsafeFuture, ReadyFuture};
use std::{
    future::Future,
    task::{Poll, Context},
    sync::mpsc::{self, Sender},
    pin::Pin,
};

#[derive(Clone)]
struct MyWaker(Sender<UnsafeFuture>);

impl WakeSend for MyWaker {
    fn wake_send(&self, handle: UnsafeFuture) {
        self.0.send(handle).unwrap();
    }
}

struct MyFuture(u32);

impl Future for MyFuture {
    type Output = u32;

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        let this = self.get_mut();
        if this.0 == 0 {
            Poll::Ready(10)
        } else {
            this.0 -= 1;
            cx.waker().wake_by_ref();
            Poll::Pending
        }
    }
}

let (tx, rx) = mpsc::channel();
let fut = MyFuture(2);
let waker = MyWaker(tx);
let consume = |ret: u32, arg: u32| ret + arg;
let mut u_fut = UnsafeFuture::new(fut, waker, consume);

unsafe {
    let mut pending = 0;
    while u_fut.poll() == Poll::Pending {
        u_fut = rx.recv().unwrap();
        pending += 1;
    }
    let r_fut = ReadyFuture::new(u_fut);
    let res: u32 = r_fut.consume(1);

    assert_eq!(pending, 2);
    assert_eq!(res, consume(10, 1));
}

Implementations

impl UnsafeFuture

pub fn new<F, R, W, Arg, CR>( future: F, waker: W, consume: fn(R, Arg) -> CR, ) -> Self

where F: Future<Output = R> + Send + 'static, R: Send + 'static, W: WakeSend,

Creates a future data in heap memory and returns its handle.

Leaks

There will be memory leak if caller doesn’t deallocate the future data. Future data can be deallocated by

• Calling UnsafeFuture::destroy.
• Turning UnsafeFuture into ReadyFuture then dropping it. ReadyFuture calls UnsafeFuture::destroy when it’s dropped.

Examples

See UnsafeFuture documentation.

pub unsafe fn destroy(self)

Drops and deallocates associated future data.

You may need this method when you have to cancel out not ready futures.

Safety

This method must be called only once for the same handles.

pub unsafe fn is_ready(&self) -> bool

Returns true if associated future data is ready.

Safety

Undefined behavior if associated FutureData has been dropped.

pub unsafe fn poll(self) -> Poll<()>

Tries to make more progress on the associated future data.

Returning value Poll::Ready means the FutureData is completely resolved and ready to provide its output. Poll::Pending, on the other hand, means the FutureData is not yet ready and will wake async runtime via the waker you inserted at UnsafeFuture::new when it can make more progress.

Safety

Associated future data must be alive, not have been dropped.

Examples

See UnsafeFuture documentation.

pub unsafe fn will_wake<W>(self, other: &W) -> bool

where W: WakeSend + PartialEq,

Returns true if the given waker is the same as the type you inserted at UnsafeFuture::new.

Safety

Waker type W must be the same as the type you inserted at UnsafeFuture::new.

pub unsafe fn set_waker<W>(self, waker: W) -> W

where W: WakeSend,

Sets a new waker to the associated future data.

Safety

Waker type W must be the same as the type you inserted at UnsafeFuture::new.

Trait Implementations

impl Clone for UnsafeFuture

fn clone(&self) -> UnsafeFuture

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for UnsafeFuture

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for UnsafeFuture

fn eq(&self, other: &UnsafeFuture) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for UnsafeFuture

impl Eq for UnsafeFuture

impl Send for UnsafeFuture

impl StructuralPartialEq for UnsafeFuture