7924: rt: introduce runtime name

[martin-augment]

7924: To review by AI

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3ad01fb and ce6a4cd.

📒 Files selected for processing (12)

• tests-build/tests/fail/macros_invalid_input.rs
• tests-build/tests/fail/macros_invalid_input.stderr
• tokio-macros/Cargo.toml
• tokio-macros/src/entry.rs
• tokio-macros/src/lib.rs
• tokio/src/runtime/builder.rs
• tokio/src/runtime/handle.rs
• tokio/src/runtime/scheduler/current_thread/mod.rs
• tokio/src/runtime/scheduler/multi_thread/handle.rs
• tokio/src/runtime/scheduler/multi_thread/mod.rs
• tokio/src/runtime/scheduler/multi_thread/worker.rs
• tokio/tests/rt_threaded.rs

---

Walkthrough

This pull request introduces runtime naming functionality to Tokio. The changes add a new optional name attribute to the #[tokio::main] and #[tokio::test] macros, enabling users to assign names to their Tokio runtimes. A corresponding Builder::name() method is added to set runtime names programmatically. The Handle::name() method allows retrieving a runtime's assigned name. The name field is propagated through both current-thread and multi-thread scheduler implementations. Documentation examples demonstrate the new feature, and tests validate that distinct runtime names are properly stored and retrieved.

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch pr-7924-2026-03-03-08-08-24

Tip

Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).
Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new feature allowing users to assign a custom name to their Tokio runtimes. This enhancement provides better identification and debugging capabilities for applications utilizing multiple runtimes or for clearer logging. The changes span across the core runtime builder, its handles, and the macro attributes, ensuring a consistent and user-friendly experience for setting and retrieving runtime names.

Highlights

• Runtime Naming: Introduced the ability to assign a custom name to a Tokio runtime using the name attribute in #[tokio::main] and #[tokio::test] macros, or via the tokio::runtime::Builder::name() method.
• API Extension: Added a new name() method to tokio::runtime::Handle to allow retrieval of the runtime's assigned name.
• Macro Support: Updated tokio-macros to parse and propagate the name attribute for both main and test entry points, ensuring proper configuration of the runtime builder.
• Error Handling & Validation: Enhanced macro error messages to include name as a recognized attribute and added validation to ensure the name attribute receives a string literal.
• Documentation & Examples: Provided comprehensive documentation and code examples illustrating how to use the new runtime naming feature with both attribute macros and the Builder API.

Changelog

• tests-build/tests/fail/macros_invalid_input.rs
  • Added a new test case test_name_not_string to verify that providing a non-string value to the name attribute in #[tokio::test] results in a compilation error.
• tests-build/tests/fail/macros_invalid_input.stderr
  • Updated expected error messages to include name as a valid attribute for tokio::main and tokio::test macros.
  • Added an expected error message for when the name attribute's value cannot be parsed as a string.
• tokio-macros/Cargo.toml
  • Updated the tokio dev-dependency to reference a local path, likely for development and testing purposes within the monorepo.
