[−][src]Trait futures::task::UnsafeWake
🔬 This is a nightly-only experimental API. (futures_api
)
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
.
Required Methods
unsafe fn clone_raw(&self) -> Waker
🔬 This is a nightly-only experimental API. (futures_api
)
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
)
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
)
futures in libcore are unstable
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 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
)
futures in libcore are unstable
Indicates that the associated task is ready to make progress and should
be poll
ed. 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.