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

                let msg = format!(
                    "The `worker_threads` option requires the `multi_thread` runtime flavor. Use `#[{}(flavor = \"multi_thread\")]`",
                    self.macro_name(),
                );
                return Err(syn::Error::new(worker_threads_span, msg));
            }
-            (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.

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`

mox692 · 2025-06-27T13:08:11Z

tokio-macros/src/lib.rs

The permission of this file is updated too.

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 Outdated 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

Copy link

Member

mox692 Jun 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The permission of this file is updated too.

	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

Are you sure you want to change the base?

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!

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Twey commented May 30, 2025 •

edited

Loading

Twey Jun 24, 2025 •

edited

Loading