Skip to content

Conversation

@martin-g
Copy link
Member

Motivation

If the interval is set to 1 then the schedulers will always execute tasks from the global queue. Tasks from the local queue will be executed only if the global queue is empty.

multi_thread scheduler:

if self.tick % self.global_queue_interval == 0 {
// Update the global queue interval, if needed
self.tune_global_queue_interval(worker);
worker
.handle
.next_remote_task()
.or_else(|| self.next_local_task())

I think this clarification is needed because of

Setting the interval to a smaller value increases the fairness of the scheduler,
    /// at the cost of more synchronization overhead.

at https://github.com/tokio-rs/tokio/blob/7127e257a7d7025a5f6a62eb8aab81c2191f5cdb/tokio/src/runtime/builder.rs#L980C16-L981C54
With 1 there is no fairness anymore

Solution

Add a sentence to the documentation about the special case of global_queue_interval=1

@martin-g martin-g force-pushed the document-global_queue_interval=1 branch from c27a23c to 00d306c Compare September 10, 2025 12:41
If the interval is set to 1 then the schedulers will always execute
tasks from the global queue. Tasks from the local queue will be executed
only if the global queue is empty.

multi_thread scheduler: https://github.com/tokio-rs/tokio/blob/7127e257a7d7025a5f6a62eb8aab81c2191f5cdb/tokio/src/runtime/scheduler/multi_thread/worker.rs#L806-L813
@martin-g martin-g force-pushed the document-global_queue_interval=1 branch from 00d306c to d778ecc Compare September 10, 2025 12:46
@ADD-SP ADD-SP added T-docs Topic: documentation A-tokio Area: The main tokio crate M-runtime Module: tokio/runtime S-waiting-on-author Status: awaiting some action (such as code changes) from the PR or issue author. labels Sep 10, 2025
Copy link
Member

@ADD-SP ADD-SP left a comment

Choose a reason for hiding this comment

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

I think there is a space to improve the docs of global_queue_interval, but it is not required to do it in this PR. Thanks!

@ADD-SP ADD-SP changed the title runtime: Clarify the documentation for global_queue_interval=1 runtime: clarify the edge case of Builder::global_queue_interval() Sep 16, 2025
@ADD-SP ADD-SP merged commit 7c197c7 into tokio-rs:master Sep 16, 2025
103 checks passed
@martin-g martin-g deleted the document-global_queue_interval=1 branch September 16, 2025 13:46
@Darksonn Darksonn mentioned this pull request Oct 14, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A-tokio Area: The main tokio crate M-runtime Module: tokio/runtime S-waiting-on-author Status: awaiting some action (such as code changes) from the PR or issue author. T-docs Topic: documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants