Document that destructors in running threads are not run on program exit

[jwodder]

It's my understanding that, when a Rust program's main thread terminates and thereby causes any still-running threads to be shut down, destructors are not run for the shut-down threads; however, the documentation doesn't seem to come out and say that explicitly anywhere. This PR therefore adds an explicit statement about this to the std::thread docs.

If I am mistaken and destructors are run, that's worth documenting explicitly, too.

[rustbot]

r? @Mark-Simulacrum

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

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: @ChrisDenton, libs
• @ChrisDenton, libs expanded to 8 candidates

[clarfonthey]

r? lang

Since this feels like more a lang decision than a libs decision. I also believe this is the case currently, but don't know if we have any other documentation that's relevant here, and whether this is desired as a guarantee.

[traviscross]

We talked about this in the lang call. We wanted to change the text to say "may", as @joshtriplett has now left a review comment about. After that's updated, one of us will r+ it.

[jwodder]

@traviscross I've applied Josh's suggested wording change.

[traviscross]

Please squash.

[jwodder]

@traviscross Squashed.

[traviscross]

@bors r+ rollup

[rust-bors]

📌 Commit 8410d26 has been approved by traviscross

It is now in the queue for this repository.

[traviscross]

Thanks @jwodder.

[steffahn]

Actually, this behavior is already documented elsewhere (mentioning this not as an argument against documenting it here, too, but to ensure consistency):

In the documentation of std::process::exit:

Note that because this function never returns, and that it terminates the process, no destructors on the current stack or any other thread’s stack will be run.

and later

Note that returning from main also calls exit, […]

and one more time even further below

Note that returning from main is equivalent to calling exit

[jwodder]

Actually, this behavior is already documented elsewhere (mentioning this not as an argument against documenting it here, too, but to ensure consistency):

In the documentation of std::process::exit:

Note that because this function never returns, and that it terminates the process, no destructors on the current stack or any other thread’s stack will be run.

and later

Note that returning from main also calls exit, […]

and one more time even further below

Note that returning from main is equivalent to calling exit

That last line is a bit too buried for my liking, and the "returning from main also calls exit" bit doesn't preclude the existence of other code being run between the return and the exit().

[steffahn]

I wonder if it would be sufficient to instead just turn "shuts down" into a link to make the connection clear? This would also avoid the need for duplicate documentation of this detail.

(Idea for revised version:)
When the main thread of a Rust program terminates, the entire program shuts down, even if other threads are still running. However, this module provides convenient facilities for automatically waiting for the termination of a thread (i.e., join).

---

Additionally on that page, I see

If a clean shutdown is needed it is recommended to only call this function at a known point where there are no more destructors left to run; or, preferably, simply return […] from the main function and avoid this function altogether[…]

But the “preferable” way described there doesn’t actually ensure “no more destructors left to run” for you, in case there are other threads not being waited on; so maybe the std::process::exit page could benefit from a mention of threads…

(Idea for revised version:)
If a clean shutdown is needed it is recommended to only call this function at a known point where there are no more destructors left to run; or, preferably, simply return […] from the main function, ensure main doesn't forget, wait for any other threads you have spawned, and avoid this function altogether

---

That last line is a bit too buried for my liking

highlighting the “equivalent” phrasing too early could lead to misconceptions that they’re also equivalent for the purpose of handling local variables inside of main.

The ambiguity that could cause this comes from the fact that “returning from main” may be understood as “the thing that happens after main has finished and has ran all local destructors” or “all effects of “evaluating” a return expression in main” (which one could intuit does include the dropping of local variables).