rt: clarify the documentation of `Runtime::spawn` by Its-Just-Nans · Pull Request #7803 · tokio-rs/tokio

Its-Just-Nans · 2025-12-29T03:41:05Z

Motivation

Following #7802 (review)

I think clarifiying the doc of spawn() is better

Rendered

Co-authored-by: Qi <add_sp@outlook.com>

ADD-SP

By the way, there are Handle::spawn and tokio::spawn, could you also update their docs?

Its-Just-Nans · 2025-12-29T04:00:51Z

By the way, there are Handle::spawn and tokio::spawn, could you also update their docs?

I've updated, tell me what I need to change

ADD-SP

We don't need fully qualified syntax in the docs.

Co-authored-by: Qi <add_sp@outlook.com>

…into change-doc-sentence

martin-g

I've updated the infra-doc links according to https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html

Backticks around the link will be stripped, so [Option] will correctly link to Option.

Co-authored-by: Martin Grigorov <martin-g@users.noreply.github.com>

Darksonn · 2026-01-01T17:44:51Z

I think it may be less confusing to introduce a concept along of whether or not the runtime is running.

The provided future will start running in the background immediately when spawn is called, even if you don't await the returned JoinHandle. (As long as the runtime is running.)

And then the word "running" can be a link to a new section in the docs for tokio::runtime, which clarifies that the multi-threaded runtime is always running, that the current-thread runtime is only running when there is at least on call to Runtime::block_on(), and that a LocalSet is running when it's being driven by one of more mechanisms.

Its-Just-Nans · 2026-01-02T00:10:51Z

And then the word "running" can be a link to a new section in the docs for tokio::runtime, which clarifies that the multi-threaded runtime is always running, that the current-thread runtime is only running when there is at least on call to Runtime::block_on(), and that a LocalSet is running when it's being driven by one of more mechanisms.

I think that's a nice idea! I've updated my branch with this change(s)

ping @ADD-SP - i've updated the docs

Its-Just-Nans · 2026-01-20T03:39:58Z

Hi

Should I change something ?

Co-authored-by: Alice Ryhl <aliceryhl@google.com>

Darksonn

Thanks.

Darksonn

Thank you.

