alloc::task::UnsafeWake - Rust
Description: API documentation for the Rust `UnsafeWake` trait in crate `alloc`.
Keywords: rust, rustlang, rust-lang, UnsafeWake

# [−][src]Trait alloc::task::UnsafeWake

    pub unsafe trait UnsafeWake: Send + Sync {
        unsafe fn clone_raw(&self) -> Waker;
        unsafe fn drop_raw(&self);
        unsafe fn wake(&self);

        unsafe fn wake_local(&self) { ... }
    }

🔬 This is a nightly-only experimental API. (`futures_api` #50547)

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` #50547)

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` #50547)

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:

ⓘ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 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` #50547)

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` #50547)

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.

## 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`)

Search multiple things at once by splitting your query with comma (e.g. `str,u8` or `String,struct:Vec,test`)