Skip to content

Commit 22bd319

Browse files
committed
Add Waker::new and LocalWaker::new
Per the `waker_getters` FCP: rust-lang#96992 (comment) Docs largely copied from `RawWaker::new`.
1 parent 2dc7514 commit 22bd319

File tree

1 file changed

+55
-0
lines changed

1 file changed

+55
-0
lines changed

Diff for: library/core/src/task/wake.rs

+55
Original file line numberDiff line numberDiff line change
@@ -493,6 +493,37 @@ impl Waker {
493493
a_data == b_data && ptr::eq(a_vtable, b_vtable)
494494
}
495495

496+
/// Creates a new `Waker` from the provided `data` pointer and `vtable`.
497+
///
498+
/// The `data` pointer can be used to store arbitrary data as required
499+
/// by the executor. This could be e.g. a type-erased pointer to an `Arc`
500+
/// that is associated with the task.
501+
/// The value of this pointer will get passed to all functions that are part
502+
/// of the `vtable` as the first parameter.
503+
///
504+
/// It is important to consider that the `data` pointer must point to a
505+
/// thread safe type such as an `Arc`.
506+
///
507+
/// The `vtable` customizes the behavior of a `Waker`. For each operation
508+
/// on the `Waker`, the associated function in the `vtable` will be called.
509+
///
510+
/// # Safety
511+
///
512+
/// The behavior of the returned `Waker` is undefined if the contract defined
513+
/// in [`RawWakerVTable`]'s documentation is not upheld.
514+
///
515+
/// (Authors wishing to avoid unsafe code may implement the [`Wake`] trait instead, at the
516+
/// cost of a required heap allocation.)
517+
///
518+
/// [`Wake`]: ../../alloc/task/trait.Wake.html
519+
#[inline]
520+
#[must_use]
521+
#[stable(feature = "waker_getters", since = "CURRENT_RUSTC_VERSION")]
522+
#[rustc_const_stable(feature = "waker_getters", since = "CURRENT_RUSTC_VERSION")]
523+
pub const unsafe fn new(data: *const (), vtable: &'static RawWakerVTable) -> Self {
524+
Waker { waker: RawWaker { data, vtable } }
525+
}
526+
496527
/// Creates a new `Waker` from [`RawWaker`].
497528
///
498529
/// # Safety
@@ -770,6 +801,30 @@ impl LocalWaker {
770801
a_data == b_data && ptr::eq(a_vtable, b_vtable)
771802
}
772803

804+
/// Creates a new `LocalWaker` from the provided `data` pointer and `vtable`.
805+
///
806+
/// The `data` pointer can be used to store arbitrary data as required
807+
/// by the executor. This could be e.g. a type-erased pointer to an `Arc`
808+
/// that is associated with the task.
809+
/// The value of this pointer will get passed to all functions that are part
810+
/// of the `vtable` as the first parameter.
811+
///
812+
/// The `vtable` customizes the behavior of a `LocalWaker`. For each
813+
/// operation on the `LocalWaker`, the associated function in the `vtable`
814+
/// will be called.
815+
///
816+
/// # Safety
817+
///
818+
/// The behavior of the returned `Waker` is undefined if the contract defined
819+
/// in [`RawWakerVTable`]'s documentation is not upheld.
820+
///
821+
#[inline]
822+
#[must_use]
823+
#[unstable(feature = "local_waker", issue = "118959")]
824+
pub const unsafe fn new(data: *const (), vtable: &'static RawWakerVTable) -> Self {
825+
LocalWaker { waker: RawWaker { data, vtable } }
826+
}
827+
773828
/// Creates a new `LocalWaker` from [`RawWaker`].
774829
///
775830
/// The behavior of the returned `LocalWaker` is undefined if the contract defined

0 commit comments

Comments
 (0)