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

The unix.scheduler vocabulary currently implements a subset
	of the functions specified by POSIX to exist in the
	<sched.h> header.

This subset is needed to provide important functionality to
	the upcoming posix-spawn backend for io.launcher and
	the <process> interface.

diff --git a/basis/unix/scheduler/authors.txt b/basis/unix/scheduler/authors.txt
new file mode 100644 (file)
index 0000000..9d4a8e1
--- /dev/null
+++ b/basis/unix/scheduler/authors.txt
@@ -0,0 +1 @@
+Cat Stevens

diff --git a/basis/unix/scheduler/freebsd/freebsd.factor b/basis/unix/scheduler/freebsd/freebsd.factor
new file mode 100644 (file)
index 0000000..4e572bd
--- /dev/null
+++ b/basis/unix/scheduler/freebsd/freebsd.factor
@@ -0,0 +1,19 @@
+! Copyright (C) 2022 Cat Stevens.
+! See http://factorcode.org/license.txt for BSD license.
+USING: alien.c-types alien.syntax kernel ;
+IN: unix.scheduler
+
+CONSTANT: SCHED_FIFO  1
+CONSTANT: SCHED_OTHER 2
+CONSTANT: SCHED_RR    3
+
+CONSTANT: MOST_IDLE_SCHED_POLICY 2
+
+FUNCTION: int sched_get_priority_min ( int policy )
+FUNCTION: int sched_get_priority_max ( int policy )
+
+: policy-priority-range ( policy -- high low )
+    [ sched_get_priority_max ] [ sched_get_priority_min ] bi ;
+
+: priority-allowed? ( policy -- ? )
+    SCHED_OTHER = not ;

diff --git a/basis/unix/scheduler/freebsd/platforms.txt b/basis/unix/scheduler/freebsd/platforms.txt
new file mode 100644 (file)
index 0000000..edfe860
--- /dev/null
+++ b/basis/unix/scheduler/freebsd/platforms.txt
@@ -0,0 +1 @@
+freebsd

diff --git a/basis/unix/scheduler/linux/linux.factor b/basis/unix/scheduler/linux/linux.factor
new file mode 100644 (file)
index 0000000..0e0083a
--- /dev/null
+++ b/basis/unix/scheduler/linux/linux.factor
@@ -0,0 +1,30 @@
+! Copyright (C) 2022 Cat Stevens.
+! See http://factorcode.org/license.txt for BSD license.
+USING: alien.c-types alien.syntax kernel sequences ;
+IN: unix.scheduler
+
+! Note: Feature "_POSIX_PRIORITY_SCHEDULING"
+! Scheduling policy values from <sched.h>
+CONSTANT: SCHED_OTHER 0
+CONSTANT: SCHED_FIFO  1
+CONSTANT: SCHED_RR    2
+
+! Note: Feature "__USE_GNU"
+CONSTANT: SCHED_BATCH    3
+CONSTANT: SCHED_ISO      4
+CONSTANT: SCHED_IDLE     5
+CONSTANT: SCHED_DEADLINE 6
+
+CONSTANT: SCHED_RESET_ON_FORK 0x40000000
+! end __USE_GNU
+
+CONSTANT: MOST_IDLE_SCHED_POLICY 5
+
+FUNCTION: int sched_get_priority_min ( int policy )
+FUNCTION: int sched_get_priority_max ( int policy )
+
+: policy-priority-range ( policy -- high low )
+    [ sched_get_priority_max ] [ sched_get_priority_min ] bi ;
+
+: priority-allowed? ( policy -- ? )
+    { SCHED_IDLE SCHED_OTHER SCHED_BATCH } member? not ;

diff --git a/basis/unix/scheduler/linux/platforms.txt b/basis/unix/scheduler/linux/platforms.txt
new file mode 100644 (file)
index 0000000..a08e1f3
--- /dev/null
+++ b/basis/unix/scheduler/linux/platforms.txt
@@ -0,0 +1 @@
+linux

diff --git a/basis/unix/scheduler/macosx/macosx.factor b/basis/unix/scheduler/macosx/macosx.factor
new file mode 100644 (file)
index 0000000..4a1d6f5
--- /dev/null
+++ b/basis/unix/scheduler/macosx/macosx.factor
@@ -0,0 +1,12 @@
+! Copyright (C) 2022 Cat Stevens.
+! See http://factorcode.org/license.txt for BSD license.
+USING: system vocabs.metadata ;
+IN: unix.scheduler
+
+CONSTANT: MOST_IDLE_SCHED_POLICY f
+
+: policy-priority-range ( policy -- * )
+    os bad-platform ;
+
+: priority-allowed? ( policy -- * )
+    os bad-platform ;

diff --git a/basis/unix/scheduler/macosx/platforms.txt b/basis/unix/scheduler/macosx/platforms.txt
new file mode 100644 (file)
index 0000000..6e806f4
--- /dev/null
+++ b/basis/unix/scheduler/macosx/platforms.txt
@@ -0,0 +1 @@
+macosx

diff --git a/basis/unix/scheduler/platforms.txt b/basis/unix/scheduler/platforms.txt
new file mode 100644 (file)
index 0000000..509143d
--- /dev/null
+++ b/basis/unix/scheduler/platforms.txt
@@ -0,0 +1 @@
+unix

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"
+    }
+} ;

diff --git a/basis/unix/scheduler/scheduler.factor b/basis/unix/scheduler/scheduler.factor
new file mode 100644 (file)
index 0000000..926740f
--- /dev/null
+++ b/basis/unix/scheduler/scheduler.factor
@@ -0,0 +1,6 @@
+! Copyright (C) 2022 Cat Stevens.
+! See http://factorcode.org/license.txt for BSD license.
+USING: accessors sequences system vocabs ;
+IN: unix.scheduler
+
+<< "unix.scheduler." os name>> append require >>

diff --git a/basis/unix/scheduler/summary.txt b/basis/unix/scheduler/summary.txt
new file mode 100644 (file)
index 0000000..f102b89
--- /dev/null
+++ b/basis/unix/scheduler/summary.txt
@@ -0,0 +1 @@
+Unix Process Scheduling