# Trait futures::executor::UnsafeNotify [−] [src]

    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:

ⓘThis example is not tested

    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

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)