system-docs: add article on Ctrl-Break handler

diff --git a/core/system/system-docs.factor b/core/system/system-docs.factor
index cee27e05d342cfecd5b2085dc87149c0210c8adf..1257eb77000e1c0778c901c5f993323def05ebd5 100644 (file)
--- a/core/system/system-docs.factor
+++ b/core/system/system-docs.factor
@@ -7,6 +7,7 @@ ARTICLE: "system" "System interface"
 { $subsections
     "cpu"
     "os"
+    "ctrl-break"
 }
 "Getting the path to the Factor VM and image:"
 { $subsections
@@ -46,6 +47,21 @@ ARTICLE: "os" "Operating system detection"
     windows
 } ;
 
+ARTICLE: "ctrl-break" "Ctrl-Break handler"
+"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."
+$nl
+"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."
+$nl
+"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."
+$nl
+"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" } ":"
+{ $code
+    "USING: listener namespaces ;"
+    "t handle-ctrl-break set-global"
+}
+$nl
+"Managing the Ctrl-Break handler:"
+{ $subsections enable-ctrl-break disable-ctrl-break } ;
 
 HELP: cpu
 { $values { "class" singleton-class } }
@@ -79,3 +95,11 @@ HELP: image-path
 HELP: vm-path
 { $values { "path" "a pathname string" } }
 { $description "Outputs the pathname of the currently running Factor VM." } ;
+
+HELP: enable-ctrl-break
+{ $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." }
+{ $see-also disable-ctrl-break } ;
+
+HELP: disable-ctrl-break
+{ $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." }
+{ $see-also enable-ctrl-break } ;