Improve documentation on thread::park returning spuriously

[aidanhs]

I'm aware that currently there is no way a thread can return from park spuriously, but this is an implementation detail - when/if the new implementation happens it will break anything trying to use park because there was previously no way to use it correctly.

(it may be that I've just missed how to do this, in which case I'd consider it a documentation bug and can make a PR)

[alexcrichton]

I believe that this is an intentional aspect of the thread::park API, so I believe the docs may just want to be clearer that spurious wakeups can happen and consumers must be prepared for that eventuality.

@aturon would know for certain, though.

[steveklabnik]

Marking with libs until we know for sure.

[aturon]

Yes, it is intended to allow spurious wakeups in the future, with no way to detect them -- part of the point of this API is to impose the narrowest possible requirements on the underlying system (so as to use Futexes, etc, eventually).

[aturon]

(See the park method in http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/locks/LockSupport.html, which is the inspiration.)

[aidanhs]

That's a good page.

The park method may also return at any other time, for "no reason", so in general must be invoked within a loop that rechecks conditions upon return. In this sense park serves as an optimization of a "busy wait" that does not waste as much time spinning, but must be paired with an unpark to be effective.

The second sentence in particular gives some clarity.