[ping][PATCH] manual: Explain sched_yield semantics with different schedulers

[Siddhesh Poyarekar]

ping!

On 2025-01-30 10:20, Siddhesh Poyarekar wrote:
> The manual entry for sched_yield mentions that the function call could
> be a nop if there are no other tasks with the same absolute priority.
> Expand the explanation to include example schedulers on Linux so that
> it's clear that sched_yield may not always result in a different task
> being scheduled.
> 
> Signed-off-by: Siddhesh Poyarekar <siddhesh@sourceware.org>
> ---
>   manual/resource.texi | 34 +++++++++++++++++++++++-----------
>   1 file changed, 23 insertions(+), 11 deletions(-)
> 
> diff --git a/manual/resource.texi b/manual/resource.texi
> index 0b82446817..260bfdb2e2 100644
> --- a/manual/resource.texi
> +++ b/manual/resource.texi
> @@ -929,18 +929,30 @@ function, so there are no specific @code{errno} values.
>   @c Direct syscall on Linux; alias to swtch on HURD.
>   
>   This function voluntarily gives up the task's claim on the CPU.
> -
> -Technically, @code{sched_yield} causes the calling task to be made
> -immediately ready to run (as opposed to running, which is what it was
> +Depending on the scheduling policy in effect and the tasks ready to run
> +on the system, another task may be scheduled to run instead.
> +
> +A call to @code{sched_yield} does not guarantee that a different task
> +from the calling task is scheduled as a result; it depends on the
> +scheduling policy used on the target system.  It is possible that the
> +call may not result in any visible effect, i.e. the same task gets
> +scheduled again.
> +
> +For example on Linux systems, when a simple priority-based FIFO
> +scheduling policy (SCHED_FIFO) is in effect, the calling task is made
> +immediately ready to run (as oposed to running, which is what it was
>   before).  This means that if it has absolute priority higher than 0, it
> -gets pushed onto the tail of the queue of tasks that share its
> -absolute priority and are ready to run, and it will run again when its
> -turn next arrives.  If its absolute priority is 0, it is more
> -complicated, but still has the effect of yielding the CPU to other
> -tasks.
> -
> -If there are no other tasks that share the calling task's absolute
> -priority, this function doesn't have any effect.
> +gets pushed onto the tail of the queue of tasks that share its absolute
> +priority and are ready to run, and it will run again when its turn next
> +arrives.  If its absolute priority is 0, it is more complicated, but
> +still has the effect of yielding the CPU to other tasks.  If there are
> +no other tasks that share the calling task's absolute priority, it will
> +be scheduled again as if @code{sched_yield} was never called.
> +
> +Another example could be a time slice based preemptive round-robin
> +policy, such as the SCHED_RR policy on Linux.  It is possible with this
> +policy that the calling task is scheduled again because it still has
> +time left in its slice.
>   
>   To the extent that the containing program is oblivious to what other
>   processes in the system are doing and how fast it executes, this