Enhance documentation on wake call memory ordering

[xmh0511]

View all comments

[rustbot]

r? @Mark-Simulacrum

rustbot has assigned @Mark-Simulacrum.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: libs
• libs expanded to 10 candidates
• Random selection from LawnGnome, Mark-Simulacrum, clarfonthey, jhpratt

[xmh0511]

@Darksonn

It's probably sufficient to say that "the call to wake() happens-before the beginning of the call to poll()".

the call to wake() sounds like the whole wake() synchronizes with the beginning of the call to poll(). I cited a similar wording in the C++ standard, which is worded in this way:

Synchronization: The completion of the thread represented by *this synchronizes with ([intro.multithread]) the corresponding successful join() return.

I agree that"wake() return" or "the call to wake()" is indistinguishable for establishing happens-before. All evaluations that do not occur within a function invocation are either sequenced-before/after these that occur within the function invocation.

[xmh0511]

@Darksonn After thinking more, I think your wording is reasonable. Consider this a valid implementation of wake(pseudo code)

fn wak(&self){
   do_something1(); // #1
   self.flag.swap(1,AcqRel); // #2
   do_something2(); // #3
}

In this implementation, #2 synchronizes with the RMW operation that is sequenced before the call to poll(). That is, only these evaluations that are sequenced before #2 happen before the poll(). So, strictly speaking, the call expression wake() sequences before #2, it's reasonable to say it happens before the beginning of the call to poll(); however, wake() return does not.

BTW, the expression wake() itself means call to wake, saying call to wake() is a bit strange.