macros: add "local" runtime flavor #7375

Twey · 2025-05-30T15:41:17Z

Motivation

We would like to be able to create a local runtime from the tokio::main attribute in order to be able to use spawn_local in functions that rely on tokio::main or tokio::test.

Solution

Add a local flavor to tokio::main which behaves like current-thread, but calls build_local(Default::default()) instead of build().

tests-integration/tests/macros_main.rs

Darksonn · 2025-06-03T08:44:23Z

Can you please make sure that CI passes? There's a rustfmt failure.

Twey · 2025-06-03T18:23:42Z

Thanks for taking the time to review @ADD-SP @Darksonn! I think I've addressed your comments. Would you mind taking another look?

Darksonn

Sorry about the delay in review.

Darksonn · 2025-06-18T21:01:30Z

tokio-macros/src/entry.rs

            }
-            (F::CurrentThread, None) => None,
+            (F::CurrentThread | F::Local, None) => None,
            (F::Threaded, worker_threads) if self.rt_multi_thread_available => {


Please add logic to rt_multi_thread_available to detect whether --cfg tokio_unstable is set and emit a hard error if it is not.

I'm not sure I understand this comment. Did you mean to add the logic to RuntimeFlavor::from_str?

The error should be similar to this error:

tokio/tokio-macros/src/entry.rs

Lines 193 to 197 in 2506c9f

let msg = if self.flavor.is_none() {

"The default runtime flavor is `multi_thread`, but the `rt-multi-thread` feature is disabled."

} else {

"The runtime flavor `multi_thread` requires the `rt-multi-thread` feature."

};

Maybe you meant a0ca77e; if I've misinterpreted please feel free to suggest changes :)

Sorry, I just saw your comment. Is 4363203 more what you had in mind?

I think both are okay.

This is harder than it appears because RUSTFLAGS is not passed to proc macros. I guess we have to emit a cfg check, so it actually can't live in either of these places.

44a31b1 seems to work in my local tests.

Doesn't that also trigger other unrelated errors when it fails?

What we do today is essentially define the main macro two times to pass different values to the rt_multi_thread boolean, and have lib.rs do this:

#[cfg(feature = "rt-multi-thread")] pub use tokio_macros::main; #[cfg(not(feature = "rt-multi-thread"))] pub use tokio_macros::main_rt as main;

This way, the macro knows based on the cfgs that apply in the main Tokio crate. We could use the same approach and have four macros.

The quadratic explosion is a little bit scary to me. We can avoid emitting additional code if checks fail like 213598d.

carllerche · 2025-06-18T22:44:09Z

This looks fine to me. I'm happy to merge this when @Darksonn is. Are there docs? My main concern is explaining to users the difference between flavor local and flavor current_thread and how to pick between them.

Twey · 2025-06-21T01:23:52Z

Is there a reason to use current_thread over local when it's available?

Darksonn · 2025-06-21T12:06:13Z

@Twey I'm pretty reluctant to change the default runtime. I do not want a repeat of #4142 where we had to revert something.

Twey · 2025-06-23T12:09:04Z

I'm happy enough to not change the default runtime — but I'm not really clear on what I should write in the documentation about when to choose current_thread over local.

Twey · 2025-06-23T12:58:01Z

I'm not certain I've done the right thing but I've done my best :) Please feel free to suggest further changes if I didn't understand something correctly.

Darksonn · 2025-06-24T12:36:02Z

tokio-macros/src/lib.rs

+///
+/// Equivalent code not using `#[tokio::main]`
+///
+/// ```ignore


Does this work?

Suggested change

/// ```ignore

/// ```

/// #![cfg(tokio_unstable)]

No, it will be executed. We could use text but then we lose Rust highlighting.

If we can execute it, then I think we should. Why can't we?

We can do b040de5.

We can't execute it because the LocalExecutor doesn't exist if we don't have tokio_unstable, which we don't usually have in tests. But maybe it's clearer this way anyway.

What if we add a cfg(tokio_unstable) to the test so it only actually runs under tokio_unstable? I believe we run tests both with and without the flag.

Right, that's b040de5 :)

…ble`

tokio-macros/src/lib.rs

jobafr · 2025-07-10T13:00:40Z

Hi, I found this PR because I was trying to figure out why spawn_local would not work when using the current-thread runtime from tokio::main. Maybe you could add something to the docs of spawn_local to indicate that this is going to work when using a main with #[tokio::main(flavor = "local")]?

Maybe something like

Spawns a !Send future on the current [LocalSet] or [LocalRuntime].

This is possible when either using one of these types explicitly, or by opting to use RuntimeFlavor::Local for the calling main function like so: #[tokio::main(flavor = "local")].

Twey · 2025-07-10T13:21:16Z

Maybe you could add something to the docs of spawn_local

In general it doesn't seem like we refer to the macros in the core API docs. I don't have anything against it myself, but I'll let the others weigh in on whether that's something we want to start doing. :)

Darksonn · 2025-07-10T13:23:29Z

Referring to the macros in core API docs is perfectly fine.

Twey · 2025-07-10T13:30:31Z

Okay! 8c3d838

I slightly reworded it @jobafr to avoid mention of the internal RuntimeFlavor::Local enum, and to be explicit (again) that it will only work with tokio_unstable. I hope that's okay.

mox692 · 2025-07-11T11:13:08Z

tokio-macros/src/entry.rs

+        #[allow(unreachable_code)]
+        {
+            panic!("fell through checks")
+        }


Is this code needed? (since this is after the return statement, I think it will never be executed.)

Or, does this work as a safeguard for future macro changes?

If the checks fail, the function body (which contains ill-formed code) won't be called. This trailer exists to provide a value of the function return type in the case that we aren't returning the real return value earlier so that we don't surface an unhelpful type mismatch error to the user.

c.f. #7375 (comment)

As far as I can tell, the addition of this panic is the cause of the worse error messages seen in tests-build/tests/fail/macros_type_mismatch.stderr. Having reasonably good error messages when used incorrectly is a goal of the macro.

Can you try annotating the fall-through case with #[cfg(not(tokio_unstable))] and see if that avoids the regression on the error messages.

Done in 9933509.

Darksonn

Thanks.

tokio-rs#7375 added the Local runtime flavour but forgot to update the error message when an unknown value is passed to from_str()

Darksonn added A-tokio-macros Area: The tokio-macros crate M-runtime Module: tokio/runtime labels May 31, 2025

Darksonn requested a review from carllerche May 31, 2025 11:39

ADD-SP reviewed Jun 2, 2025

View reviewed changes

tests-integration/tests/macros_main.rs Show resolved Hide resolved

Twey force-pushed the local-macro branch from f3998b9 to bc425d8 Compare June 3, 2025 17:03

Darksonn reviewed Jun 18, 2025

View reviewed changes

Twey force-pushed the local-macro branch from d41ff3f to d9f8b81 Compare June 23, 2025 13:05

Darksonn reviewed Jun 24, 2025

View reviewed changes

Twey force-pushed the local-macro branch 3 times, most recently from b1f3a19 to 44a31b1 Compare June 24, 2025 13:19

Twey added 9 commits June 24, 2025 15:10

macros: add "local" runtime flavor

6bd6650

tokio-macros: hard error if flavor = "local" and not `tokio_unsta…

dad546f

…ble`

tokio-macros: add docs for flavor = "local"

225f6d7

tokio-macros: don't run unstable usage examples

11f49dd

tokio-macros: use ignore instead of no_run

8bfcd4b

tokio-macros: put local validation logic with the rest

324222a

tokio-macros: use hidden cfg for local docs

0bdde71

tokio-macros: emit compile error on local without unstable

92e156f

tokio-macros: add dummy main to disabled doctest blocks

3a29832

Twey force-pushed the local-macro branch from 730b77a to 3a29832 Compare June 24, 2025 14:10

mox692 reviewed Jun 27, 2025

View reviewed changes

tokio-macros/src/lib.rs Show resolved Hide resolved

macros: don't emit additional warnings when checks fail

213598d

Twey added 2 commits July 7, 2025 22:10

fix permissions

0cc0f31

update compile errors for newer Rust

b58144e

Merge branch 'master' into local-macro

e1117ec

link flavor in spawn_local docs

8c3d838

Twey added 2 commits July 10, 2025 14:31

unbreak docs

0f436ec

rerun tests

67abbc8

mox692 reviewed Jul 11, 2025

View reviewed changes

Twey requested a review from Darksonn July 25, 2025 12:06

Twey added 2 commits July 28, 2025 12:33

only emit panic if checks fail

9933509

revert macros_type_mismatch.stderr

ac2ad0a

Darksonn approved these changes Jul 28, 2025

View reviewed changes

Darksonn merged commit 4b96af6 into tokio-rs:master Jul 28, 2025
86 checks passed

ADD-SP mentioned this pull request Sep 1, 2025

Tracking issue for LocalRuntime stabilization #7558

Open

13 tasks

martin-g added a commit to martin-g/tokio that referenced this pull request Sep 9, 2025

macros: Add local to the list of available runtime flavours

b46e7d4

tokio-rs#7375 added the Local runtime flavour but forgot to update the error message when an unknown value is passed to from_str()

martin-g mentioned this pull request Sep 9, 2025

macros: add missing local flavor to tokio::main error message #7597

Merged

martin-g added a commit to martin-g/tokio that referenced this pull request Sep 9, 2025

macros: Add local to the list of available runtime flavours

be782ca

tokio-rs#7375 added the Local runtime flavour but forgot to update the error message when an unknown value is passed to from_str()

ADD-SP mentioned this pull request Oct 11, 2025

task: add tests for spawn_local and spawn_local_on #7609

Merged

This was referenced Oct 14, 2025

chore: prepare tokio-macros v2.6.0 #7676

Merged

Prepare v1.48.0 #7677

Merged

	let msg = if self.flavor.is_none() {
	"The default runtime flavor is `multi_thread`, but the `rt-multi-thread` feature is disabled."
	} else {
	"The runtime flavor `multi_thread` requires the `rt-multi-thread` feature."
	};

Uh oh!

macros: add "local" runtime flavor #7375

macros: add "local" runtime flavor #7375

Conversation

Twey commented May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Solution

Uh oh!

Uh oh!

Darksonn commented Jun 3, 2025

Uh oh!

Twey commented Jun 3, 2025

Uh oh!

Darksonn left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Twey Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

carllerche commented Jun 18, 2025

Uh oh!

Twey commented Jun 21, 2025

Uh oh!

Darksonn commented Jun 21, 2025

Uh oh!

Twey commented Jun 23, 2025

Uh oh!

Twey commented Jun 23, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Twey Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jobafr commented Jul 10, 2025

Uh oh!

Twey commented Jul 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Darksonn commented Jul 10, 2025

Uh oh!

Twey commented Jul 10, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Twey Jul 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Twey commented May 30, 2025 •

edited

Loading

Twey Jul 7, 2025 •

edited

Loading

Twey Jun 24, 2025 •

edited

Loading

Twey commented Jul 10, 2025 •

edited

Loading

Twey Jul 18, 2025 •

edited

Loading