• tokio-macros/src/entry.rs
  • Added a name: Option<String> field to FinalConfig and Configuration structs to store the runtime name.
  • Initialized the name field to None in DEFAULT_ERROR_CONFIG and Configuration::new.
  • Implemented a set_name method in Configuration to handle parsing and setting the runtime name from a syn::Lit.
  • Integrated the name attribute into the build_config function, allowing it to be parsed from macro arguments.
  • Updated error messages for unknown attributes to include name as a recognized option.
  • Modified parse_knobs to apply the configured runtime name using rt.name(#v) if present.
• tokio-macros/src/lib.rs
  • Added new documentation sections and examples for setting the runtime name using #[tokio::main(name = "...")] and #[tokio::test(name = "...")] attributes.
• tokio/src/runtime/builder.rs
  • Added a name: Option<String> field to the Builder struct to store the runtime's name.
  • Initialized the name field to None in Builder::new and Builder::new_current_thread.
  • Introduced a public name(&mut self, val: impl Into<String>) -> &mut Self method to allow users to set the runtime's name.
  • Passed the self.name.clone() to the CurrentThread and MultiThread scheduler creation functions during the build process.
• tokio/src/runtime/handle.rs
  • Added a public name(&self) -> Option<&str> method to Handle to retrieve the runtime's name, delegating to the internal scheduler handle.
• tokio/src/runtime/scheduler/current_thread/mod.rs
  • Added a pub(crate) name: Option<String> field to the Handle struct.
  • Modified the CurrentThread::new function to accept a name: Option<String> parameter and store it in the Handle.
  • Implemented a pub(crate) name(&self) -> Option<&str> getter method for the Handle.
• tokio/src/runtime/scheduler/multi_thread/handle.rs
  • Added a pub(crate) name: Option<String> field to the Handle struct.
  • Implemented a pub(crate) name(&self) -> Option<&str> getter method for the Handle.
• tokio/src/runtime/scheduler/multi_thread/mod.rs
  • Modified the MultiThread::new function to accept a name: Option<String> parameter and pass it to the worker::create function.
  • Added #[allow(clippy::too_many_arguments)] to MultiThread::new due to the added parameter.
• tokio/src/runtime/scheduler/multi_thread/worker.rs
  • Modified the create function to accept a name: Option<String> parameter and store it in the Handle.
  • Added #[allow(clippy::too_many_arguments)] to create due to the added parameter.
• tokio/tests/rt_threaded.rs
  • Added a new test different_runtime_names to verify that two multi-threaded runtimes created with distinct names indeed report different names.

Activity

• The pull request was created with a description indicating it is for AI review, suggesting it is a new submission without prior human review activity.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a name attribute for Tokio runtimes, which can be set via the Builder or the #[tokio::main] and #[tokio::test] macros. The name can then be retrieved using a new name() method on runtime::Handle. The implementation is consistent and well-tested, with updates to documentation and the addition of both unit and integration tests.

My main feedback is a suggestion to refactor a couple of internal functions that now have a large number of arguments. Using a configuration struct could improve maintainability.

[augmentcode]

🤖 Augment PR Summary

Summary: Adds a configurable "runtime name" across Tokio’s runtime builder, scheduler handles, and proc-macro entrypoints.

Changes:

• Introduce name: Option<String> on tokio::runtime::Builder and a new Builder::name(...) setter.
• Propagate the name into current-thread and multi-thread scheduler handles and expose it via tokio::runtime::Handle::name().
• Extend #[tokio::main] and #[tokio::test] with a name = "..." attribute knob, including validation and updated diagnostics.
• Update tokio-macros dev-dependency to use the workspace tokio crate for tests.
• Add tests for differing runtime names and a compile-fail case for non-string name values.

Technical Notes: The name is stored on scheduler handles and returned as Option<&str>, keeping it cheap to query without extra allocation.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. 2 suggestions posted.

Comment augment review to trigger a new review at any time.

[augmentcode]

Builder now has a name configuration, but impl fmt::Debug for Builder doesn’t include it, which can make debug output misleading when diagnosing runtime configuration. Consider including the name field in the debug struct output as well.

Severity: low

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

[martin-augment]

value:good-to-have; category:bug; feedback: The Augment AI reviewer is correct! There is a custom implementation of std::fmt::Debug trait and the new name field is not added to it. Prevents missing to print the name of the runtime in its Debug implementation.

[augmentcode]

This test currently only asserts that the two runtime names differ; it would miss bugs where the runtime name is set but doesn’t reflect the provided value. Consider also asserting that each handle().name() matches the corresponding input string.

Severity: low

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

[martin-augment]

value:good-to-have; category:bug; feedback: The Augment AI reviewer is correct! The test makes sure that the two different runtimes have their own names which are not shared. It would be good to assert the names of each runtime too.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[cursor]

Redundant path dependency accidentally committed

Low Severity

The workspace root Cargo.toml already has [patch.crates-io] tokio = { path = "tokio" }, which automatically redirects all workspace members' tokio dependency to the local path. Adding an explicit path = "../tokio" to tokio-macros's [dev-dependencies] is therefore redundant. Notably, the tokio-macros/Cargo.toml header comment itself says "Remove path dependencies (if any)" before releasing, suggesting this was a local debugging artifact that wasn't cleaned up.

 

[martin-augment]

value:annoying; category:bug; feedback: The Bugbot AI reviewer is not correct! The patch is used by most of the CI checks but some of them remove it to test a "pre-release". The "path" setting is needed for those pre-release checks.

[claude]

test comment - please ignore

[claude]

PR Review posted successfully - ignore this comment

[claude]

Contributing to Tokio

Thanks for your help improving Tokio! We are so happy to have you!

There are opportunities to contribute to Tokio at any level. It doesn't matter if
you are just getting started with Rust or are the most weathered expert, we can
use your help.

No contribution is too small and all contributions are valued.

See the contributing guidelines to get started.

Code of Conduct

The Tokio project adheres to the Rust Code of Conduct. This describes
the minimum behavior expected from all contributors. Instances of violations of the
Code of Conduct can be reported by contacting the project team at
moderation@tokio.rs.

Need Help?

Reach out to us on the Discord server for any concern not covered in this guide.

LTS guarantees

In Tokio ≥1.0.0, each LTS release comes with the guarantee of at least one year of
backported fixes.

The goal of these guarantees is to provide stability to the ecosystem.

Minimum Supported Rust Version (MSRV)

• All Tokio ≥1.0.0 releases will support at least a 6-month old Rust
  compiler release.
• The MSRV will only be increased on 1.x releases.

Versioning Policy

With Tokio ≥1.0.0:

• Patch (1._.x) releases should only contain bug fixes or documentation
  changes. Besides this, these releases should not substantially change
  runtime behavior.
• Minor (1.x) releases may contain new functionality, MSRV increases (see
  above), minor dependency updates, deprecations, and larger internal
  implementation changes.

This is as defined by Semantic Versioning 2.0.

[claude]

[workspace]
resolver = "2"
members = [
"tokio",
"tokio-macros",
"tokio-test",
"tokio-stream",
"tokio-util",

Internal

"benches",
"examples",
"stress-test",
"tests-build",
"tests-integration",
]

[patch.crates-io]
tokio = { path = "tokio" }

[workspace.metadata.spellcheck]
config = "spellcheck.toml"

[workspace.lints.rust]
unexpected_cfgs = { level = "warn", check-cfg = [
'cfg(fuzzing)',
'cfg(loom)',
'cfg(mio_unsupported_force_poll_poll)',
'cfg(tokio_allow_from_blocking_fd)',
'cfg(tokio_internal_mt_counters)',
'cfg(tokio_no_parking_lot)',
'cfg(tokio_no_tuning_tests)',
'cfg(tokio_unstable)',
'cfg(target_os, values("cygwin"))',
] }

[claude]

PR Review: rt: introduce runtime name

This PR adds a name field to the Builder API and exposes it via Handle::name(), as well as a name attribute for both #[tokio::main] and #[tokio::test] macros. The feature is clean and well-scoped. Below are observations across several dimensions.

---

Code Quality and Design

1. name should live in Config, not as a standalone parameter

The most notable design issue is that name is threaded as a standalone Option<String> parameter through several function signatures: CurrentThread::new(), MultiThread::new(), and worker::create(). This is why #[allow(clippy::too_many_arguments)] was needed in two places.

A better approach would be to include name in the existing Config struct that is already passed around. That struct is purpose-built for this kind of metadata and would keep function signatures stable as future fields are added.

2. name field visibility is broader than necessary

In both current_thread::Handle and multi_thread::Handle, the field is declared pub(crate), but it is only accessed through the name() accessor method. It could be private or pub(super) since no other module accesses the field directly.

3. No use of the name beyond storage

The runtime name is stored and retrievable, but not surfaced anywhere else: not in fmt::Debug output for handles, and not as a prefix/suffix to worker thread names. Neither is a blocker, but a doc note setting expectations about future integration plans would help users understand the current scope.

---

Tests

4. The new test does not verify the actual stored name

The test different_runtime_names asserts that two differently-named runtimes have different names -- trivially true regardless of the implementation. More meaningful assertions would be direct equality checks on the stored values.

5. Missing test for the current_thread flavor

All new test coverage is in rt_threaded.rs (multi-thread only). There is no equivalent test for the current-thread scheduler.

6. No test that an unnamed runtime returns None

There is no test verifying the default None behavior when .name() is not called on the builder.

7. No end-to-end test for the macro-level name attribute

The compile-fail test for name = 123 is a good addition, but there is no runtime test verifying that name = "my-name" correctly propagates the name to Handle::current().name().

---

Documentation

8. Handle::name() doc example uses .unwrap() without explanation

Since name() returns Option<&str>, calling .unwrap() will panic for unnamed runtimes. The example should use .unwrap_or("(unnamed)") or include a note about when None is returned.

---

Input Validation

9. No validation for empty string names

Builder::name("") is currently accepted silently. An empty string name is arguably meaningless. Consider debug_assert!(!val.is_empty()) or at minimum document that empty strings are permitted.

---

Cargo.toml

10. path = "../tokio" in dev-dependencies must be removed before publishing

Path dependencies are not permitted in published crates. The tokio-macros/Cargo.toml change will need to be reverted before release, with the version pin bumped to the version that introduces Builder::name().

---

Summary

Category	Severity	Finding
Design	Medium	name should be in Config to avoid too_many_arguments suppressions
Tests	Medium	Test verifies trivial inequality; missing current-thread and macro tests
Tests	Low	No test for unnamed runtime returning None
Docs	Low	.unwrap() in Handle::name() doc example can panic unexpectedly
API	Low	Empty string accepted silently as a valid name
Cargo	Informational	path dependency must be removed before publishing

Overall this is a useful and well-scoped addition. The core implementation is correct: the name flows properly from the builder through both scheduler handles and is accessible via the public API. Addressing the test coverage and the Config struct design point would bring this to a mergeable state.

[martin-augment]

2. name field visibility is broader than necessary

In both current_thread::Handle and multi_thread::Handle, the field is declared pub(crate), but it is only accessed through the name() accessor method. It could be private or pub(super) since no other module accesses the field directly.

value:useful; category:bug; feedback: The Claude AI reviewer is correct! There is no need the fields to be visible in the crate. The getter methods are visible and they should be used instead.

[martin-augment]

Tests

4. The new test does not verify the actual stored name

The test different_runtime_names asserts that two differently-named runtimes have different names -- trivially true regardless of the implementation. More meaningful assertions would be direct equality checks on the stored values.

5. Missing test for the current_thread flavor

All new test coverage is in rt_threaded.rs (multi-thread only). There is no equivalent test for the current-thread scheduler.

6. No test that an unnamed runtime returns None

There is no test verifying the default None behavior when .name() is not called on the builder.

7. No end-to-end test for the macro-level name attribute

The compile-fail test for name = 123 is a good addition, but there is no runtime test verifying that name = "my-name" correctly propagates the name to Handle::current().name().

value:good-to-have; category:bug; feedback: The Claude AI reviewer is correct! Adding more tests would prevent regressions in the future and would document the new functionality.