Dongle/Timer API

Dongle provides a mechanism for registering timers and triggering functions when they expire. The API is designed to be simple to use and the implementation is efficient enough to scale to thousands of scheduled timers.

This API was introduced with Dongle-1.1

DongleObject:ScheduleTimer(name, func, delay, ...)
Schedule a timer to expire in delay seconds at which point it will call the callback func. name is an identifier for this timer.

Arguments

 * name (string) - The name of the timer to be scheduled. You can use this name to check if this timer's status and/or cancel it. As a constant, this is typically in "ALL_CAPS".  To ensure no collisions, it is good practice to name your timers after your addon, such as "DONGLE_PROFILE_CREATED".
 * func (function) - A function to be called when the timer expires.
 * delay (number) - The number of seconds it takes for this timer to expire.
 * ... - Any additional arguments to pass to the callback.

Callback Signature

 * func(name, ...)

Behavior

 * The name of the timer is passed to the callback as a first argument. If specified the user arguments will be passed after that.
 * Each dongle object may only schedule one timer per unique name. If you try to schedule a timer with the same name a second time, the old schedule will be overwritten.

DongleObject:ScheduleRepeatingTimer(name, func, delay, ...)
Schedule a repeating timer that expires every delay seconds.

Arguments

 * name (string) - The name of the timer to schedule. You can use this name to check if this timer's status and/or cancel it. As a constant, this is typically in "ALL_CAPS".  To ensure no collisions, it is good practice to name your timers after your addon, such as "DONGLE_PROFILE_CREATED".
 * func (function) - A function to be called when the timer expires.
 * delay (number) - The number of seconds it takes for this timer to expire.
 * ... - Any additional arguments to pass to the callback.

Callback Signature

 * func(name, ...)

Behavior

 * The name of the timer is passed to the callback as a first argument. If specified the user arguments will be passed after that.
 * Each dongle object may only schedule one timer per unique name. If you try to schedule a timer with the same name, the old schedule will be overwritten.

DongleObject:CancelTimer(name)
Cancels the timer scheduled with name.

Arguments

 * name (string) - The name of the timer to cancel.

DongleObject:IsTimerScheduled(name)
Returns if the timer with the name specified is scheduled or not and also returns the time remaining for it to expire.

Arguments

 * name (string) - The name of the timer to query.

Returns
false - if the timer is not scheduled. true, seconds (number) - if the timer is scheduled. seconds is the number of seconds required for the timer to expire.