nsITimer

The nsITimer interface offers a functionality to invoke a function after a specified delay.

Note that the delay is approximate: the timer can be fired before the requested time has elapsed.

nsITimer instances must be initialized by calling one of the initialization methods. You may also re-initialize (using one of the initialization methods) an existing instance to avoid the overhead of destroying and creating a timer. It is not necessary to cancel the timer in that case.

Please add a summary to this article.
Last changed in Gecko 5 (Firefox 5 / Thunderbird 5 / SeaMonkey 2.2)

Inherits from: nsISupports

Implemented by: @mozilla.org/timer;1. To create an instance, use:

var timer = Components.classes["@mozilla.org/timer;1"]
            .createInstance(Components.interfaces.nsITimer);
Users of instances of nsITimer should keep a reference to the timer until it is no longer needed in order to assure the timer is fired.

Method overview

void cancel();
void init(in nsIObserver aObserver, in unsigned long aDelay, in unsigned long aType);
void initWithCallback(in nsITimerCallback aCallback, in unsigned long aDelay, in unsigned long aType);
void initWithFuncCallback(in nsTimerCallbackFunc aCallback, in voidPtr aClosure, in unsigned long aDelay, in unsigned long aType); Native code only!

Attributes

Attribute Type Description
callback nsITimerCallback The nsITimerCallback object passed to initWithCallback(). Read only.
closure voidPtr The opaque pointer pass to initWithFuncCallback(). Read only. Native code only!
delay unsigned long

The timeout delay in millisecond.

Note: Re-setting the delay on a one-shot timer that has already fired doesn't restart the timer. Call one of the init() methods to restart a one-shot timer.
target nsIEventTarget The nsIEventTarget to which the callback is dispatched. This target must be set before calling any of the initialization methods.
type unsigned long Defines the timer type: one shot, repeating slack or repeating precise. Must be one of the constants defined under Constants on this page.

Constants

Constant Value Description
TYPE_ONE_SHOT 0 Type of a timer that fires once only.
TYPE_REPEATING_SLACK 1

After firing, the timer is stopped and not restarted until its callback completes. The timer period will ideally be at least the time between when processing for last firing the callback completes and when the next firing occurs, but note that this is not guaranteed: the timer can fire at any time.

This is the preferable repeating type for most situations.
TYPE_REPEATING_PRECISE 2

TYPE_REPEATING_PRECISE is just a synonym for TYPE_REPEATING_PRECISE_CAN_SKIP. They used to be distinct, but the old TYPE_REPEATING_PRECISE kind was similar to TYPE_REPEATING_PRECISE_CAN_SKIP while also being less useful. So the distinction was removed.
TYPE_REPEATING_PRECISE_CAN_SKIP 3 This repeating timer aims to have constant period between firings. The processing time for each timer callback should not influence the timer period. However this timer type guarantees that it will not queue up new events to fire the callback until the previous callback event finishes firing. If the callback takes a long time, then the next callback will be scheduled immediately afterward, but only once, unlike TYPE_REPEATING_PRECISE. If you want a non-slack timer, you probably want this one.

Methods

cancel()

Cancels the timer. This method works on all types, not just on repeating timers -- you might want to cancel a TYPE_ONE_SHOT timer, and even reuse it by re-initializing it (to avoid object destruction and creation costs by conserving one timer instance).

void cancel();
Parameters

None.

init()

Initialize a timer that will fire after the specified delay. A user must keep a reference to this timer till it is no longer needed or has been cancelled.

void init(
  in nsIObserver aObserver,
  in unsigned long aDelay,
  in unsigned long aType
);
Parameters
aObserver
A callback Object, that is capable listening to timer events. If the timer fires, the observer will be notified via the nsIObserver Interface. The subject is set to the nsITimer Object which fired, the topic is equal to "timer-callback" and data is always set to null.
aDelay
Timeout delay in milliseconds.
aType
Defines the timer type: one shot, repeating slack or repeating precise. Must be one of the constants defined under Constants on this page.

initWithCallback()

Initialize a timer to fire after the given millisecond interval. This version takes a function to call.

void initWithCallback(
  in nsITimerCallback aCallback,
  in unsigned long aDelay,
  in unsigned long aType
);
Parameters
aCallback
An nsITimerCallback interface to call when timer expires.
aDelay
Timeout delay in milliseconds.
aType
Defines the timer type: one shot, repeating slack or repeating precise. Must be one of the constants defined under Constants on this page.

Native code only!

initWithFuncCallback

Initialize a timer to fire after the given millisecond interval. This version takes a function to call and a closure to pass to that function.

void initWithFuncCallback(
  in nsTimerCallbackFunc aCallback,
  in voidPtr aClosure,
  in unsigned long aDelay,
  in unsigned long aType
);
Parameters
aCallback
A nsTimerCallbackFunc interface compatible function to call when timer fires.
aClosure
An opaque pointer to pass to that function.
aDelay
Timeout delay in milliseconds.
aType
Defines the timer type: one shot, repeating slack or repeating precise. Must be one of the constants defined under Constants on this page.

Remarks

TYPE_REPEATING_SLACK timer is the preferable repeating timer type for most situations

Example

Using initWithCallback:

// we need an nsITimerCallback compatible...
// ... interface for the callbacks.
var event = {
  notify: function(timer) {
    alert("Fire!");
  }
}

// Now it is time to create the timer...
var timer = Components.classes["@mozilla.org/timer;1"].createInstance(Components.interfaces.nsITimer);

// ... and to initialize it, we want to call event.notify() ...
// ... one time after exactly ten seconds.
timer.initWithCallback(event,10000, Components.interfaces.nsITimer.TYPE_ONE_SHOT);

Using init, we fire an event every 10 seconds:

var event = {
  observe: function(subject, topic, data) {
    dump("hello world\n");
  }
}
var timer = Components.classes["@mozilla.org/timer;1"].createInstance(Components.interfaces.nsITimer);
const TYPE_REPEATING_PRECISE_CAN_SKIP = Components.interfaces.nsITimer.TYPE_REPEATING_PRECISE_CAN_SKIP;

timer.init(event, 10*1000, TYPE_REPEATING_PRECISE_CAN_SKIP);

See also