runtime: Clarify the documentation for global_queue_interval=1

[martin-g]

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:

tokio/tokio/src/runtime/scheduler/multi_thread/worker.rs

Lines 806 to 813 in 7127e25

	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

[ADD-SP]

In my opinion, this explanation is too specific, we can explain it more general. We just need to warn the downstream that an unreasonably low value might starve the tasks in the local queue.

I'm less worried about the global_queue_interval=1 or global_queue_interval=2, downstream shouldn't change it unless they know what they are doing.

[martin-g]

My reason to suggest this change is because of Setting the interval to a smaller value increases the fairness of the scheduler in the current documentation which becomes false when one goes down to 1.
It is a corner case that breaks completely the promise of more fairness.

[ADD-SP]

For my perspective, global_queue_interval=2 is also a corner case, it also breaks the "fairness" promise. If we warn the =1, we should also warn =2. Is =3 reasonable? I don't know without concrete usecase, so I suggest make it more general.

The global_queue_interval is a magic number, downstream should know what they are doing while tuning a magic number.

[martin-g]

=2 is complete fairness - one tick for global, one for local.
=3 is 33.3% for global, 66.6% for local
=4 is 25% for global, 75% for local
All these fit perfectly for Setting the interval to a smaller value increases the fairness of the scheduler
Only =1 breaks it.

I have no better idea how to make it more generic and clear in the same time.
I am OK to close this PR without merging if you think the changes do not make things more clear!

[ADD-SP]

It looks like we are using different definition of "fairness". Sometimes, a new task will be pushed into the local queue. So the "global queue" and "local queue" fairness is not the same "fairness" of all tasks.

But if you mean the "fairness" just for "global queue" and "local queue", I agree only "=1" breaks.

I believe the "fairness" is somewhat misleading for downstream, they have to know the internal details of the tokio scheduler to understand its definition correctly.

Do you have idea to improve it?

[Darksonn]

Honestly, I think 1 is just an invalid value.

[martin-g]

I think 1 is just an invalid value.

I'd agree with this.