From 466d41c34185a090ce3c063101bb991d282a79ef Mon Sep 17 00:00:00 2001
From: Joe Groff <arcata@gmail.com>
Date: Tue, 8 Nov 2011 23:12:10 -0800
Subject: [PATCH] unix.signals: documentation and metadata

---
 basis/unix/signals/authors.txt         |  1 +
 basis/unix/signals/platforms.txt       |  1 +
 basis/unix/signals/signals-docs.factor | 32 ++++++++++++++++++++++++++
 basis/unix/signals/signals.factor      |  4 ++--
 basis/unix/signals/summary.txt         |  1 +
 5 files changed, 37 insertions(+), 2 deletions(-)
 create mode 100644 basis/unix/signals/authors.txt
 create mode 100644 basis/unix/signals/platforms.txt
 create mode 100644 basis/unix/signals/signals-docs.factor
 create mode 100644 basis/unix/signals/summary.txt

diff --git a/basis/unix/signals/authors.txt b/basis/unix/signals/authors.txt
new file mode 100644
index 0000000000..f13c9c1e77
--- /dev/null
+++ b/basis/unix/signals/authors.txt
@@ -0,0 +1 @@
+Joe Groff
diff --git a/basis/unix/signals/platforms.txt b/basis/unix/signals/platforms.txt
new file mode 100644
index 0000000000..509143d863
--- /dev/null
+++ b/basis/unix/signals/platforms.txt
@@ -0,0 +1 @@
+unix
diff --git a/basis/unix/signals/signals-docs.factor b/basis/unix/signals/signals-docs.factor
new file mode 100644
index 0000000000..8c546849f0
--- /dev/null
+++ b/basis/unix/signals/signals-docs.factor
@@ -0,0 +1,32 @@
+! (c)2010 Joe Groff bsd license
+USING: help.markup help.syntax kernel ;
+IN: unix.signals
+
+HELP: add-signal-handler
+{ $values
+    { "handler" { $quotation "( -- )" } } { "sig" "a signal number" }
+}
+{ $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." }
+{ $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." } ;
+
+HELP: remove-signal-handler
+{ $values
+    { "handler" { $quotation "( -- )" } } { "sig" "a signal handler" }
+}
+{ $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." } ;
+
+{ add-signal-handler remove-signal-handler } related-words
+
+ARTICLE: "unix.signals:allowed-signals" "Signals that can be handled by Factor"
+"The following signals can be handled by Factor programs:"
+{ $list "SIGWINCH" "SIGCONT" "SIGURG" "SIGIO" "SIGPROF" "SIGALRM" "SIGVTALRM" "SIGINFO (if available on the host platform)" "SIGUSR1" }
+"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." ;
+
+ARTICLE: "unix.signals" "Signal handlers"
+"The " { $vocab-link "unix.signals" } " vocabulary allows Factor applications to handle a limited subset of Unix signals."
+{ $subsection "unix.signals:allowed-signals" }
+"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:"
+{ $subsections add-signal-handler remove-signal-handler }
+;
+
+ABOUT: "unix.signals"
diff --git a/basis/unix/signals/signals.factor b/basis/unix/signals/signals.factor
index 76e392a32e..9f37eafbe0 100644
--- a/basis/unix/signals/signals.factor
+++ b/basis/unix/signals/signals.factor
@@ -9,11 +9,11 @@ SYMBOL: signal-handlers
 
 signal-handlers [ H{ } ] initialize
 
-PRIVATE>
-
 : dispatch-signal ( sig -- )
     signal-handlers get-global at [ in-thread ] each ;
 
+PRIVATE>
+
 : add-signal-handler ( handler: ( -- ) sig -- )
     signal-handlers get-global push-at ;
 
diff --git a/basis/unix/signals/summary.txt b/basis/unix/signals/summary.txt
new file mode 100644
index 0000000000..cd49cef3a2
--- /dev/null
+++ b/basis/unix/signals/summary.txt
@@ -0,0 +1 @@
+Signal handling