Expand a bit on thread::park spurious wakeups

[steveklabnik]

Fixes #26475

I'm not sure this is enough, really, but I'm not totally clear on what specific information would be valuable here. In the original issue, the Java page was pretty decent, but now I can't think of a different way to word it, and copying their prose is of course not acceptable.

thoughts @alexcrichton @aturon @aidanhs ?

[rust-highfive]

r? @aturon

(rust_highfive has picked a reviewer for you, use r? to override)

[alexcrichton]

I feel like this doesn't quite reflect the discussion in #26475, but after re-reading the module documentation I'm not actually sure what clarification is needed. @aidanhs could you weigh in with what you'd like to see?

[aidanhs]

The thing missing for me was an explanation of what this library feature brings to the table - the rest of the page talks about things impossible to achieve without library support, whereas this is effectively an optimisation of a busy-wait loop (I can't think of any other uses off-hand).

Some tweaked docs:

Every thread is equipped with some basic low-level blocking support, via the park and unpark functions. These can be used as a more CPU-efficient implementation of a spinlock.

and

The API is typically used by acquiring a handle to the current thread, placing that handle in a shared data structure so that other threads can find it, and then parking (in a loop with a check for the token actually being acquired).

[steveklabnik]

I incorporated your suggestions, @aidanhs . Improving the module documentation makes sense too, but I'll take care of that when i run through all of std::thread together, I'm just finishing up std::io.

[alexcrichton]

@bors: r+ cbdc52e

[bors]

⌛ Testing commit cbdc52e with merge 21dfd24...

[bors]

☀️ Test successful - auto-linux-32-nopt-t, auto-linux-32-opt, auto-linux-64-nopt-t, auto-linux-64-opt, auto-linux-64-x-android-t, auto-mac-32-opt, auto-mac-64-nopt-t, auto-mac-64-opt, auto-win-gnu-32-nopt-t, auto-win-gnu-32-opt, auto-win-gnu-64-nopt-t, auto-win-gnu-64-opt