Skip to content

Commit

Permalink
Add Waker::new and LocalWaker::new
Browse files Browse the repository at this point in the history
Per the `waker_getters` FCP:
rust-lang#96992 (comment)

Docs largely copied from `RawWaker::new`.
  • Loading branch information
kevinmehall committed Sep 3, 2024
1 parent 2dc7514 commit 22bd319
Showing 1 changed file with 55 additions and 0 deletions.
55 changes: 55 additions & 0 deletions library/core/src/task/wake.rs
Original file line number Diff line number Diff line change
Expand Up @@ -493,6 +493,37 @@ impl Waker {
a_data == b_data && ptr::eq(a_vtable, b_vtable)
}

/// Creates a new `Waker` from the provided `data` pointer and `vtable`.
///
/// The `data` pointer can be used to store arbitrary data as required
/// by the executor. This could be e.g. a type-erased pointer to an `Arc`
/// that is associated with the task.
/// The value of this pointer will get passed to all functions that are part
/// of the `vtable` as the first parameter.
///
/// It is important to consider that the `data` pointer must point to a
/// thread safe type such as an `Arc`.
///
/// The `vtable` customizes the behavior of a `Waker`. For each operation
/// on the `Waker`, the associated function in the `vtable` will be called.
///
/// # Safety
///
/// The behavior of the returned `Waker` is undefined if the contract defined
/// in [`RawWakerVTable`]'s documentation is not upheld.
///
/// (Authors wishing to avoid unsafe code may implement the [`Wake`] trait instead, at the
/// cost of a required heap allocation.)
///
/// [`Wake`]: ../../alloc/task/trait.Wake.html
#[inline]
#[must_use]
#[stable(feature = "waker_getters", since = "CURRENT_RUSTC_VERSION")]
#[rustc_const_stable(feature = "waker_getters", since = "CURRENT_RUSTC_VERSION")]
pub const unsafe fn new(data: *const (), vtable: &'static RawWakerVTable) -> Self {
Waker { waker: RawWaker { data, vtable } }
}

/// Creates a new `Waker` from [`RawWaker`].
///
/// # Safety
Expand Down Expand Up @@ -770,6 +801,30 @@ impl LocalWaker {
a_data == b_data && ptr::eq(a_vtable, b_vtable)
}

/// Creates a new `LocalWaker` from the provided `data` pointer and `vtable`.
///
/// The `data` pointer can be used to store arbitrary data as required
/// by the executor. This could be e.g. a type-erased pointer to an `Arc`
/// that is associated with the task.
/// The value of this pointer will get passed to all functions that are part
/// of the `vtable` as the first parameter.
///
/// The `vtable` customizes the behavior of a `LocalWaker`. For each
/// operation on the `LocalWaker`, the associated function in the `vtable`
/// will be called.
///
/// # Safety
///
/// The behavior of the returned `Waker` is undefined if the contract defined
/// in [`RawWakerVTable`]'s documentation is not upheld.
///
#[inline]
#[must_use]
#[unstable(feature = "local_waker", issue = "118959")]
pub const unsafe fn new(data: *const (), vtable: &'static RawWakerVTable) -> Self {
LocalWaker { waker: RawWaker { data, vtable } }
}

/// Creates a new `LocalWaker` from [`RawWaker`].
///
/// The behavior of the returned `LocalWaker` is undefined if the contract defined
Expand Down

0 comments on commit 22bd319

Please sign in to comment.