imp.wakeup(interval, callback, name)

Description

This method sets a timer to trigger the imp or the agent and call the specified function after the specified interval. The method does not block: the imp may enter a sleep state during the interim period or continue running code. When Squirrel runs out of device code to execute, it will automatically enter shallow sleep.

While this method is available to both imps and agents, it does not work between them: an agent, for example, can’t set a timer to call a function on the imp, or vice versa. However, the function called can of course include a device.send() or agent.send(), as appropriate, which in turn triggers the desired function.

The method returns a reference to the timer object it has instantiated. This allows you to store references to the timers you have created. Any timer can be subsequently passed to imp.cancelwakeup() to disable and delete the timer. When the timer fires, the reference will not be nulled, even though the timer no longer exists. imp.wakeup() will return null if the device is unable to create a new timer for any reason.

The timer has only centisecond (0.01s) resolution. The code

imp.wakeup(0.0, functionToCall);

acts like

imp.onidle(functionToCall);

while

imp.wakeup(0.000001, functionToCall);

acts like

imp.wakeup(0.01, functionToCall);

The imp supports timer durations of up to 2³⁰ centiseconds — ie. 124 days.

If the imp is handling some other event at the moment the timer fires, that other code is not interrupted. Instead, the second timer event is queued and is executed when all previously queued event handlers have returned, ie. when the imp would otherwise be idle. As such, the called function may run after a greater duration than that specified in the imp.wakeup() call.

For more information on lower-power suspend modes, refer to server.sleepfor() and server.sleepuntil().

Agents are able to maintain a queue of no more than 50 imp.wakeup() timers; devices are limited only by the amount of free memory into which the timer queue can grow. Having too many timers in play — for instance, creating multiple timers in a tight loop — is an easy way to fill the device’s memory, causing further memory allocation operations of any type to fail. Agents will throw an exception as soon as more than 50 timers are queued. It is therefore strongly recommended that you keep track of the timers you establish.

Named Timers

The optional parameter, name, allows you to specify an identifier for a timer. If you provide a name, any timers which share that name will automatically be cancelled.

Note The name parameter is only available in agent code.

Naming timers can be used to prevent your code from inadvertently spawning multiple loops in cases where you (correctly) use a timer to drive a loop:

function poll() {
    imp.wakeup(1.0, poll);
}

poll();    // Initiates a loop; loop count = 1
poll();    // Initiates a loop; loop count = 2

The above code causes poll() to be called every second. Adding a second call to the function after the first results in two loops, which may not be intended and increases the likelihood that you are more likely to hit the agent’s 50-timer limit (see above) or run out of device memory. Adding a name to the imp.wakeup() call will prevent this because any subsequent calls to poll() will cause the existing timer (and thus the loop) to be cancelled:

function poll() {
    // Name the timer to prevent extra loops being spawned
    imp.wakeup(1.0, poll, "poll.timer");
}

poll();    // Initiates a loop; loop count = 1
poll();    // Cancels the first loop, initiates a loop; loop count = 1

• For more information on the uses of imp.wakeup(), please see the guide How to Write Imp Loop Structures