[newlib-cygwin/main] Cygwin: doc: document sched_setpolicy(2) and priority mapping

[Corinna Vinschen]

https://sourceware.org/git/gitweb.cgi?p=newlib-cygwin.git;h=757424f744000b0feff8693b47827d5f626434b2

commit 757424f744000b0feff8693b47827d5f626434b2
Author:     Christian Franke <christian.franke@t-online.de>
AuthorDate: Mon Dec 2 18:27:22 2024 +0100
Commit:     Corinna Vinschen <corinna@vinschen.de>
CommitDate: Wed Dec 4 19:06:48 2024 +0100

    Cygwin: doc: document sched_setpolicy(2) and priority mapping
    
    Document the long standing mapping from nice or sched_priority
    values to Windows priority classes and the new behavior of
    sched_setpolicy(8).
    
    Signed-off-by: Christian Franke <christian.franke@t-online.de>

Diff:
---
 winsup/doc/posix.xml | 34 ++++++++++++++++++++++++++++++----
 1 file changed, 30 insertions(+), 4 deletions(-)

diff --git a/winsup/doc/posix.xml b/winsup/doc/posix.xml
index 89056915bf50..436ab00a743c 100644
--- a/winsup/doc/posix.xml
+++ b/winsup/doc/posix.xml
@@ -601,7 +601,7 @@ also IEEE Std 1003.1-2017 (POSIX.1-2017).</para>
     nexttowardf
     nexttowardl
     nftw
-    nice
+    nice			(see <xref linkend="std-notes">chapter "Implementation Notes"</xref>)
     nl_langinfo
     nl_langinfo_l
     nrand48
@@ -818,8 +818,8 @@ also IEEE Std 1003.1-2017 (POSIX.1-2017).</para>
     sched_getparam
     sched_getscheduler
     sched_rr_get_interval
-    sched_setparam
-    sched_setscheduler
+    sched_setparam		(see <xref linkend="std-notes">chapter "Implementation Notes"</xref>)
+    sched_setscheduler		(see <xref linkend="std-notes">chapter "Implementation Notes"</xref>)
     sched_yield
     seed48
     seekdir
@@ -854,7 +854,7 @@ also IEEE Std 1003.1-2017 (POSIX.1-2017).</para>
     setlogmask
     setpgid
     setpgrp
-    setpriority
+    setpriority			(see <xref linkend="std-notes">chapter "Implementation Notes"</xref>)
     setprotoent
     setpwent
     setregid
@@ -1769,6 +1769,32 @@ atomic either.  Over-allocation with FALLOC_FL_KEEP_SIZE is only
 temporary on Windows until the last handle to the file is closed.
 Over-allocation on sparse files is entirely ignored on Windows.</para>
 
+<para><function>sched_setpolicy</function> only emulates API behavior
+because Windows does not offer alternative scheduling policies.
+If <literal>SCHED_OTHER</literal> is selected, the Windows priority is
+set according to the nice value.  If <literal>SCHED_FIFO</literal>
+or <literal>SCHED_RR</literal> is selected, the nice value is preserved
+and the Windows priority is set according to the
+<literal>sched_priority</literal> value.</para>
+
+<para><function>nice</function>, <function>setpriority</function>,
+<function>sched_setparam</function> and <function>sched_setpolicy</function>
+map the nice value (<literal>SCHED_OTHER</literal>) or the
+<literal>sched_priority</literal> (<literal>SCHED_FIFO</literal>,
+<literal>SCHED_RR</literal>) to Windows priority classes as follows:</para>
+<screen>
+    nice value   sched_priority   Windows priority class
+     12...19      1....6          IDLE_PRIORITY_CLASS
+      4...11      7...12          BELOW_NORMAL_PRIORITY_CLASS
+     -4....3     13...18          NORMAL_PRIORITY_CLASS
+    -12...-5     19...24          ABOVE_NORMAL_PRIORITY_CLASS
+    -13..-19     25...30          HIGH_PRIORITY_CLASS
+         -20     31...32          REALTIME_PRIORITY_CLASS
+</screen>
+The use of values which are mapped to the
+<literal>REALTIME_PRIORITY_CLASS</literal> require administrative
+privileges.
+
 </sect1>
 
 </chapter>