Skip to content

Commit db5f882

Browse files
Matthias247boats
authored andcommitted
Add additional clarification around RawWaker
1 parent e025c59 commit db5f882

File tree

1 file changed

+8
-3
lines changed

1 file changed

+8
-3
lines changed

text/0000-futures.md

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -242,9 +242,13 @@ pub struct RawWaker {
242242
pub struct RawWakerVTable {
243243
/// This function will be called when the `RawWaker` gets cloned, e.g. when
244244
/// the `Waker` or `LocalWaker` in which the `RawWaker` is stored gets cloned.
245+
///
245246
/// The implementation of this function must retain all resources that are
246247
/// required for this additional instance of a `RawWaker` and associated
247-
/// task.
248+
/// task. The implementation must return a valid `RawWaker` that behaves
249+
/// equivalent to the `RawWaker` that got cloned. E.g. cloning a `RawWaker`
250+
/// that implemented a thread-safe wakeup for use in `Waker` must return
251+
/// a `RawWaker` that implements the same wakeup behavior.
248252
pub clone: unsafe fn(*const ()) -> RawWaker,
249253
/// This function will be called when a `LocalWaker` should be converted into
250254
/// a thread-safe `Waker`. The implementation of this function must return
@@ -266,6 +270,7 @@ pub struct RawWakerVTable {
266270
/// This function will be called when `wake` is called on the `RawWaker`.
267271
pub wake: unsafe fn(*const ()),
268272
/// This function gets called when a `RawWaker` gets dropped.
273+
///
269274
/// The implementation of this function must make sure to release any
270275
/// resources that are associated with this instance of a `RawWaker` and
271276
/// associated task.
@@ -421,8 +426,8 @@ impl LocalWaker {
421426
- `Waker::wake()` must wake up an executor even if it is called from an arbitrary
422427
thread.
423428

424-
An executor which implements `RawWaker` must therefore make sure that all these
425-
requirements are fulfilled.
429+
An executor that instantiates a `RawWaker` must therefore make sure that all
430+
these requirements are fulfilled.
426431

427432
Since many of the ownership semantics that are required here can easily be met
428433
through a reference-counted `Waker` implementation, a convienence method for

0 commit comments

Comments
 (0)