From bbad200a019867c3a85b7502299a7995b8e873d4 Mon Sep 17 00:00:00 2001
From: Slava Pestov <slava@factorcode.org>
Date: Thu, 21 Feb 2008 19:19:21 -0600
Subject: [PATCH] Document and clean up alarms

---
 extra/alarms/alarms-docs.factor | 22 ++++++++++++++++++++++
 extra/alarms/alarms.factor      | 24 ++++++++++++++----------
 2 files changed, 36 insertions(+), 10 deletions(-)
 create mode 100755 extra/alarms/alarms-docs.factor

diff --git a/extra/alarms/alarms-docs.factor b/extra/alarms/alarms-docs.factor
new file mode 100755
index 0000000000..a53515a68d
--- /dev/null
+++ b/extra/alarms/alarms-docs.factor
@@ -0,0 +1,22 @@
+IN: alarms
+USING: help.markup help.syntax calendar ;
+
+HELP: alarm
+{ $class-description "An alarm. Cancel passed to " { $link cancel-alarm } "." } ;
+
+HELP: add-alarm
+{ $values { "time" timestamp } { "frequency" "a " { $link dt } " or " { $link f } } { "quot" quotation } { "alarm" alarm } }
+{ $description "Creates and registers an alarm. If " { $snippet "frequency" } " is " { $link f } ", this will be a one-time alarm, otherwise it will fire with the given frequency. The quotation will be called from the alarm thread." } ;
+
+HELP: cancel-alarm
+{ $values { "alarm" alarm } }
+{ $description "Cancels an alarm." }
+{ $errors "Throws an error if the alarm is not active." } ;
+
+ARTICLE: "alarms" "Alarms"
+"Alarms provide a lightweight way to schedule one-time and recurring tasks without spawning a new thread."
+{ $subsection alarm }
+{ $subsection add-alarm }
+{ $subsection cancel-alarm } ;
+
+ABOUT: "alarms"
diff --git a/extra/alarms/alarms.factor b/extra/alarms/alarms.factor
index 03d16b892d..6a1793ee95 100755
--- a/extra/alarms/alarms.factor
+++ b/extra/alarms/alarms.factor
@@ -6,6 +6,8 @@ IN: alarms
 
 TUPLE: alarm time interval quot entry ;
 
+<PRIVATE
+
 : check-alarm
     pick timestamp? [ "Not a timestamp" throw ] unless
     over dup dt? swap not or [ "Not a dt" throw ] unless
@@ -21,16 +23,6 @@ SYMBOL: alarm-thread
 : notify-alarm-thread ( -- )
     alarm-thread get-global interrupt ;
 
-: add-alarm ( time delay quot -- alarm )
-    <alarm> [
-        dup dup alarm-time alarms get-global heap-push*
-        swap alarm-entry >box
-        notify-alarm-thread
-    ] keep ;
-
-: cancel-alarm ( alarm -- )
-    alarm-entry box> alarms get-global heap-delete ;
-
 : alarm-expired? ( alarm now -- ? )
     >r alarm-time r> <=> 0 <= ;
 
@@ -78,3 +70,15 @@ SYMBOL: alarm-thread
     alarm-thread set-global ;
 
 [ init-alarms ] "alarms" add-init-hook
+
+PRIVATE>
+
+: add-alarm ( time delay quot -- alarm )
+    <alarm> [
+        dup dup alarm-time alarms get-global heap-push*
+        swap alarm-entry >box
+        notify-alarm-thread
+    ] keep ;
+
+: cancel-alarm ( alarm -- )
+    alarm-entry box> alarms get-global heap-delete ;