core/system/system-docs.factor

   1 USING: classes.singleton help.markup help.syntax init kernel math ;
   2 IN: system
   3
   4 ABOUT: "system"
   5
   6 ARTICLE: "system" "System interface"
   7 { $subsections
   8     "cpu"
   9     "os"
  10     "ctrl-break"
  11 }
  12 "Getting the path to the Factor VM and image:"
  13 { $subsections
  14     vm-path
  15     image-path
  16 }
  17 "Getting a monotonically increasing nanosecond count:"
  18 { $subsections nano-count }
  19 "Exiting the Factor VM:"
  20 { $subsections exit } ;
  21
  22 ARTICLE: "cpu" "Processor detection"
  23 "Processor detection:"
  24 { $subsections cpu }
  25 "Supported processors:"
  26 { $subsections
  27     x86.32
  28     x86.64
  29     ppc
  30     arm
  31 }
  32 "Processor families:"
  33 { $subsections x86 } ;
  34
  35 ARTICLE: "os" "Operating system detection"
  36 "Operating system detection:"
  37 { $subsections os }
  38 "Supported operating systems:"
  39 { $subsections
  40     linux
  41     macosx
  42     windows
  43 }
  44 "Operating system families:"
  45 { $subsections
  46     unix
  47     windows
  48 } ;
  49
  50 ARTICLE: "ctrl-break" "Ctrl-Break handler"
  51 "There is one global handler available per Factor VM, disabled by default. When enabled, it starts a separate native thread and polls the keyboard for the Ctrl-Break combination. If user presses Ctrl-Break with one of the Factor windows active, the handler causes an exception to be thrown in the main thread, which allows user to interrupt a VM stuck in a busy loop."
  52 $nl
  53 "Due to specific implementation requirements, this facility is only available on Windows platforms. Namely, it needs the ability to poll the keyboard state while the input focus belongs to another thread."
  54 $nl
  55 "While the handler is active, it can interrupt any code in Factor VM, including sensitive or low-level functions. If this happens, chances are VM won't be able to recover. To prevent crashes, only enable the handler while user code is running in the foreground. Don't enable it in the background threads before yielding, don't have it enabled while GC is working, etc. Always make sure you can catch the exception it would produce."
  56 $nl
  57 "The listener can activate the Ctrl-Break handler while it's compiling and running user code interactively, so that user could interrupt an infinite loop. To allow the listener use this facility, add the following code to your " { $link ".factor-rc" } ":"
  58 { $code
  59     "USING: listener namespaces ;"
  60     "t handle-ctrl-break set-global"
  61 }
  62 $nl
  63 "Managing the Ctrl-Break handler:"
  64 { $subsections enable-ctrl-break disable-ctrl-break } ;
  65
  66 HELP: cpu
  67 { $values { "class" singleton-class } }
  68 { $description
  69     "Outputs a singleton class with the name of the current CPU architecture."
  70 } ;
  71
  72 HELP: os
  73 { $values { "class" singleton-class } }
  74 { $description
  75     "Outputs a singleton class with the name of the current operating system family."
  76 } ;
  77
  78 HELP: embedded?
  79 { $values { "?" boolean } }
  80 { $description "Tests if this Factor instance is embedded in another application." } ;
  81
  82 HELP: exit
  83 { $values { "n" "an integer exit code" } }
  84 { $description "Runs all " { $link shutdown-hooks } " and then exits the Factor process. If an error occurs when the shutdown hooks runs, or when the process is about to terminate, the error is ignored and the process exits with status 255." } ;
  85
  86 HELP: nano-count
  87 { $values { "ns" integer } }
  88 { $description "Outputs a monotonically increasing count of nanoseconds elapsed since an arbitrary starting time. The difference of two calls to this word allows timing. This word is unaffected by system clock changes." }
  89 { $notes "This is a low-level word. The " { $vocab-link "tools.time" } " vocabulary defines words to time code execution time." } ;
  90
  91 HELP: image-path
  92 { $values { "path" "a pathname string" } }
  93 { $description "Outputs the pathname of the currently running Factor image." } ;
  94
  95 HELP: vm-path
  96 { $values { "path" "a pathname string" } }
  97 { $description "Outputs the pathname of the currently running Factor VM." } ;
  98
  99 HELP: enable-ctrl-break
 100 { $description "Enables the global Ctrl-Break handler. There is only one handler per Factor VM. If it is enabled, additional calls to enable-ctrl-break have no effect." }
 101 { $see-also disable-ctrl-break } ;
 102
 103 HELP: disable-ctrl-break
 104 { $description "Disables the global Ctrl-Break handler. There is one handler per Factor VM. If it is disabled, additional calls to disable-ctrl-break have no effect." }
 105 { $see-also enable-ctrl-break } ;