Proposed High Resolution Timer API

Long time since I’ve posted on Planet WebKit:
Here’s a proposed high resolution Timer API for WebKit (and hopefully HTML5). It’s based off of Adobe’s “flash.utils.Timer” API found in ActionScript 3.0.
Timer : EventDispatcher
Properties:

  • currentCount:Number => Total number of times the timer has fired since it started (at 0)
  •  delay:Number => The time, measured in millisecondsseconds, between timer firings. Precision is browser defined, but should be at least 1ms
  • repeatCount:Number => The total number of times the counter is set to run. If the timer is “0”, the timer will run forever or until its stopped.
  • running:Boolean => If the timer is running or not
Methods:
  • start() => Starts the timer if the timer is not running
  • stop() => Stops the timer if the timer is running.
  • reset() => Stops the timer if its running, and resets “currentCount” back to 0.
The timer will implement the browser native event dispatching system (W3C for most, IE proprietary for MSIE), and will fire the following events:
  • timer => Dispatched whenever the timer reaches the interval specified by the “delay” property.
  • timerComplete => Dispatched when the timer’s repeatCount reaches 0.
Please note the timer will be a high resolution timer, with no minimum bound, so there’s no compatibility issues when using setTimeout/setInterval. Plus, the API is simple enough to be implemented in terms of setTimeout/setInterval on browsers that do not implement the proposed.
Please leave feedback on the proposed API.
Some notes:
  • Changes from flash.utils.Timer: delay is measured in seconds instead of milliseconds, since its defined to be a JavaScript number, which has the precision equivalent to a “double” on a standard Intel x86 system.
  • Repeat Count defaults to 0, meaning, go on forever. If you want it to be “one shot”, then set repeat count to 1.
Example Code:
var timer = new Timer();
timer.delay = 0.01;
timer.repeatCount = 1;
// Add Event Listeners
if(timer.addEventListener) timer.addEventListener(“timercomplete”, OnTimerComplete); // W3C
else if (timer.attachEvent) timer.attachEvent(“ontimercomplete”,OnTimerComplete); // MSIE
// Event Lsitener
function OnTimerComplete(e)
{
if(!e) e = window.event; // MSIE
// Do Something
}

6 Replies to “Proposed High Resolution Timer API”

  1. What’s wrong with setInterval/setTimeout?
    MS AJAX specifically didn’t implement a Timer API because they considered setInterval sufficient. And MS AJAX goes out of it’s way to re-implement most JavaScript APIs.
    What do other AJAX libraries have?

  2. Setting repeatCount to 0 for infinite looping seems illogical to me, as 0 can be read as ?Repeat 0 times?. I?d much prefer -1, but that?s just me?
    When does currentCount increment, before/after the event is fired? needs to be defined.
    What happens when delay is set to 0?

  3. @John Drinkwater:
    I copied the API from Adobe’s mostly. I like the -1 suggestion, I might incorporate that into it if other people like it to. For currentCount, which do you prefer? For delay = 0, it will probably be the same as sleep(0), but for JavaScript.
    @RichB:
    It wasn’t written with a high resolution arbitrary precision in mind. Most browsers cap it to 10ms or 15ms. It helps with compatibility by adding a new high precision timer API.

  4. +1 for repeatCount complain.
    It’s unintuitive.
    It should be either repeatCount, with -1 for infinite, 0 for one shot and so one,
    or it should have an other name like triggerCount or fireCount.

Leave a Reply

Your email address will not be published.