Module timer
Schedule code to run at some point in the future or in intervals.
Most of the functions here use the same name and semantics of the corresponding JavaScript functions. The resemblance goes much deeper: JavaScript in a browser and MC are both non-threaded applications and they use exactly the same model to implement this feature: it’s the event loop which fires the timers. So if you're already familiar with timers in JavaScript, consider yourself familiar with timers in MC as well.
Functions
clear_timeout(fn) | Cancels a pending timeout. |
debounce(fn, delay) | A variation of set_timeout. |
now() | Returns the current “timestamp”. |
set_interval(fn, delay) | Schedules code to run repeatedly. |
set_timeout(fn, delay) | Schedules code to run once in the future. |
unlock() | Enables “reentrancy”. |
Functions
- clear_timeout(fn)
- Cancels a pending timeout.
- debounce(fn, delay)
-
A variation of set_timeout.
See explanation for debounce on the internet.
In GUI applications it’s common to perform some action as the user types something. For example, you may want to update search results while the user types the query. A naive approach would be to do (assuming an Input widget):
query.on_change = function() do_search() end
However, this might make the interface sluggish. A better approach is:
query.on_change = timer.debounce(function() do_search() end, 500)
See another example at <<select-file>>.
- now()
-
Returns the current “timestamp”.
This function is similar to Unix’s time(2) function, except that our timestamp is of higher resolution (milliseconds instead of seconds) and the Epoch is the time the program started (the time this function was first called, to be exact).
This function is mainly useful for building peripheral utilities, like benchmarking code.
- set_interval(fn, delay)
-
Schedules code to run repeatedly.
Example:
local itrvl = timer.set_interval(function() counter.text = counter.text + 1 end, 100)
The function returns an object having the following methods:
- stop() – cancels the ticking.
- resume() – restarts the ticking.
- stopped – a read-only property telling us whether it’s ticking.
- toggle() – calls either stop() or resume().
See a complete example in ui_setinterval.mcs.
Parameters:
- fn The function to schedule.
- delay How many milliseconds to wait between invocations.
- set_timeout(fn, delay)
-
Schedules code to run once in the future.
Example:
-- Edit /etc/fstab in 5 seconds. timer.set_timeout(function() mc.edit('/etc/fstab') end, 5000)
As with JavaScript in a browser, there’s no guarantee about the exact time your function will be called.
Parameters:
- fn The function to schedule.
- delay How many milliseconds in the future to schedule it to. This can be zero or negative if you want to run it as soon as possible.
- unlock()
-
Enables “reentrancy”.
By default, timers don’t fire while a scheduled function is already running. This is a feature intended to prevent the following code from “blowing up” your application with alert boxes:
timer.set_interval(function() alert('bomb!') end, 100)
If you want to disable this protective feature, call
timer.unlock()
at the start of your scheduled function: this will fool the system to think that no scheduled code is currently running.