MoonTimers Reference Manual

Preface

This is the reference manual ^[1] of MoonTimers, a Lua module that provides concurrent timers.

It is assumed that the reader is familiar with the Lua programming language.

For convenience of reference, this document contains external (deep) links to the Lua Reference Manual.

Getting and installing

For installation intructions, refer to the README file in the MoonTimers official repository on GitHub.

Module organization

The MoonTimers module is loaded using Lua’s require() and returns a table containing the functions it provides (as usual with Lua modules). This manual assumes that such table is named timers, i.e. that it is loaded with:

 timers = require("moontimers")

but nothing forbids the use of a different name.

Examples

Complete examples can be found in the examples/ directory of the release package.

License

MoonTimers is released under the MIT/X11 license (same as Lua, and with the same only requirement to give proper credits to the original author). The copyright notice is in the LICENSE file in the base directory of the official repository on GitHub.

Overview

This module extends Lua with timers.

The application can create multiple timer objects associating a callback function with each, and then start them to expire at a future point in time, and possibly stop them before their expiration.

The application is then expected to repeatedly call the trigger( ) function in its main event loop. This function checks for expired timers and executes their callback.

A simple example is shown below:

 local timers = require("moontimers")

 local duration = 2 -- seconds
 local function callback(timer, exptime)
    print(string.format("timer expired, system time = %f", timers.now()))
    -- Restart the timer:
    timer:start(exptime+duration)
 end

 -- Create a timer
 local t1 = timers.new(duration, callback)

 -- Start it:
 t1:start()

 -- Event loop:
 while true do
    timers.trigger()
 end

System time

All timestamps accepted or returned by functions and methods in this module refer to the system time given by the now( ) function described below.

The system time is relative to an unspecified point in the past that depends on the underlying function used to retrieve time from the operating system.

timestamp = now( )
Returns the current system time, in seconds.

dt = since(timestamp)
Returns the time elapsed from the point in time given by timestamp.

Timer objects

The application can create and manage timers using the functions and methods described below.

timer = new(duration, func)
Creates a new timer object.
duration: the timer’s default timeout (seconds),
func: the timer’s callback (a Lua function).
The func callback is executed when the timer expires as func(timer, exptime), where exptime is the actual expiration time.

timer:free( )
Deletes timer. Also stops it, if it is running.

exptime = timer:start([exptime])
Starts timer so to expire at the point in time given by exptime (default: exptime = now( )+duration).
Calling this function may change the current tnext value.

timer:stop( )
Stops timer. If the timer is not running, this function has no effects and generates no errors.

boolean, exptime = timer:is_running( )
If timer is running, returns true, exptime.
If timer is not running, returns false, math.huge.

timer:set_duration(duration)
timer:set_callback(func)
Set the timer’s default timeout, and its callback (see new( )).

Main loop

The functions described in this section are to be used in the application’s main event loop. In particular, the application is expected to repeatedly call the trigger( ) function in its event loop.

tnext = trigger( )
Executes the callbacks for all the timers that are expired.
The application is expected to call the trigger( ) function again no later than at tnext (a point in time, or math.huge if no timers are running).

tnext = tnext( )
Returns the current tnext value (see trigger( )).

1. This manual is written in AsciiDoc, rendered with AsciiDoctor and a CSS from the AsciiDoctor Stylesheet Factory.