thread::scope: document how join interacts with TLS destructors

[RalfJung]

Fixes #116237 by documenting the current behavior regarding thread-local destructors as intended. (I'm not stoked about this, but documenting it is better than leaving it unclear.)

This also adds documentation for explicit join calls (both for scoped and regular threads), saying that those will wait for TLS destructors. That reflects my understanding of the current implementation, which calls join on the native thread handle. Are we okay with guaranteeing that? I think we should, so people have at least some chance of implementing "wait for all destructors" manually. This fixes #127571.

Cc @rust-lang/libs-api

[rustbot]

r? @ChrisDenton

rustbot has assigned @ChrisDenton.
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

[joboet]

As far as I know, this truly matches current behaviour. I really like that this is phrased in a way that still leaves the possibility of fixing this in the future.

View changes since this review

[ChrisDenton]

This looks correct to me based on the current implementation and previous discussion. But it does probably warrant a libs-api sign-off so I'll nominate it.

It is not great that implicit joins can't currently offer the same guarantees as explicit ones so we do want to keep the door open to future improvements. On the flip side, this does close off the possibility of providing weaker guarantees for explicit joins in the future but I'd consider that a very good thing. I'd always want some way to wait until a thread is fully finished running.

[Amanieu]

@rfcbot merge libs-api

[rust-rfcbot]

Team member @Amanieu has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @the8472

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[ChrisDenton]

Just to be clear the libs-api FCP is specifically for guaranteeing that an explicit join will always fully wait for the thread to finish (including TLS destructors and whatever else).