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.

unlike in JavaScript, here you simply pass back the closure fed to set_interval. (This makes implementing facilities like debounce trivial.)

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.

You don’t need this function in order to use timers (or intervals). You'll seldom find a need for this function.

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”.

This function is very seldom needed. Feel free to ignore it.

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)

This issue only exists when the scheduled function calls the event loop (i.e., when it opens a dialog). It’s the event loop that fires the timers (remember: MC isn’t multithreaded). So if your function doesn’t open a dialog, no timer will ever get the chance to fire anyway.

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.

there’s no corresponding lock() function: the lock flag is automatically set when a scheduled function is called.

generated by LDoc 1.4.3 Last updated 2016-08-23 17:29:40