basis/unix/signals/signals-docs.factor

   1 ! Copyright (C) 2010 Joe Groff.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax kernel ;
   4 IN: unix.signals
   5
   6 HELP: add-signal-handler
   7 { $values
   8     { "handler" { $quotation ( -- ) } } { "sig" "a signal number" }
   9 }
  10 { $description "Adds a signal handler for " { $snippet "sig" } ". If " { $snippet "sig" } " is raised, the signal handler will be run in a freshly-spawned Factor thread concurrently with any already established signal handlers for " { $snippet "sig" } ". Signal constants are available in the " { $vocab-link "unix.ffi" } " vocabulary." }
  11 { $notes "Only certain signals can be handled. See " { $link "unix.signals:allowed-signals" } " for more information. The handler quotation will be run in its own freshly-spawned thread." } ;
  12
  13 HELP: remove-signal-handler
  14 { $values
  15     { "handler" { $quotation ( -- ) } } { "sig" "a signal handler" }
  16 }
  17 { $description "Removes a signal handler for " { $snippet "sig" } ". " { $snippet "handler" } " must be the same quotation object that was passed to " { $link add-signal-handler } ". Signal constants are available in the " { $vocab-link "unix.ffi" } " vocabulary." } ;
  18
  19 { add-signal-handler remove-signal-handler } related-words
  20
  21 ARTICLE: "unix.signals:allowed-signals" "Signals that can be handled by Factor"
  22 "The following signals can be handled by Factor programs:"
  23 { $list "SIGWINCH" "SIGCONT" "SIGURG" "SIGIO" "SIGPROF" "SIGALRM" "SIGVTALRM" "SIGINFO (if available on the host platform)" "SIGUSR1" }
  24 "Synchronous signals such as SIGILL, SIGFPE, SIGBUS, and SIGSEGV are handled by the Factor implementation and reported as exceptions when appropriate. SIGUSR2 is used by Factor internally. SIGINT and SIGQUIT are used by Factor to pause the VM and enter into the low-level debugger (like the " { $link die } " word); they cannot yet be handled reliably by Factor code." ;
  25
  26 ARTICLE: "unix.signals" "Signal handlers"
  27 "The " { $vocab-link "unix.signals" } " vocabulary allows Factor applications to handle a limited subset of Unix signals."
  28 { $subsection "unix.signals:allowed-signals" }
  29 "Factor signal handlers are composable. Adding a signal handler does not replace signal handlers installed by other libraries. Individual signal handlers are added and removed independently with the following words:"
  30 { $subsections add-signal-handler remove-signal-handler }
  31 ;
  32
  33 ABOUT: "unix.signals"