This PR contains the following updates: | Package | Type | Update | Change | |---|---|---|---| | [tokio](https://tokio.rs) ([source](https://github.com/tokio-rs/tokio)) | dependencies | minor | `1.49.0` → `1.50.0` | --- ### Release Notes <details> <summary>tokio-rs/tokio (tokio)</summary> ### [`v1.50.0`](https://github.com/tokio-rs/tokio/releases/tag/tokio-1.50.0): Tokio v1.50.0 [Compare Source](tokio-rs/tokio@tokio-1.49.0...tokio-1.50.0) ### 1.50.0 (Mar 3rd, 2026) ##### Added - net: add `TcpStream::set_zero_linger` ([#7837]) - rt: add `is_rt_shutdown_err` ([#7771]) ##### Changed - io: add optimizer hint that `memchr` returns in-bounds pointer ([#7792]) - io: implement vectored writes for `write_buf` ([#7871]) - runtime: panic when `event_interval` is set to 0 ([#7838]) - runtime: shorten default thread name to fit in Linux limit ([#7880]) - signal: remember the result of `SetConsoleCtrlHandler` ([#7833]) - signal: specialize windows `Registry` ([#7885]) ##### Fixed - io: always cleanup `AsyncFd` registration list on deregister ([#7773]) - macros: remove (most) local `use` declarations in `tokio::select!` ([#7929]) - net: fix `GET_BUF_SIZE` constant for `target_os = "android"` ([#7889]) - runtime: avoid redundant unpark in current\_thread scheduler ([#7834]) - runtime: don't park in `current_thread` if `before_park` defers waker ([#7835]) - io: fix write readiness on ESP32 on short writes ([#7872]) - runtime: wake deferred tasks before entering `block_in_place` ([#7879]) - sync: drop rx waker when oneshot receiver is dropped ([#7886]) - runtime: fix double increment of `num_idle_threads` on shutdown ([#7910], [#7918], [#7922]) ##### Unstable - fs: check for io-uring opcode support ([#7815]) - runtime: avoid lock acquisition after uring init ([#7850]) ##### Documented - docs: update outdated unstable features section ([#7839]) - io: clarify the behavior of `AsyncWriteExt::shutdown()` ([#7908]) - io: explain how to flush stdout/stderr ([#7904]) - io: fix incorrect and confusing `AsyncWrite` documentation ([#7875]) - rt: clarify the documentation of `Runtime::spawn` ([#7803]) - rt: fix missing quotation in docs ([#7925]) - runtime: correct the default thread name in docs ([#7896]) - runtime: fix `event_interval` doc ([#7932]) - sync: clarify RwLock fairness documentation ([#7919]) - sync: clarify that `recv` returns `None` once closed and no more messages ([#7920]) - task: clarify when to use `spawn_blocking` vs dedicated threads ([#7923]) - task: doc that task drops before `JoinHandle` completion ([#7825]) - signal: guarantee that listeners never return `None` ([#7869]) - task: fix task module feature flags in docs ([#7891]) - task: fix two typos ([#7913]) - task: improve the docs of `Builder::spawn_local` ([#7828]) - time: add docs about auto-advance and when to use sleep ([#7858]) - util: fix typo in docs ([#7926]) [#7771]: tokio-rs/tokio#7771 [#7773]: tokio-rs/tokio#7773 [#7792]: tokio-rs/tokio#7792 [#7803]: tokio-rs/tokio#7803 [#7815]: tokio-rs/tokio#7815 [#7825]: tokio-rs/tokio#7825 [#7828]: tokio-rs/tokio#7828 [#7833]: tokio-rs/tokio#7833 [#7834]: tokio-rs/tokio#7834 [#7835]: tokio-rs/tokio#7835 [#7837]: tokio-rs/tokio#7837 [#7838]: tokio-rs/tokio#7838 [#7839]: tokio-rs/tokio#7839 [#7850]: tokio-rs/tokio#7850 [#7858]: tokio-rs/tokio#7858 [#7869]: tokio-rs/tokio#7869 [#7871]: tokio-rs/tokio#7871 [#7872]: tokio-rs/tokio#7872 [#7875]: tokio-rs/tokio#7875 [#7879]: tokio-rs/tokio#7879 [#7880]: tokio-rs/tokio#7880 [#7885]: tokio-rs/tokio#7885 [#7886]: tokio-rs/tokio#7886 [#7889]: tokio-rs/tokio#7889 [#7891]: tokio-rs/tokio#7891 [#7896]: tokio-rs/tokio#7896 [#7904]: tokio-rs/tokio#7904 [#7908]: tokio-rs/tokio#7908 [#7910]: tokio-rs/tokio#7910 [#7913]: tokio-rs/tokio#7913 [#7918]: tokio-rs/tokio#7918 [#7919]: tokio-rs/tokio#7919 [#7920]: tokio-rs/tokio#7920 [#7922]: tokio-rs/tokio#7922 [#7923]: tokio-rs/tokio#7923 [#7925]: tokio-rs/tokio#7925 [#7926]: tokio-rs/tokio#7926 [#7929]: tokio-rs/tokio#7929 [#7932]: tokio-rs/tokio#7932 </details> --- ### Configuration 📅 **Schedule**: Branch creation - Between 12:00 AM and 03:59 AM ( * 0-3 * * * ) in timezone Pacific/Auckland, Automerge - Between 12:00 AM and 03:59 AM ( * 0-3 * * * ) in timezone Pacific/Auckland. 🚦 **Automerge**: Disabled because a matching PR was automerged previously. ♻ **Rebasing**: Whenever PR is behind base branch, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).  Reviewed-on: https://harton.dev/project-neon/neonfs/pulls/53 Co-authored-by: Renovate Bot <bot@harton.nz> Co-committed-by: Renovate Bot <bot@harton.nz>

feat: clarify spawn call

8e6dbb5

Its-Just-Nans mentioned this pull request Dec 29, 2025

rt: clarify the behavior of Runtime::spawn #7802

Closed

Its-Just-Nans changed the title ~~feat: clarify spawn call~~ rt: clarify the documentation of Runtime::spawn Dec 29, 2025

ADD-SP reviewed Dec 29, 2025

View reviewed changes

Comment thread tokio/src/runtime/runtime.rs Outdated

Comment thread tokio/src/runtime/runtime.rs Outdated

ADD-SP added T-docs Topic: documentation A-tokio Area: The main tokio crate M-runtime Module: tokio/runtime labels Dec 29, 2025

Update tokio/src/runtime/runtime.rs

051623b

Co-authored-by: Qi <add_sp@outlook.com>

ADD-SP reviewed Dec 29, 2025

View reviewed changes

update sentence

924d772

ADD-SP added the S-waiting-on-author Status: awaiting some action (such as code changes) from the PR or issue author. label Dec 29, 2025

fix CI

dede762

Its-Just-Nans requested a review from ADD-SP December 29, 2025 04:08

ADD-SP reviewed Dec 29, 2025

View reviewed changes

Comment thread tokio/src/runtime/handle.rs Outdated

Comment thread tokio/src/runtime/runtime.rs Outdated

Its-Just-Nans and others added 3 commits December 29, 2025 05:16

Update tokio/src/runtime/runtime.rs

f2ab9df

Co-authored-by: Qi <add_sp@outlook.com>

fix link

02a5ce9

Merge branch 'change-doc-sentence' of github.com:Its-Just-Nans/tokio …

dc7a2ce

…into change-doc-sentence

Its-Just-Nans requested a review from ADD-SP December 29, 2025 04:21

ADD-SP removed the S-waiting-on-author Status: awaiting some action (such as code changes) from the PR or issue author. label Dec 29, 2025

martin-g reviewed Dec 29, 2025

View reviewed changes

Its-Just-Nans and others added 6 commits December 30, 2025 03:38

Update tokio/src/runtime/handle.rs

52a2cc3

Co-authored-by: Martin Grigorov <martin-g@users.noreply.github.com>

Update tokio/src/task/spawn.rs

14bfb82

Co-authored-by: Martin Grigorov <martin-g@users.noreply.github.com>

Update tokio/src/task/spawn.rs

25e30be

Co-authored-by: Martin Grigorov <martin-g@users.noreply.github.com>

Update tokio/src/task/spawn.rs

9a08f17

Co-authored-by: Martin Grigorov <martin-g@users.noreply.github.com>

Update tokio/src/runtime/runtime.rs

fbcd157

Co-authored-by: Martin Grigorov <martin-g@users.noreply.github.com>

Update tokio/src/runtime/runtime.rs

3063480

Co-authored-by: Martin Grigorov <martin-g@users.noreply.github.com>

ADD-SP added the S-waiting-on-author Status: awaiting some action (such as code changes) from the PR or issue author. label Dec 31, 2025

Darksonn reviewed Jan 1, 2026

View reviewed changes

Comment thread tokio/src/runtime/runtime.rs Outdated

Its-Just-Nans added 3 commits January 1, 2026 16:46

fix doc link for runtime

19976ba

try new docs

7a8cb70

add tokio-rs#7803 (comment)

33b05d9

Its-Just-Nans requested a review from Darksonn January 2, 2026 00:10

Its-Just-Nans added 2 commits January 1, 2026 18:55

spellcheck

f8b168d

fmt

2c80c10

Darksonn reviewed Jan 3, 2026

View reviewed changes

Comment thread tokio/src/runtime/handle.rs Outdated

Comment thread tokio/src/runtime/mod.rs Outdated

Comment thread tokio/src/runtime/mod.rs Outdated

Its-Just-Nans added 3 commits January 3, 2026 11:22

change docs

66496ef

spellcheck

cefed98

spelling

531b492

ADD-SP removed the S-waiting-on-author Status: awaiting some action (such as code changes) from the PR or issue author. label Jan 8, 2026

Its-Just-Nans requested a review from Darksonn January 20, 2026 03:40

Darksonn reviewed Jan 21, 2026

View reviewed changes

Comment thread tokio/src/runtime/handle.rs Outdated

Comment thread tokio/src/task/spawn.rs Outdated

Its-Just-Nans and others added 2 commits January 24, 2026 22:24

Update tokio/src/runtime/handle.rs

ab1bf79

Co-authored-by: Alice Ryhl <aliceryhl@google.com>

add

a705a47

Its-Just-Nans requested a review from Darksonn January 24, 2026 23:01

Darksonn reviewed Jan 26, 2026

View reviewed changes

Comment thread tokio/src/runtime/runtime.rs Outdated

Comment thread tokio/src/task/spawn.rs Outdated

fix doc

9a27185

Its-Just-Nans requested a review from Darksonn January 29, 2026 04:23

change wording

37f51a1

Darksonn approved these changes Feb 4, 2026

View reviewed changes

Darksonn merged commit c0943f9 into tokio-rs:master Feb 4, 2026
88 checks passed

ADD-SP mentioned this pull request Feb 25, 2026

chore: prepare Tokio v1.50.0 #7934

Merged

Uh oh!

Conversation

Its-Just-Nans commented Dec 29, 2025 • edited by Darksonn Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Uh oh!

Uh oh!

Uh oh!

ADD-SP left a comment

Choose a reason for hiding this comment

Uh oh!

Its-Just-Nans commented Dec 29, 2025

Uh oh!

ADD-SP left a comment • 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!

Uh oh!

Uh oh!

martin-g left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Darksonn commented Jan 1, 2026

Uh oh!

Its-Just-Nans commented Jan 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Its-Just-Nans commented Jan 20, 2026

Uh oh!

Uh oh!

Uh oh!

Darksonn left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Darksonn left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Its-Just-Nans commented Dec 29, 2025 •

edited by Darksonn

Loading

ADD-SP left a comment •

edited

Loading

Its-Just-Nans commented Jan 2, 2026 •

edited

Loading