TIMER - an event scheduler for SBCL

Abstract

TIMER is an SBCL interface for scheduling events to occur at specified times. It allows relative and absolute scheduling and event repetition. It is loosely based on the LispWorks timer scheduling interface.

It is released in the public domain by its author, Zachary Beane <xach@xach.com>.

Contents

1. Download and Installation
2. Timers
3. The TIMER Dictionary
   1. enable-timers
   2. timers-enabled-p
   3. make-timer
   4. timer-name
   5. schedule-timer
   6. schedule-timer-relative
   7. unschedule-timer
   8. timer-expired-p
4. Examples
5. Differences from LispWorks

Download and Installation

The latest version of this package should always be available from http://www.xach.com/lisp/timer/.

The easiest way to install TIMER is via asdf-install. From inside a running SBCL session:

* (require 'asdf)
* (require 'asdf-install)
* (asdf-install:install 'timer)

If you download this package as a source tarball, unpack it anywhere you like, then symlink the timer.asd file into a directory in asdf:*central-registry*, such as ~/.sbcl/systems/

After TIMER is installed, you can bring it into your SBCL session with "(require 'timer)".

Timers

A timer is an object that contains a function. The timer may be scheduled to run at an absolute or relative time. When the time arrives, the timer expires, and its associated function is invoked with no arguments.

A timer may also be scheduled to have a repeat time. When set, this value is used when the timer expires as a relative time to reschedule the timer.

Timers may be named at creation time. This option affects how the object is displayed with PRINT-OBJECT.

The TIMER Dictionary

TIMER exports the following symbols:

[Function]
enable-timers => <no values>

This function initializes and starts the timer scheduling system. It must be called before using timer scheduling functions.

[Function]
timers-enabled-p => result

This function returns true if the timer scheduling system is currently running, NIL otherwise.

[Function]
make-timer function &key name (thread t) => timer

This function will create and return a timer object. If thread is non-NIL, function will run in a new thread when the timer expires.

Note: If a new thread is not created, a timer function that has a significant run time or raises an error can disrupt the timer scheduling system.

[Function]
timer-name timer

Return the name of timer that was specified at creation time, or NIL if the timer is unnamed.

[Function]
schedule-timer timer absolute-time &optional repeat-time => <no values>

This function will schedule timer to expire at absolute-time. absolute-time is a time as returned by get-universal-time, but it may be a real (that is, include partial seconds). If a positive real number repeat-time is provided, the timer will be rescheduled after its first expiration to expire every repeat-time seconds.

absolute-time and repeat-time must not be negative.

If timer has already been scheduled by a call to schedule-timer or schedule-timer-relative and has not yet expired, it is unscheduled and rescheduled with the new expiration and repeat times.

The consequences are unspecified if absolute-time is a non-negative number representing a date in the past.

[Function]
schedule-timer-relative timer relative-time &optional repeat-time => <no values>

This function is identical to schedule-timer, except the timer is scheduled to expire at the current time plus the non-negative real number relative-time.

[Function]
unschedule-timer timer => result

This function unschedules and returns true if timer is scheduled, and NIL if timer is not scheduled.

[Function]
timer-expired-p timer &optional relative-time => result

This function returns true if timer has not been scheduled or if it has expired, or NIL otherwise.

If relative-time is provided, this function returns true if timer has not been scheduled or if it will expire within relative-time seconds, or NIL otherwise.

Examples

CL-USER(3): (timer:enable-timers)

12374
CL-USER(4): (defun show-time () (format t "~%The time is now ~D~%" (get-universal-time)))

SHOW-TIME
CL-USER(5): (defvar *timer* (timer:make-timer #'show-time))

*TIMER*
CL-USER(7): (progn (show-time) (timer:schedule-timer-relative *timer* 10 5))

The time is now 3277307432
CL-USER(8): 
The time is now 3277307442

The time is now 3277307447

The time is now 3277307452

CL-USER(8): 
The time is now 3277307457

The time is now 3277307462

CL-USER(9): (timer:unschedule-timer *timer*)
#<TIMER (unnamed) {96410E1}>

Differences from Lispworks

This interface is inspired by the LispWorks timer interface, with a few differences:

• LispWorks timers are initialized with a symbol and a list of arguments. When the timer expires, the symbol is applied as a function to the arguments. TIMER uses a single function object which is invoked with no arguments.
• The absolute value given to LispWorks' schedule-timer is relative to the start of the program. TIMER uses a value based on get-universal-time.
• make-named-timer is eliminated; the name keyword argument to make-timer is available instead.
• TIMER functions, by default, run in a new dedicated thread. LispWorks timer functions run in the system idle thread. The thread keyword argument to make-timer is available to cause timer functions to run in the timer scheduler thread.