[−][src]Trait futures::executor::UnsafeNotify
An unsafe trait for implementing custom forms of memory management behind a
Task
.
The futures
critically relies on "notification handles" to extract for
futures to contain and then later inform that they're ready to make
progress. These handles, however, must be cheap to create and cheap
to clone to ensure that this operation is efficient throughout the
execution of a program.
Typically this sort of memory management is done in the standard library
with the Arc
type. An Arc
is relatively cheap to allocate an is
quite cheap to clone and pass around. Plus, it's 100% safe!
When working outside the standard library, however, you don't always have
and Arc
type available to you. This trait, UnsafeNotify
, is intended
to be the "unsafe version" of the Notify
trait. This trait encodes the
memory management operations of a Task
's notification handle, allowing
custom implementations for the memory management of a notification handle.
Put another way, the core notification type in this library,
NotifyHandle
, simply internally contains an instance of
*mut UnsafeNotify
. This "unsafe trait object" is then used exclusively
to operate with, dynamically dispatching calls to clone, drop, and notify.
Critically though as a raw pointer it doesn't require a particular form
of memory management, allowing external implementations.
A default implementation of the UnsafeNotify
trait is provided for the
Arc
type in the standard library. If the use_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 NotifyHandle::new
.
Unsafety
This trait is manually encoding the memory management of the underlying handle, and as a result is quite unsafe to implement! Implementors of this trait must guarantee:
- Calls to
clone_raw
produce uniquely owned handles. It should be safe to drop the current handle and have the returned handle still be valid. - 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. When in doubt ping the
futures
authors to clarify an unsafety question here.
Required methods
unsafe fn clone_raw(&self) -> NotifyHandle
Creates a new NotifyHandle
from this instance of UnsafeNotify
.
This function will create a new uniquely owned handle that under the
hood references the same notification instance. In other words calls
to notify
on the returned handle should be equivalent to calls to
notify
on this handle.
Unsafety
This trait is unsafe to implement, as are all these methods. This
method is also unsafe to call as it's asserting the UnsafeNotify
value is in a consistent state. In general it's recommended to
review the trait documentation as well as the implementation for Arc
in this crate. When in doubt ping the futures
authors to clarify
an unsafety question here.
unsafe fn drop_raw(&self)
Drops this instance of UnsafeNotify
, 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 trait is unsafe to implement, as are all these methods. This
method is also unsafe to call as it's asserting the UnsafeNotify
value is in a consistent state. In general it's recommended to
review the trait documentation as well as the implementation for Arc
in this crate. When in doubt ping the futures
authors to clarify
an unsafety question here.