[PATCH] manual: Explain sched_yield semantics with different schedulers

[Siddhesh Poyarekar]

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
-- 
2.47.1