cron.lua/README.md

cron.lua

cron.lua are a set of functions for executing actions at a certain time interval.

API

local clock = cron.after(time, callback, ...). Creates a clock that will execute callback after time passes. If additional params were provided, they are passed to callback.

local clock = cron.every(time, callback, ...). Creates a clock that will execute callback every time, periodically. Additional parameters are passed to the callback too.

Clock methods:

local expired = clock:update(dt). Increases the internal timer in the clock by dt.

• On one-time clocks, if the internal timer surpasses the clock's time, then the clock's callback is invoked.
• On periodic clocks, the callback is executed 0 or more times, depending on how big dt is and the clock's internal timer.
• expired will be true for one-time clocks whose time has passed, so their function has been invoked.

clock:reset([running]) Changes the internal timer manually to running, or to 0 if nothing is specified. It never invokes callback.

Examples

local cron = require 'cron'

local function printMessage()
  print('Hello')
end

-- the following calls are equivalent:
local c1 = cron.after(5, printMessage)
local c2 = cron.after(5, print, 'Hello')

c1:update(2) -- will print nothing, the action is not done yet
c1:update(5) -- will print 'Hello' once

c1:reset() -- reset the counter to 0

-- prints 'hey' 5 times and then prints 'hello'
while not c1:update(1) do
  print('hey')
end

-- Create a periodical clock:
local c3 = cron.every(10, printMessage)

c3:update(5) -- nothing (total time: 5)
c3:update(4) -- nothing (total time: 9)
c3:update(12) -- prints 'Hello' twice (total time is now 21)

Gotchas / Warnings

• cron.lua does not implement any hardware or software clock; you will have to provide it with the access to the hardware timers, in the form of periodic calls to cron.update
• cron does not have any defined time units (seconds, milliseconds, etc). You define the units it uses by passing it a dt on cron.update. If dt is in seconds, then cron will work in seconds. If dt is in milliseconds, then cron will work in milliseconds.

Installation

Just copy the cron.lua file somewhere in your projects (maybe inside a /lib/ folder) and require it accordingly.

Remember to store the value returned by require somewhere! (I suggest a local variable named cron)

local cron = require 'cron'

Also, make sure to read the license file; the text of that license file must appear somewhere in your projects' files.

Specs

This project uses busted for its specs. If you want to run the specs, you will have to install it first. Then run:

cd path/where/the/spec/folder/is
busted