Trait core::task::UnsafeWake

pub unsafe trait UnsafeWake: Send + Sync {
    unsafe fn clone_raw(&self) -> Waker;
    unsafe fn drop_raw(&self);
    unsafe fn wake(&self);

    unsafe fn wake_local(&self) { ... }
}

🔬 This is a nightly-only experimental API. (futures_api #50547)

futures in libcore are unstable

An unsafe trait for implementing custom memory management for a Waker or LocalWaker.

A Waker conceptually is a cloneable trait object for Wake, and is most often essentially just Arc<dyn Wake>. However, in some contexts (particularly no_std), it's desirable to avoid Arc in favor of some custom memory management strategy. This trait is designed to allow for such customization.

When using std, a default implementation of the UnsafeWake trait is provided for Arc<T> where T: Wake and Rc<T> where T: LocalWake.

Although the methods on UnsafeWake take pointers rather than references,

Required Methods

unsafe fn clone_raw(&self) -> Waker

🔬 This is a nightly-only experimental API. (futures_api #50547)

futures in libcore are unstable

Creates a clone of this UnsafeWake and stores it behind a Waker.

This function will create a new uniquely owned handle that under the hood references the same notification instance. In other words calls to wake on the returned handle should be equivalent to calls to wake on this handle.

Unsafety

This function is unsafe to call because it's asserting the UnsafeWake value is in a consistent state, i.e. hasn't been dropped.

unsafe fn drop_raw(&self)

🔬 This is a nightly-only experimental API. (futures_api #50547)

futures in libcore are unstable

Drops this instance of UnsafeWake, deallocating resources associated with it.

FIXME(cramertj) This method is intended to have a signature such as:

fn drop_raw(self: *mut Self);

Unfortunately in Rust today that signature is not object safe. Nevertheless it's recommended to implement this function as if that were its signature. As such it is not safe to call on an invalid pointer, nor is the validity of the pointer guaranteed after this function returns.

Unsafety

This function is unsafe to call because it's asserting the UnsafeWake value is in a consistent state, i.e. hasn't been dropped.

unsafe fn wake(&self)

🔬 This is a nightly-only experimental API. (futures_api #50547)

futures in libcore are unstable

Indicates that the associated task is ready to make progress and should be polled.

Executors generally maintain a queue of "ready" tasks; wake should place the associated task onto this queue.

Panics

Implementations should avoid panicking, but clients should also be prepared for panics.

Unsafety

This function is unsafe to call because it's asserting the UnsafeWake value is in a consistent state, i.e. hasn't been dropped.

Provided Methods

unsafe fn wake_local(&self)

🔬 This is a nightly-only experimental API. (futures_api #50547)

futures in libcore are unstable

Indicates that the associated task is ready to make progress and should be polled. This function is the same as wake, but can only be called from the thread that this UnsafeWake is "local" to. This allows for implementors to provide specialized wakeup behavior specific to the current thread. This function is called by LocalWaker::wake.

Executors generally maintain a queue of "ready" tasks; wake_local should place the associated task onto this queue.

Panics

Implementations should avoid panicking, but clients should also be prepared for panics.

Unsafety

This function is unsafe to call because it's asserting the UnsafeWake value is in a consistent state, i.e. hasn't been dropped, and that the UnsafeWake hasn't moved from the thread on which it was created.

Implementors