1  #lang scribble/doc
 2  @(require "common.rkt")
 3  
 4  @defclass/title[timer% object% ()]{
 5  
 6  A @racket[timer%] object encapsulates an event-based alarm. To use a
 7   timer, either instantiate it with a @racket[timer-callback] thunk to
 8   perform the alarm-based action, or derive a new class and override
 9   the @method[timer% notify] method to perform the alarm-based
10   action. Start a timer with @method[timer% start] and stop it with
11   @method[timer% stop]. Supplying an initial @racket[interval] (in
12   milliseconds) when creating a timer also starts the timer.
13  
14  Timers have a relatively high priority in the event queue. Thus, if
15   the timer delay is set low enough, repeated notification for a timer
16   can preempt user activities (which might be directed at stopping the
17   timer). For timers with relatively short delays, call @racket[yield]
18   within the @method[timer% notify] procedure to allow guaranteed event
19   processing.
20  
21  See @secref["eventspaceinfo"] for more information about event
22   priorities.
23  
24  
25  @defconstructor[([notify-callback (-> any) void]
26                   [interval (or/c (integer-in 0 1000000000) #f) #f]
27                   [just-once? any/c #f])]{
28  
29  The @racket[notify-callback] thunk is called by the default
30  @method[timer% notify] method when the timer expires.
31  
32  If @racket[interval] is @racket[#f] (the default), the timer is not
33   started; in that case, @method[timer% start] must be called
34   explicitly. If @racket[interval] is a number (in milliseconds), then
35   @method[timer% start] is called with @racket[interval] and
36   @racket[just-once?].
37  
38  }
39  
40  
41  @defmethod[(interval)
42             (integer-in 0 1000000000)]{
43  
44  Returns the number of milliseconds between each timer expiration (when
45   the timer is running).
46  
47  }
48  
49  @defmethod[(notify)
50             void?]{
51  
52  @methspec{
53  
54  Called (on an event boundary) when the timer's alarm expires.
55  
56  }
57  @methimpl{
58  
59  Calls the @racket[notify-callback] procedure that was provided when the
60   object was created.
61  
62  }}
63  
64  @defmethod[(start [msec (integer-in 0 1000000000)]
65                    [just-once? any/c #f])
66             void?]{
67  
68  Starts (or restarts) the timer. If the timer is already running, its alarm time is not changed.
69  
70  The timer's alarm expires after @racket[msec] milliseconds, at which point
71  @method[timer% notify] is called (on an event boundary). If
72  @racket[just-once?] is true, the timer calls its @method[timer% notify]
73  callback when the alarm expires and the timer is stopped. If
74  @racket[just-once?] is @racket[#f], the timer is re-started when the @method[timer% notify]
75  callback returns; it stops only once @method[timer% stop] is called explicitly.
76  
77  }
78  
79  @defmethod[(stop)
80             void?]{
81  
82  Stops the timer. A stopped timer never calls
83  @method[timer% notify]. If the timer has expired but the call to
84  @method[timer% notify] has not yet been dispatched, the call is removed from the event queue.
85  
86  }}
87