add track_caller to public APIs (#4413)

[hds]

Motivation

When a user of tokio calls a function that panics when misused (e.g. calling
Handle::current() outside of a runtime), then the user currently sees the line
number of the panic call inside tokio. It would be more informative for the user
to see the place where they called the panicking function.

It is still possible for the user to see the full stack trace by setting the
environment variable RUST_BACKLOG=1, so no useful information is
hidden.

Hopefully this change fixes is the first step to closing #4413 (here it is done
for the main tokio crate, it still needs to be done for other crates).

Note that there was an earlier PR (#4445) to work on this issue for the tokio-util
crate, but it hasn't seen much work recently and after looking into it, I found that
these change in the main crate are necessary prerequisites.

Solution

Functions that may panic can be annotated with #[track_caller] so that
in the event of a panic, the function where the user called the
panicking function is shown instead of the file and line within Tokio
source.

This change adds track caller to all the non-unstable public APIs in
Tokio core where the documentation describes how the function may panic
due to incorrect context or inputs. Since each internal function needs
to be annotated down to the actual panic, it makes sense to start in
Tokio core functionality.

Tests are needed to ensure that all the annotations remain in place in
case internal refactoring occurs.

The test installs a panic hook to extract the file location from the
PanicInfo struct and clone it up to the outer scope to check that the
panic was indeed reported from within the test file. The downside to
this approach is that the panic hook is global while set and so we need
a lot of extra functionality to effectively serialize the tests so that
only a single panic can occur at a time. This requires adding the
lazy_static crate as a dev dependency.

The annotation of block_on was removed as it did not work. It appears
to be impossible to correctly chain track caller when the call stack to
the panic passes through clojures, as the track caller annotation can
only be applied to functions. Also, the panic message itself is very
descriptive.

[Darksonn]

Wait, does this function have two sections describing its panics?

[hds]

Funny you should ask... the first Panic section (as far as I can tell) isn't actually true. Calling worker_threads for a current_thread runtime doesn't panic, at least not immediately and not after scheduling a task on the runtime either.

I was going to submit an issue for this to get some guidance on the preferred behaviour (fix docs or fix code).

[hds]

Created issue for it not panicking in the way described by the first Panic section: #4773

[Darksonn]

Use futures::future::pending() instead of a timer where the test fails if the timer elapses.

[hds]

I think the timer isn't needed at all. abort() is called on the handle before being awaited. So I've removed it entirely.

[Darksonn]

Awaiting a handle doesn't affect whether the task starts running or not.

[hds]

Understood, fixed now. Thanks!

[Darksonn]

We already have the dependencies to do this. There's no reason to add lazy_static.

Suggested change

	lazy_static! {
	static ref SET_UP_PANIC_HOOK: Once = Once::new();
	static ref PANIC_MUTEX: Arc<Mutex<()>> = Arc::new(Mutex::new(()));
	static ref PANIC_FILE: Mutex<String> = Mutex::new(String::new());
	}
	use parking_lot::{const_mutex, Mutex};
	static SET_UP_PANIC_HOOK: Once = Once::new();
	static PANIC_MUTEX: Mutex<()> = const_mutex(());
	static PANIC_FILE: Mutex<String> = const_mutex(String::new());

[hds]

Thank you! I was hoping to get a comment like this.

[Darksonn]

Looks good to me. Thanks!