1 Introduction
2 What to require
2.1 Raw timeout events
timer-evt
2.2 Timers and timer managers
make-timer-manager
add-absolute-timer!
add-relative-timer!
fire-single-timer-evt
fire-single-timer
fire-timers-evt
fire-timers
cancel-timer!
timer-manager
pending-timer
timer-manager-idle?
5.3.3.5

racket-timers

Tony Garnock-Jones <tonygarnockjones@gmail.com>

    1 Introduction

    2 What to require

      2.1 Raw timeout events

      2.2 Timers and timer managers

If you find that this library lacks some feature you need, or you have a suggestion for improving it, please don’t hesitate to get in touch with me!

1 Introduction

This library provides utilities for managing a heap of timeouts when programming in an event-driven style with sync.

2 What to require

All the functionality below can be accessed with a single require:

 (require (planet tonyg/timers:1:=0))

2.1 Raw timeout events

procedure

(timer-evt msecs)  evt?

  msecs : nonnegative-number?
Just like alarm-evt, but yields as its value the value of current-inexact-milliseconds at (or shortly after) the time the event fires. This contrasts with alarm-evt in that alarm-evt yields no useful value.

2.2 Timers and timer managers

Construct a fresh timer-manager with an empty internal queue of timers.

procedure

(add-absolute-timer! tm deadline handler)  pending-timer?

  tm : timer-manager?
  deadline : nonnegative-number?
  handler : (-> any?)
Registers a new timer with the given timer-manager, that will expire at the given deadline (N.B.: milliseconds! Use current-inexact-milliseconds), calling the given handler callback. The timer descriptor is returned (for potential later use with cancel-timer!).

procedure

(add-relative-timer! tm delta-msec handler)  pending-timer?

  tm : timer-manager?
  delta-msec : number?
  handler : (-> any?)
As add-absolute-timer!, but instead of expecting an absolute expiry deadline, takes an expiry time expressed as a number of milliseconds relative to the value of current-inexact-milliseconds at the time of the call.

procedure

(fire-single-timer-evt tm    
  k-fired    
  k-not-fired)  evt?
  tm : timer-manager?
  k-fired : (->* () #:rest any? any?)
  k-not-fired : (-> any?)
Returns an event for use with sync that is ready to fire only when current-inexact-milliseconds is past the earliest event in the queue managed by tm. If selected, tail-calls fire-single-timer (with the same arguments as it was given itself) to produce the values to yield from the event.

procedure

(fire-single-timer tm k-fired k-not-fired)  any?

  tm : timer-manager?
  k-fired : (->* () #:rest any? any?)
  k-not-fired : (-> any?)
Checks the queue of timers in tm. If none are ready to fire, tail-calls k-not-fired. Otherwise, selects the first ready timer in the queue. If it has been cancelled, tail-calls k-not-fired. Otherwise, tail-calls k-fired with the values returned from its handler callback.

procedure

(fire-timers-evt tm)  evt?

  tm : timer-manager?
Returns an event for use with sync that is ready to fire only when current-inexact-milliseconds is past the earliest event in the queue managed by tm. If selected, tail-calls fire-timers, yielding (void).

procedure

(fire-timers tm)  void?

  tm : timer-manager?
Checks the queue of timers in tm, calling handlers for expired timers (ignoring the results from the handlers) and removing them from the queue until no further expired timers remain to be processed.

procedure

(cancel-timer! t)  void?

  t : pending-timer?
Cancels an outstanding timer. If the timer’s handler has not been called at the time cancel-timer! is called, then the timer’s handler will not ever be called by any of the functions or events provided by this module.

struct

(struct timer-manager (heap)
  #:extra-constructor-name make-timer-manager
  #:transparent)
  heap : heap?
Represents a collection of pending timers. Updated by in-place mutation. Note that no access to the raw constructor of this struct is provided.

struct

(struct pending-timer (deadline handler cancelled?)
  #:extra-constructor-name make-pending-timer
  #:transparent)
  deadline : nonnegative-number?
  handler : (-> any?)
  cancelled? : boolean?
A record of a timer registered with some timer manager.

pending-timer-deadline is the value of current-inexact-milliseconds after which the event will fire (when the pending timer’s timer-manager is checked for expired events).

pending-timer-handler is the timer callback. It will be called with no arguments, and may yield any number of values. The values are ignored if either fire-timers or fire-timers-evt is used to trigger the firing of the timer, and are used if either fire-single-timer or fire-single-timer-evt fire the timer.

pending-timer-cancelled? indicates whether this timer has been cancelled. A cancelled timer’s callback will never be called; it is as if it were never registered.

procedure

(timer-manager-idle? tm)  boolean?

  tm : timer-manager?
Returns #t if and only if there are no queued timers on the given timer manager; otherwise, returns #f. Note that even a single cancelled timer that has not yet been cleared (via one of the event-firing routines above) will cause this procedure to return #t.