pub unsafe trait UnsafeWake {
// Required methods
unsafe fn clone_raw(&self) -> Waker;
unsafe fn drop_raw(&self);
unsafe fn wake(&self);
}
Expand description
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 ownedWaker
handles. These handles should be independently usable and droppable. -
Calls to
drop_raw
work withself
as a raw pointer, deallocating resources associated with it. This is a pretty unsafe operation as it’s invalidating theself
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§
Sourceunsafe fn clone_raw(&self) -> Waker
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.
Sourceunsafe fn drop_raw(&self)
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
Sourceunsafe fn wake(&self)
unsafe fn wake(&self)
Indicates that the associated task is ready to make progress and should
be poll
ed.
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