unix.scheduler: small new vocab to get Unix scheduler info

[factor.git] / basis / unix / scheduler / scheduler-docs.factor

diff --git a/basis/unix/scheduler/scheduler-docs.factor b/basis/unix/scheduler/scheduler-docs.factor
new file mode 100644 (file)
index 0000000..13d20a5
--- /dev/null
+++ b/basis/unix/scheduler/scheduler-docs.factor
@@ -0,0 +1,61 @@
+! Copyright (C) 2022 Cat Stevens.
+! See http://factorcode.org/license.txt for BSD license.
+USING: alien.c-types help.markup help.syntax kernel system ;
+IN: unix.scheduler
+
+ARTICLE: "unix.scheduler" "Unix Process Scheduling"
+"The " { $vocab-link "unix.scheduler" } "vocabulary provides an interface to the POSIX process scheduler. " { $link macosx } " does not implement POSIX Process Scheduling, but does have other similar low-level APIs exposed by this vocabulary."
+$nl "Cross platform constants:"
+{ $subsections MOST_IDLE_SCHED_POLICY }
+"Utility words:"
+{ $subsections policy-priority-range priority-allowed? } ;
+
+ABOUT: "unix.scheduler"
+
+HELP: MOST_IDLE_SCHED_POLICY
+{ $description
+    "The scheduling policy value which is, or is most like, the " { $snippet "SCHED_IDLE" } " policy on Linux. The value of this word is platform specific, and differs between " { $link linux } ", " { $link macosx } " and " { $link freebsd } "." }
+    $nl
+    { $snippet "sched(7)" } " describes " { $snippet "SCHED_IDLE" } " to be " { $emphasis "intended for running jobs at extremely low priority (lower even than a +19 nice value with the SCHED_OTHER or SCHED_BATCH policies)."
+} ;
+
+HELP: policy-priority-range
+{ $values { "policy" int } { "high" int } { "low" int } }
+{ $description
+    "Find the upper and lower bound on scheduler priority value, for a given scheduler policy. Each available scheduler policy ("
+    { $snippet "SCHED_OTHER" } ", " { $snippet "SCHED_FIFO" } ", etc) may have its own range of allowable priorities."
+}
+{ $examples
+    { $unchecked-example
+        "USING: formatting unix.scheduler ;"
+        "SCHED_OTHER policy-priority-range \"High: %d Low: %d\\n\" printf"
+        "High: 0 Low: 0"
+    }
+    { $unchecked-example
+        "USING: formatting unix.scheduler ;"
+        "SCHED_FIFO policy-priority-range \"High: %d Low: %d\\n\" printf"
+        "High: 99 Low: 1"
+    }
+} ;
+
+HELP: priority-allowed?
+{ $values { "policy" int } { "?" boolean } }
+{ $description
+    { $link t } " if the input scheduling policy can be used with a non-zero static priority, " { $link POSTPONE: f } " otherwise. This word allows a platform's real-time policies to be distinguished from normal scheduling policies."
+    $nl
+    "Depending on platform, normal scheduling policies (such as " { $snippet "SCHED_OTHER" } ", " { $snippet "SCHED_BATCH" } ", and " { $snippet "SCHED_IDLE" }
+    ") must be used with a static scheduling priority of " { $snippet "0" } ". Similarly, the real-time policies must be used with a non-zero priority, within the"
+    " range found by " { $link policy-priority-range } "."
+}
+{ $examples
+    { $unchecked-example
+        "USE: unix.scheduler"
+        "SCHED_OTHER priority-allowed? ."
+        "f"
+    }
+    { $unchecked-example
+        "USE: unix.scheduler"
+        "SCHED_FIFO priority-allowed? ."
+        "t"
+    }
+} ;