Cancels a timer previously established by imp.wakeup()
Device (from impOS™ 27) + Agent
|timerIdentifier||A timer object reference (device/agent) or name (agent only)||
An identifier for a timer established by imp.wakeup()
To use this method, you must already have a reference to the timer you wish to cancel. Creating a new timer with imp.wakeup() returns a reference to the new timer. Store this reference in a variable and you can later pass the reference to imp.cancelwakeup() if you need to.
If the timer has not yet fired, once cancelled it never will. Cancelling a timer that has already fired has no effect. Cancelling a timer, whether it has fired or not, does not null the reference.
The method can be applied to timers established by either a device or an agent, but the method doesn’t allow an agent to cancel a timer established by a device, or vice versa.
When establishing timers within agent code (but not device code), you may specify an identifier for the timer created. You may use this name as an alternative identifier for the timer you wish to cancel when calling imp.cancelwakeup(). An exception will be thrown if the identifier you use identifies an inactive (cancelled or not yet established) timer.
The following example demonstrates the specific usage of imp.cancelwakeup() in agent code. First we establish a timer using a string identifier (
"wakeup_timer"), which we subsequently pass into imp.cancelwakeup() to cancel it. The second imp.wakeup() call uses the original (and still available) way of identifying a timer: by storing the reference returned by imp.wakeup() — which we then use to cancel that timer!
The following example uses imp.cancelwakeup() to suspend a regular timer-based loop in response to the arrival of new data, in this case in index value indicating a specific color in an array of RGB colors.