basis/timers/timers-docs.factor

   1 USING: help.markup help.syntax calendar quotations system ;\r
   2 IN: timers\r
   3 \r
   4 HELP: timer\r
   5 { $class-description "A timer. Can be passed to " { $link stop-timer } "." } ;\r
   6 \r
   7 HELP: start-timer\r
   8 { $values { "timer" timer } }\r
   9 { $description "Starts a timer." } ;\r
  10 \r
  11 HELP: restart-timer\r
  12 { $values { "timer" timer } }\r
  13 { $description "Starts or restarts a timer. Restarting a timer causes the a sleep of initial delay nanoseconds before looping. An timer's parameters may be modified and restarted with this word." } ;\r
  14 \r
  15 HELP: stop-timer\r
  16 { $values { "timer" timer } }\r
  17 { $description "Prevents a timer from calling its quotation again. Has no effect on timers that are not currently running." } ;\r
  18 \r
  19 HELP: every\r
  20 { $values\r
  21      { "quot" quotation } { "interval-duration" duration }\r
  22      { "timer" timer } }\r
  23 { $description "Creates a timer that calls the quotation repeatedly, using " { $snippet "duration" } " as the frequency. The first call of " { $snippet "quot" } " will happen immediately. If the quotation throws an exception, the timer will stop." }\r
  24 { $examples\r
  25     { $code\r
  26         "USING: timers io calendar ;"\r
  27         """[ "Hi Buddy." print flush ] 10 seconds every drop"""\r
  28     }\r
  29 } ;\r
  30 \r
  31 HELP: later\r
  32 { $values { "quot" quotation } { "delay-duration" duration } { "timer" timer } }\r
  33 { $description "Sleeps for " { $snippet "duration" } " and then calls a " { $snippet "quot" } ". The user may cancel the timer before " { $snippet "quot" } " runs. This timer is not repeated." }\r
  34 { $examples\r
  35     { $code\r
  36         "USING: timers io calendar ;"\r
  37         """[ "Break's over!" print flush ] 15 minutes later drop"""\r
  38     }\r
  39 } ;\r
  40 \r
  41 HELP: delayed-every\r
  42 { $values\r
  43      { "quot" quotation } { "duration" duration }\r
  44      { "timer" timer } }\r
  45 { $description "Creates a timer that calls " { $snippet "quot" } " repeatedly, waiting " { $snippet "duration" } " before calling " { $snippet "quot" } " the first time and then waiting " { $snippet "duration" } " between further calls. If the quotation throws an exception, the timer will stop." }\r
  46 { $examples\r
  47     { $code\r
  48         "USING: timers io calendar ;"\r
  49         """[ "Hi Buddy." print flush ] 10 seconds every drop"""\r
  50     }\r
  51 } ;\r
  52 \r
  53 ARTICLE: "timers" "Timers"\r
  54 "The " { $vocab-link "timers" } " vocabulary provides a lightweight way to schedule one-time and recurring tasks. Timers run in a single green thread per timer and consist of a quotation, a delay duration, and an interval duration. After starting a timer, the timer thread sleeps for the delay duration and calls the quotation. Then it waits out the interval duration and calls the quotation again until something stops the timer. If a recurring timer's quotation would be scheduled to run again before the previous quotation has finished processing, the timer will be run again immediately afterwards. This may result in the timer falling behind indefinitely, in which case the it will run as often as possible while still allowing other green threads to run. Recurring timers that execute 'on time' or 'catch up' will always be scheduled for an exact multiple of the interval from the original starting time to prevent the timer from drifting over time. Timers use " { $link nano-count } " as the timing primitive, so they will continue to work across system clock changes." $nl\r
  55 "The timer class:"\r
  56 { $subsections timer }\r
  57 "Create a timer before starting it:"\r
  58 { $subsections <timer> }\r
  59 "Starting a timer:"\r
  60 { $subsections start-timer restart-timer }\r
  61 "Stopping a timer:"\r
  62 { $subsections stop-timer }\r
  63 \r
  64 "A recurring timer without an initial delay:"\r
  65 { $subsections every }\r
  66 "A one-time timer with an initial delay:"\r
  67 { $subsections later }\r
  68 "A recurring timer with an initial delay:"\r
  69 { $subsections delayed-every } ;\r
  70 \r
  71 ABOUT: "timers"\r