Tracking issue for `LocalRuntime` stabilization

[ADD-SP]

This is the central place to track all relevant works about stabilizing the LocalRuntime.

What is the LocalRuntime?

Currrntly, there are two types of stable runtime supported by tokio, Current Thread Runtime and Multi Thread Runtime, LocalRuntime is the thrid type of runtime, which allows downstream to spawn !Send Futures.

Why do we need the LocalRuntime?

The tokio::spawn and similar functions require the Future can be Send. However, it is reasonable to spawn a !Send Future in certain cases. While the Current Thread Runtime running all tasks in a single thread, spawning local async task is still not ergonomic and straightforward, and also has some issues (see below).

What did we try?

We introduced LocalSet in #1733, which allows downstream to spawn !Send Futures. However, there are some downsides.

• Tasks on the LocalSet can tokio::spawn to get onto the runtime, but once you're on the runtime, you can no longer spawn_local to get back into the LocalSet.
• From the runtime's perspective, all of the tasks in the LocalSet behave like a single task using FuturesUnordered, so various runtime options such as event_interval behave in > a very surprising way by counting many tasks at once.
• After discussions with Deno, the LocalSet has been shown to involve considerable performance overhead compared to unsafely spawning the !Send tasks onto a current-thread runtime.

---

• Issue Add on_spawn configuration for Builder #3181 proposes to add hooks that run when a task is spawned / destroyed. The hooks would not run for tasks on the LocalSet. This is confusing.
• Task dumps currently don't look inside block_on, which means that LocalSet tasks are completely invisible to task dumps.

Ref: #6739

So we need another solution.

Steps to stabilize the LocalRuntime

In high-level, there are several areas, and we need to distinguish between tasks that must be completed before stabilization and those that can be completed after stabilization.

Analyze the potential impacts on the existing usage.

The scope should at least includes existing usage of tokio, tokio-macros, tokio-stream, tokio-util, and tokio-test. We may need to deprecate the existing features.

• Proposal: Deprecate Tokio's LocalSet #6741
• RFC: Replace the internal implementation of LocalPoolHandle with LocalRuntime #7560
• More ... (please leave comment in this issue to rich this list)

Change the document and guideline

The scope includes the docs of tokio, tokio-macros, tokio-stream, tokio-util, tokio-test, and https://tokio.rs/tokio/tutorial.

• macros: add "local" runtime flavor #7375
• Guideline for choosing between Current Thread Runtime and Local Runtime #7559
• Clarify the behavior of several spawn_local methods #7561
• More ... (please leave comment in this issue to rich this list)

New features

The scope includes of tokio, tokio-macros, tokio-stream, tokio-util, and tokio-test.

• rt: add thread (un)parking hooks for LocalRuntime #7420
• Do we need a tokio::spawn_local as the shortcut of [tokio::task::spawn_local]? (needs a dedicated issue)
• More ... (please leave comment in this issue to rich this list)

Others

• tokio: Stabilize LocalRuntime #7557 (removes the cfg(tokio_unstable) gate)
• Improve the test coverage of task containers on LocalRuntime #7562
• More ... (please leave comment in this issue to rich this list)

FAQs

Shall we deprecate the Current Thread Runtime?

No, we shouldn't, because it has valid use cases. See https://tokio.rs/tokio/topics/bridging and #7559 .

[Daksh14]

Do we need a tokio::spawn_local as the shortcut of [tokio::task::spawn_local]? (needs a dedicated issue)

I don't think we should do this because the spawn local implementation if called inside a multithreaded runtime will panic or just not do anything with the task. I believe if we call tokio::spawn inside a LocalRuntime then that should behave as if tokio::task::spawn_local is called.

#[tokio::main(flavor = "local")]
async fn main() {
  let timer = ...;

  tokio::spawn(async {
      x.await;
   });
}

[taikulawo]

@Daksh14 But tokio::spawn requires Future to be Send while tokio::task::spawn_local not

[taikulawo]

New features we could have.

tokio-macros

#[tokio::test(flavor = "local"]
#[tokio::main(flavor = "local"]