PDG engine v0.9.5
 All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | Related Functions | List of all members
TimerManager Class Reference

manages timers that can fire at a particular time, or repeatedly at an interval More...

Inheritance diagram for TimerManager:
Inheritance graph
[legend]
Collaboration diagram for TimerManager:
Collaboration graph
[legend]

Public Member Functions

 cancelAllTimers ()
 stop and remove all timers
 
 cancelTimer (int id)
 stop and remove a timer
 
 delayTimer (int id, uint delay)
 delay the normal firing by a given amount
 
 delayTimerUntil (int id, uint msTime)
 postpone the normal firing of a timer until a specific time
 
number getMilliseconds ()
 get the current time in milliseconds
 
number getWhenTimerFiresNext (int id)
 get the millisecond time when the timer will fire
 
boolean isPaused ()
 check if the TimerManager is paused
 
boolean isTimerPaused (int id)
 check if a timer is paused
 
IEventHandler onInterval (function func, int interval)
 setup handler to be called at a regular interval
 
IEventHandler onTimeout (function func, int delay)
 setup handler to be called once after a delay
 
 pause ()
 pause all timers indefinitely
 
 pauseTimer (int id)
 pause a timer indefinitely
 
 startTimer (int id, uint delay, boolean oneShot=true)
 create and start a new timer
 
 unpause ()
 resume all paused timers
 
 unpauseTimer (int id)
 resume a specific timer
 
- Public Member Functions inherited from EventEmitter
 addHandler (IEventHandler inHandler, int inEventType=all_events)
 add a new handler for some event type, or for all events if no type specified.
 
 blockEvent (int inEventType)
 temporarily ignore all events of a particular type.
 
 clear ()
 remove all handlers
 
 removeHandler (IEventHandler inHandler, int inEventType=all_events)
 remove a handler for some event type, or for all events (see note) if no type specified.
 
 unblockEvent (int inEventType)
 stop ignoring events of a particular type
 

Related Functions

(Note that these are not member functions.)

 getTimerManager
 get the singleton instance of the TimerManager used by the pdg framework
 
 tm
 the singleton instance of the TimerManager
 

Detailed Description

manages timers that can fire at a particular time, or repeatedly at an interval

Precondition
API Stability: 3 - Stable. The API has proven satisfactory, but cleanup in the underlying code may cause minor changes. Backwards-compatibility is guaranteed.

The singleton instance of the TimerManager can be accessed at pdg.tm, for example:

pdg.tm.onTimeout(function(evt) {
console.log(evt);
}, 1000);

All TimerManager functions are safe to perform while a timer is firing. Functions that alter a timer can be safely used even from within the handler of the timer being changed (ie: while the target timer is in the process of firing)

The TimerManager is an EventEmitter, and will generate pdg.eventType_Timer events:

{ 
    emitter: {},            // the emitter that generated this event
    eventType: 3,           // the event type (pdg.eventType_Timer)
    id: 117440512,          // the timer id (auto-generated up by onTimeout())
    millisec: 1025448321,   // the millisecond time when the timer fired
    msElapsed: 18896        // the time elapsed since the timer was started or last fired
} 

Member Function Documentation

cancelAllTimers ( )

stop and remove all timers

This is the same as calling cancelTimer() on every timer in the TimerManager

See Also
cancelTimer()
cancelTimer ( int  id)

stop and remove a timer

Parameters
idthe id number of the timer to stop
See Also
cancelAllTimers()
delayTimer ( int  id,
uint  delay 
)

delay the normal firing by a given amount

Delay a timer's normal firing by the number of milliseconds passed in. If the timer is a repeating timer, this will only delay the next firing time; the interval will return to normal after the next firing.

If the timer is paused, this adds the delay but does not unpause the timer.

Parameters
idthe id number of the timer to delay
delaythe number of milliseconds to delay
See Also
pauseTimer()
delayTimerUntil()
delayTimerUntil ( int  id,
uint  msTime 
)

postpone the normal firing of a timer until a specific time

Sets the specific time in milliseconds (as returned by getMilliseconds() ) at which the timer should fire. If the timer is a repeating timer, this will only postpone the next firing time; it will fire at it's normal interval from then on.

If the timer is paused, this un-pauses the timer so it can fire at the specified time.

