Trait UnsafeWake

pub unsafe trait UnsafeWake {
    // Required methods
    unsafe fn clone_raw(&self) -> Waker;
    unsafe fn drop_raw(&self);
    unsafe fn wake(&self);
}

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

A Waker is a cloneable trait object for Wake, and is most often essentially just Arc<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.

A default implementation of the UnsafeWake trait is provided for the Arc type in the standard library. If the std feature of this crate is not available however, you’ll be required to implement your own instance of this trait to pass it into Waker::new.

Unsafety

This trait manually encodes the memory management of the underlying trait object. Implementors of this trait must guarantee:

• Calls to clone_raw produce uniquely owned Waker handles. These handles should be independently usable and droppable.

• Calls to drop_raw work with self as a raw pointer, deallocating resources associated with it. This is a pretty unsafe operation as it’s invalidating the self pointer, so extreme care needs to be taken.

In general it’s recommended to review the trait documentation as well as the implementation for Arc in this crate before attempting a custom implementation.

Required Methods

unsafe fn clone_raw(&self) -> Waker

Creates a new Waker from this instance of UnsafeWake.

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 is also 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)

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

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 is also 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)

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 is also unsafe to call because it’s asserting the UnsafeWake value is in a consistent state, i.e. hasn’t been dropped

Implementors