Repository: tokio-rs/tokio
File: tokio/src/runtime/mod.rs (Rust)

Code before:
//! > * There is some number `MAX_TASKS` such that the total number of tasks on
//! >   the runtime never exceeds `MAX_TASKS`.
//! > * There is some number `MAX_POLL` such that calling [`poll`] on any task
//! >   spawned on the runtime returns within `MAX_POLL` time units.
//! >
//! > Then, it is guaranteed that tasks are scheduled fairly, that is, there is
//! > some number `MAX_DELAY` such that when a task becomes ready, it will be
//! > polled by the runtime within `MAX_DELAY` time units.
//!
//! Other than the above fairness guarantee, there is no guarantee about the
//! order in which tasks are polled. There is also no guarantee that the runtime
//! is equally fair to all tasks. For example, if the runtime has two tasks A
//! and B that are both ready, then the runtime may poll A five times before it
//! polls B. This is the case even if A yields using [`yield_now`]. All that is
//! guaranteed is that it will poll B eventually.
//!
//! Normally, tasks are polled only if they have notified the runtime by waking
//! their waker. However, this is not guaranteed, and Tokio may poll tasks that
//! have not notified the runtime under some circumstances. This is called a
//! spurious wakeup.
//!
//! ## IO and timers
//!
//! Beyond just polling tasks, the runtime must also manage IO resources and
//! timers. It does this by periodically checking whether there are any IO
//! resources or timers that are ready, and notifying the relevant task so that
//! it will be polled.
//!
//! These checks are performed periodically between polling tasks. Under the
//! same assumptions as the previous fairness guarantee, Tokio guarantees that
//! it will notify tasks with an IO or timer event within some maximum number of
//! time units.
//!
//! ## Current behavior (current thread runtime)
//!
//! This section describes how the [current thread runtime] behaves today. This
//! behavior may change in future versions of Tokio.
//!
//! The current thread runtime maintains two FIFO queues of tasks that are ready
//! to be polled: the global queue and the local queue. The runtime will prefer
//! to choose the next task to poll from the local queue, and will only pick a
//! task from the global queue if the local queue is empty, or if it has picked
//! a task from the local queue 31 times in a row. The number 31 can be
//! changed using the [`global_queue_interval`] setting.
//!
//! The runtime will check for new IO or timer events whenever there are no
//! tasks ready to be polled, or when it has polled 61 tasks in a row. The
//! number 61 may be changed using the [`event_interval`] setting.
//!
//! When a task is woken from within a task running on the runtime, then the
//! woken task is added directly to the local queue. Otherwise, the task is

Review comment (suggestion):
Does "notifying" here mean waking the task?

I feel that some clarification is needed because in the previous section we talk about a task notifying the runtime (via the waker) and here we talk about the runtime notifying the task.

Code after:
//! > fairly.
//!
//! Or, more formally:
//!
//! > Under the following two assumptions:
//! >
//! > * There is some number `MAX_TASKS` such that the total number of tasks on
//! >   the runtime at any specific point in time never exceeds `MAX_TASKS`.
//! > * There is some number `MAX_SCHEDULE` such that calling [`poll`] on any
//! >   task spawned on the runtime returns within `MAX_SCHEDULE` time units.
//! >
//! > Then, there is some number `MAX_DELAY` such that when a task is woken, it
//! > will be scheduled by the runtime within `MAX_DELAY` time units.
//!
//! (Here, `MAX_TASKS` and `MAX_SCHEDULE` can be any number and the user of
//! the runtime may choose them. The `MAX_DELAY` number is controlled by the
//! runtime, and depends on the value of `MAX_TASKS` and `MAX_SCHEDULE`.)
//!
//! Other than the above fairness guarantee, there is no guarantee about the
//! order in which tasks are scheduled. There is also no guarantee that the
//! runtime is equally fair to all tasks. For example, if the runtime has two
//! tasks A and B that are both ready, then the runtime may schedule A five
//! times before it schedules B. This is the case even if A yields using
//! [`yield_now`]. All that is guaranteed is that it will schedule B eventually.
//!
//! Normally, tasks are scheduled only if they have been woken by calling
//! [`wake`] on their waker. However, this is not guaranteed, and Tokio may
//! schedule tasks that have not been woken under some circumstances. This is
//! called a spurious wakeup.
//!
//! ## IO and timers
//!
//! Beyond just scheduling tasks, the runtime must also manage IO resources and
//! timers. It does this by periodically checking whether there are any IO
//! resources or timers that are ready, and waking the relevant task so that
//! it will be scheduled.
//!
//! These checks are performed periodically between scheduling tasks. Under the
//! same assumptions as the previous fairness guarantee, Tokio guarantees that
//! it will wake tasks with an IO or timer event within some maximum number of
//! time units.
//!
//! ## Current thread runtime (behavior at the time of writing)
//!
//! This section describes how the [current thread runtime] behaves today. This
//! behavior may change in future versions of Tokio.
//!
//! The current thread runtime maintains two FIFO queues of tasks that are ready
//! to be scheduled: the global queue and the local queue. The runtime will prefer
//! to choose the next task to schedule from the local queue, and will only pick a
//! task from the global queue if the local queue is empty, or if it has picked