From a3c468058a259f619b7257b84324ca5c47780885 Mon Sep 17 00:00:00 2001 From: orwell96 Date: Wed, 6 Nov 2019 21:22:18 +0100 Subject: lines: document scheduler better --- advtrains_line_automation/scheduler.lua | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/advtrains_line_automation/scheduler.lua b/advtrains_line_automation/scheduler.lua index a2b7e7b..b641597 100644 --- a/advtrains_line_automation/scheduler.lua +++ b/advtrains_line_automation/scheduler.lua @@ -10,7 +10,11 @@ local UNITS_THRESH = 10 local MAX_PER_ITER = 10 local callbacks = {} ---Function signature is function(d) + +-- Register a handler callback to handle scheduler items. +-- e - a handler identifier (corresponds to "handler" in enqueue() ) +-- func - a function(evtdata) to be executed when a schedule item expires +-- evtdata - arbitrary data that has been passed into enqueue() function sched.register_callback(e, func) callbacks[e] = func end @@ -36,6 +40,7 @@ function sched.load(data) table.insert(queue, elem) units_cnt[elem.u] = (units_cnt[elem.u] or 0) + 1 end + atlog("[lines][scheduler] Loaded the schedule queue,",#data,"items.") end end function sched.save() @@ -54,7 +59,7 @@ function sched.run() -- run it callbacks[elem.e](elem.d) else - atwarn("No callback to handle schedule",elem) + atwarn("[lines][scheduler] No callback to handle schedule",elem) end cnt=cnt+1 ucn = units_cnt[elem.u] @@ -67,6 +72,12 @@ function sched.run() end end +-- Enqueue a new scheduled item to be executed at "rwtime" +-- handler: a string identifying the handler to use (registered with sched.register_callback()) +-- evtdata: Arbitrary Lua data to be passed to the handler callback +-- unitid: An arbitrary string uniquely identifying the thing that is issuing this enqueue. +-- used to prevent expotentially growing "scheduler bombs" +-- unitlim: Custom override for UNITS_THRESH (see there) function sched.enqueue(rwtime, handler, evtdata, unitid, unitlim) local qtime = ln.rwt.to_secs(rwtime) assert(type(handler)=="string") @@ -79,7 +90,7 @@ function sched.enqueue(rwtime, handler, evtdata, unitid, unitlim) ucn = (units_cnt[unitid] or 0) local ulim=(unitlim or UNITS_THRESH) if ucn >= ulim then - atwarn("Scheduler: discarding enqueue for",handler,"(limit",ulim,") because unit",unitid,"has already",ucn,"schedules enqueued") + atwarn("[lines][scheduler] discarding enqueue for",handler,"(limit",ulim,") because unit",unitid,"has already",ucn,"schedules enqueued") return false end @@ -99,6 +110,7 @@ function sched.enqueue(rwtime, handler, evtdata, unitid, unitlim) end end +-- See enqueue(). Same meaning, except that rwtime is relative to now. function sched.enqueue_in(rwtime, handler, evtdata, unitid, unitlim) local ctime = ln.rwt.get_time() sched.enqueue(ctime + rwtime, handler, evtdata, unitid, unitlim) -- cgit v1.2.3