basis/unix/scheduler/scheduler-docs.factor

   1 ! Copyright (C) 2022 Cat Stevens.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: alien.c-types help.markup help.syntax kernel system ;
   4 IN: unix.scheduler
   5
   6 ARTICLE: "unix.scheduler" "Unix Process Scheduling"
   7 "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."
   8 $nl "Cross platform constants:"
   9 { $subsections MOST_IDLE_SCHED_POLICY }
  10 "Utility words:"
  11 { $subsections policy-priority-range priority-allowed? } ;
  12
  13 ABOUT: "unix.scheduler"
  14
  15 HELP: MOST_IDLE_SCHED_POLICY
  16 { $description
  17     "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 } "." }
  18     $nl
  19     { $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)."
  20 } ;
  21
  22 HELP: policy-priority-range
  23 { $values { "policy" int } { "high" int } { "low" int } }
  24 { $description
  25     "Find the upper and lower bound on scheduler priority value, for a given scheduler policy. Each available scheduler policy ("
  26     { $snippet "SCHED_OTHER" } ", " { $snippet "SCHED_FIFO" } ", etc) may have its own range of allowable priorities."
  27 }
  28 { $examples
  29     { $unchecked-example
  30         "USING: formatting unix.scheduler ;"
  31         "SCHED_OTHER policy-priority-range \"High: %d Low: %d\\n\" printf"
  32         "High: 0 Low: 0"
  33     }
  34     { $unchecked-example
  35         "USING: formatting unix.scheduler ;"
  36         "SCHED_FIFO policy-priority-range \"High: %d Low: %d\\n\" printf"
  37         "High: 99 Low: 1"
  38     }
  39 } ;
  40
  41 HELP: priority-allowed?
  42 { $values { "policy" int } { "?" boolean } }
  43 { $description
  44     { $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."
  45     $nl
  46     "Depending on platform, normal scheduling policies (such as " { $snippet "SCHED_OTHER" } ", " { $snippet "SCHED_BATCH" } ", and " { $snippet "SCHED_IDLE" }
  47     ") 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"
  48     " range found by " { $link policy-priority-range } "."
  49 }
  50 { $examples
  51     { $unchecked-example
  52         "USE: unix.scheduler"
  53         "SCHED_OTHER priority-allowed? ."
  54         "f"
  55     }
  56     { $unchecked-example
  57         "USE: unix.scheduler"
  58         "SCHED_FIFO priority-allowed? ."
  59         "t"
  60     }
  61 } ;