Parameters
idthe id number of the timer to postpone
msTimethe millisecond time when it should fire
Note
Millisecond accuracy is attempted but not guaranteed. An additional delay of several milliseconds is common.
See Also
delayTimer()
pauseTimer()
getMilliseconds ( )

get the current time in milliseconds

Gets the current millisecond time, from an arbitrary base time prior to the application start.

Note
Many events and callbacks pass this value (or a ms delta since the last call), so you can often avoid repeated calls to getMilliseconds() by using the value or millisecond delta passed in.
getWhenTimerFiresNext ( int  id)

get the millisecond time when the timer will fire

Gets the millisecond time when the timer is set to fire next. If the timer is paused, or is a one-shot timer that is current firing, then it will return pdg.timer_Never.

Returns
the millisecond time the timer will fire
isPaused ( )

check if the TimerManager is paused

Returns
true if the TimerManager is paused, false if not
See Also
pause()
isTimerPaused()
isTimerPaused ( int  id)

check if a timer is paused

Parameters
idthe id number of the timer to check
Returns
true if the timer is paused, false if not
See Also
pause()
pauseTimer()
onInterval ( function  func,
int  interval 
)

setup handler to be called at a regular interval

This creates a handler from your function and automatically assigns a timer id. You can call cancel() on the handler object returned to remove the timer and cleanup the handler. The timer field of the handler object contains the timer's id number for use in other TimerManager calls.

var t = pdg.tm.onInterval( function(evt) {
console.log('fired ');
}, 1000);
pdg.tm.delayTimer(t.timer, 500); // wait an extra 1/2 second to fire
t.cancel(); // removes the timer and the handler for it
Parameters
functhe handler function to call
intervalthe number of milliseconds between calls
Returns
an IEventHandler object with a cancel() method and a timer value
See Also
onTimeout()
startTimer()
onTimeout ( function  func,
int  delay 
)

setup handler to be called once after a delay

This creates a handler from your function and automatically assigns a timer id. You can call cancel() on the handler object returned to remove the timer and cleanup the handler. The timer field of the handler object contains the timer's id number for use in other TimerManager calls.

Parameters
functhe handler function to call
delaythe number of milliseconds to wait
Returns
an IEventHandler object with a cancel() method and a timer value
See Also
onInterval()
startTimer()
pause ( )

pause all timers indefinitely

Pause all timers in the TimerManager until unpause() or unpauseTimer() are called. When unpaused they continue their behavior as if no time had passed between the pause() and unpause() calls.

Note
timers added after pause() is called are not paused and will run as normal.
See Also
unpause()
unpauseTimer()
isPaused()
pauseTimer ( int  id)

pause a timer indefinitely

Pause the specified timer until unpause() or unpauseTimer() are called. When unpaused, the timer will continue as if no time had passed between the pauseTimer() and unpauseTimer() calls.

See Also
unpauseTimer()
unpause()
isTimerPaused()
startTimer ( int  id,
uint  delay,
boolean  oneShot = true 
)

create and start a new timer

Create a new timer and start it running. If the timer is a one-shot timer, it will wait delay ms then fire off a pdg.eventType_Timer event. If it is a repeating timer it will fire repeatedly at the delay ms interval until canceled by a call to cancelTimer().

If there is already a timer with the given id, it will be removed and the new timer will replace it.

You must install an event handler to get the timer events, either in the TimerManager itself, or in the EventManager. For that reason it is often more convenient to use onTimeout() or onInterval(), since they set up the event handler for you.

Parameters
idthe id number of the timer to start or reset
delaythe time before the timer should fire (or the firing interval if this is a repeating timer)
oneShottrue mean
Note
This is a safe to do even if from within the handler of a timer with the same id
See Also
cancelTimer()
onTimeout()
onInterval()
unpause ( )

resume all paused timers

This is the same as calling unpauseTimer() for every timer in the TimerManager.

See Also
unpauseTimer()
pause()
unpauseTimer ( int  id)

resume a specific timer

Parameters
idthe id number of the timer to be resumed
See Also
pauseTimer()
unpause()

Friends And Related Function Documentation

getTimerManager
related

get the singleton instance of the TimerManager used by the pdg framework

Returns
TimerManager singleton object

User Comments