Trait futures::executor::UnsafeNotify

pub unsafe trait UnsafeNotify: Notify {
    unsafe fn clone_raw(&self) -> NotifyHandle;
    unsafe fn drop_raw(&self);
}

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 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. 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.

Implementors