Documentation is inconsistent about Runtime shutdown behaviour

[jbg]

Version
1.13.0 (also Git master)

Platform
n/a

Description
The module-level documentation for tokio::runtime says:

Once Runtime is dropped, all runtime threads are forcibly shutdown. Any tasks that have not yet completed will be dropped.

However, the documentation for tokio::runtime::Runtime::shutdown_timeout says:

[...] dropping a Runtime will wait indefinitely for all tasks to terminate, [...]

This has lead to confusion over the expected behaviour when a Runtime is dropped.

The module-level documentation appears to be accurate; dropping Runtime will not wait for any tasks to terminate.

[Darksonn]

Well, it's more complicated. The runtime will immediately attempt to kill all tasks, but it may not be able to do so immediately for some of the tasks - a task that is currently running cannot be killed until the next time it yields (reaches an .await), and spawn_blocking tasks cannot be killed whatsoever. The runtime will kill all tasks as fast as it can, but if there are tasks that it can't kill, it will wait indefinitely for them to either finish or become killable.