Fix inaccurate documentation of wait_while and wait_timeout_while

[Jupeyy]

fixes #121388

Sometimes code is more clear than documentation, cppreference is doing that:

quote start

Equivalent to

while (!stop_waiting())
{
    wait(lock);
}

(https://en.cppreference.com/w/cpp/thread/condition_variable/wait)

quote end

But the current documentation can be interpreted incorrectly. For example if you wait for a condition that is already false, the current documentation suggests that the current thread will still block.

[rustbot]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @Mark-Simulacrum (or someone else) some time within the next two weeks.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

• @rustbot author: the review is finished, PR author should check the comments and take action accordingly
• @rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

[Mark-Simulacrum]

I feel like the old phrasing was clearer. It's technically true that we evaluate the condition before blocking, but the right mental model for a condition variable is that it blocks until the condition is false.

The new wording also suggests to me that we are continuously evaluating the condition while waiting for a notification, which isn't accurate: the condition is only evaluated in response to notifications (or spurious wakeups).

[Jupeyy]

but the right mental model for a condition variable is that it blocks until the condition is false.

That would be really bad.

Imagine i have aVec of events. every time i push events i also signal the condition variable.

Now at cleanup I might want to check if all events were handled, else wait.

cond_var.wait_while(&mut g, |g| !g.events.is_empty());

but if in this case events is empty, a blocking would lead to infinite waiting.

The new wording also suggests to me that we are continuously evaluating the condition while waiting for a notification

I'd glady take better suggestions :D
I simply tried to make while condition is true, thread will block until notification sound a bit more english.

[Mark-Simulacrum]

I'd be happy to see the same code block as in the implementation (perhaps a bit simplified if needed) put into the documentation to help further clarify exactly what the function does if the current docs aren't clear enough.