kikito / cron.lua Goto Github PK

View Code? Open in Web Editor NEW

166.0 14.0 26.0 33 KB

Time-related functions for Lua, inspired in javascript's setTimeout and setInterval

License: MIT License

Lua 100.00%

cron.lua's Introduction

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

cron.lua's People

Contributors

Stargazers

Watchers

cron.lua's Issues

Remove/kill timers after X iterations

I realize this is an incredibly old project, but it's basically exactly what I was looking for except I am looking to "kill/remove" the timer from the meta table after X iterations of it running. I haven't written the kill part, as I can't get the script to only cycle for X iterations.

`
local cron = {
__VERSION = 'cron.lua 2.0.0',
__DESCRIPTION = 'Time-related functions for lua',
__URL = 'https://github.com/kikito/cron.lua',
__LICENSE = [[
Copyright (c) 2011 Enrique García Cota
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
]]
}

-- Private functions

local function isCallable(callback)
local tc = type(callback)
if tc == 'function' then return true end
if tc == 'table' then
local mt = getmetatable(callback)
return type(mt) == 'table' and type(mt.__call) == 'function'
end
return false
end

local function checkPositiveInteger(name, value)
if type(value) ~= "number" or value < 0 then
error(name .. " must be a positive number")
end
end

local Clock = {}
local Clock_mt = {__index = Clock}

local function newClock(time, callback, update, ..., iterations)
checkPositiveInteger('time', time)
assert(isCallable(callback), "callback must be a function")

return setmetatable({
time = time,
callback = callback,
args = {...},
running = 0,
update = update,
iterations = iterations
}, Clock_mt)
end

local function updateAfterClock(self, dt) -- returns true if expired
checkPositiveInteger('dt', dt)
if self.running >= self.time and self.iterations >= -1 then
self.iterations = self.iterations - 1
return true
end

self.running = self.running + dt

if self.running >= self.time then
self.callback(unpack(self.args))
return true
end
return false
end

local function updateEveryClock(self, dt)
checkPositiveInteger('dt', dt)
self.running = self.running + dt

while self.running >= self.time and self.iterations > -1 do
self.callback(unpack(self.args))
self.running = self.running - self.time
self.iterations = self.iterations - 1
end
return false
end

function Clock:reset(running)
running = running or 0
checkPositiveInteger('running', running)
self.running = running
self.iterations = -1 -- this disables the timer as iterations is -1
end

function cron.after(time, callback, ..., iterations)
return newClock(time, callback, updateAfterClock, ..., iterations)
end

function cron.every(time, callback, ..., iterations)
return newClock(time, callback, updateEveryClock, ..., iterations)
end

return cron
I am then initiating the timer via
t_europa3 = cron.every(5, doEuropa_i,0,0,3)
`

and I can update it succesfully every 1 second, however the passed iterations parameter (I've tried it in different spots), don't seem to matter. self.iterations doesn't seem to be catching or lowering itself.
I know this is most likely dead, but any insight would be appreciated.

Consider updating individual crons

In some cases it might be useful to update only certain crons (for example, pausing all crons except the ones of the pause menu).

How we do this is difficult though. Several possible, compatible-between-each-other ways:

Make each individual cron updateable
Make groups - possibly nestable for more awesome

Must think about all this.