Clarify the behavior of several `spawn_local` methods

[ADD-SP]

This issue is tracked by #7558, and it MUST be done before stabilizing the LocalRuntime.

What are the spawn_local methods?

tokio::task::spawn_local is used for spawn a !Send Future on the LocalSet or LocalRuntime, and there are several methods call tokio::task::spawn_local internally.

• JoinSet::spawn_local
• JoinSet::spawn_local_on
• JoinMap::spawn_local
• JoinMap::spawn_local_on
• TaskTracker::spawn_local
• TaskTracker::spawn_local_on

What should we do?

We need to update the docs to clarify the behavior when the methods above are called on the LocalRuntime.

What is the behavior on the LocalRuntime?

Invoking these methods on the LocalRuntime doesn't panic.

What else do we need to do?

It would be better specifically reminding the authors of library crates to use these methods with caution, as calling them in their libraries may lead to their downstream panics, especially if their downstream uses a multi-threaded runtime.

[Darksonn]

I believe we already made these methods work with LocalRuntime when we added it. But it's of course good to check if tests are missing.

[mattiapitossi]

Hi @ADD-SP, I'd like to work on this issue if possible. I'll also check if there are any missing tests as suggested by Darksonn

[ADD-SP]

@mattiapitossi, this issue is primarily for documentation improvements, feel free to work on it.

For tests, #7609 is already working on it. Additional tests is welcome, but please make sure we don't duplicate the works of #7609 .

[mattiapitossi]

Hi @ADD-SP, I've opened a first PR for this issue. However, it seems like the spawn_local_on methods are actually calling LocalSet's spawn_local method internally instead of tokio::task::spawn_local. And unless I'm missing something, I couldn't find any proof or reference that this method panics outside LocalRuntime like I did with the task's spawn_local. Could you please help me understand if my reasoning is correct? Thanks!

[ADD-SP]

The spawn_local_on doesn't panic outside of the LocalRuntime.