Document that `RawWakerVTable` functions must be thread-safe.

[kpreid]

Also add some intra-doc links and more high-level explanation of how Waker is used, while I'm here.

Context: https://internals.rust-lang.org/t/thread-safety-of-rawwakervtables/17126

[rust-highfive]

r? @scottmcm

(rust-highfive has picked a reviewer for you, use r? to override)

[rustbot]

Hey! It looks like you've submitted a new PR for the library teams!

If this PR contains changes to any rust-lang/rust public library APIs then please comment with @rustbot label +T-libs-api -T-libs to tag it appropriately. If this PR contains changes to any unstable APIs please edit the PR description to add a link to the relevant API Change Proposal or create one if you haven't already. If you're unsure where your change falls no worries, just leave it as is and the reviewer will take a look and make a decision to forward on if necessary.

Examples of T-libs-api changes:

• Stabilizing library features
• Introducing insta-stable changes such as new implementations of existing stable traits on existing stable types
• Introducing new or changing existing unstable library APIs (excluding permanently unstable features / features without a tracking issue)
• Changing public documentation in ways that create new stability guarantees
• Changing observable runtime behavior of library APIs

[scottmcm]

I don't know enough about tasks/futures to be a good reviewer here.

r? libs

[thomcc]

r? @thomcc

[thomcc]

Hmm, can someone on @rust-lang/wg-async double-check this?

[thomcc]

After a reread through our APIs and docs I'm convinced this is fine and doesn't make any new guarantees.

@bors r+ rollup

[bors]

:pushpin: Commit d4bcc4ae6dcd6c01f05edf1888d4696e61a40288 has been approved by thomcc

It is now in the queue for this repository.

[tmandry]

Thanks for the ping and for the PR, I agree it looks good!