Build 04

- simplified handling of initial global timer step
- expanded README.txt with full documentation

README.txt

@@ -1,9 +1,83 @@
-Timekeeper Mod v1.2
+Timekeeper Mod v1.3
 By Leslie E. Krause
 
 Timekeeper acts as a centralized dispatcher for all time-sensitive routines, thereby 
 obviating the need for redundant timer implementations within each mod.
 
+The Timekeeper class provides a simple and efficient means of executing code at regular 
+intervals. The constructor itself is global, so typically it will be used in conjunction 
+with entities.
+
+ * Timekeeper( this )
+   Instantiates and returns a new timekeeper object, with an optional meta table for use 
+   by callbacks (typically this will be a reference to the entity itself). Ideally the 
+   Timekeeper constructor will be called as soon as the LuaEntitySAO has been added to 
+   the environment.
+
+The timekeeper object is instantiated within the on_activate callback of an entity:
+
+>  on_activate(self)
+>          self.timekeeper = Timekeeper(self)
+>          :
+>  end,
+
+The following methods are available:
+
+ * timekeeper.start( period, name, func, delay )
+   Starts a new timer with the given name and period. The callback will execute no sooner 
+   than the next server step. If the callback returns false, then the timer will be 
+   cancelled and removed from the queue. An optional delay can be specified to avoid 
+   concurrency with other running timers.
+
+ * timekeeper.start_now( period, name, func )
+   Identical to timekeeper.start(), except the first iteration of the callback will be 
+   executed immediately.
+
+ * timekeeper.clear( name )
+   Cancels an existing timer with the given name.
+
+Four parameters are provided to the timer callback for each iteration:
+
+ * this - the meta table that was originally passed to the constructor
+ * cycles - the number of cycles that have accrued, beginning at 1
+ * period - the interval between each cycle
+ * elapsed - the elapsed time for all cycles
+ * overrun - the overrun time from the last cycle
+
+In order for the timers to be processed correctly, you must call the on_step method of 
+the timekeeper object during every server step. For example, in the case of entities:
+
+>  on_step = function (self, dtime)
+>          local timers = self.timekeeper.on_step(dtime)
+>          :
+>  end,
+
+The on_step method of the timekeeper object returns a table of running timers. This can 
+be useful for post-processing of timers within the on_step callback. Each timer consists 
+of the following read-only fields: cycles, period, expiry, started, and func.
+
+For convenience, a globaltimer singleton object is available for use by all mods. This 
+can avoid the need to register multiple globalsteps when a simple timer mechanism is all 
+that is required. In this case, the timer names must be prefixed with the mod name and a 
+colon to avoid collisions.
+
+The following method is available, but only at server startup:
+
+ * globaltimer.start( period, name, func, delay )
+   Starts a new global timer with the given name and period (name must be prefixed with
+   the current mod name). The callback will execute no sooner than the first server step. 
+   An optional delay can be specified to avoid concurrency with other global timers.
+
+Four parameters are provided to the global timer callback for each iteration:
+
+ * cycles - the number of cycles that have accrued, beginning at 1
+ * period - the interval between each cycle
+ * uptime - the elapsed time since server start
+ * overrun - the overrun time from the last cycle
+
+Since global timers are persistent, they are best suited for ongoing tasks that execute 
+for the lifetime of the server. Hence, there is no clear method.
+
 
 Repository
 ----------------------
@@ -27,7 +101,7 @@ License of source code
 
 The MIT License (MIT)
 
-Copyright (c) 2020-2021, Leslie Krause (leslie@searstower.org)
+Copyright (c) 2020-2022, Leslie Krause (leslie@searstower.org)
 
 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

init.lua

@@ -18,7 +18,7 @@ globaltimer.start = function ( period, name, func, delay )
 	table.insert( g_timer_list, {
 		cycles = 0,
 		period = period,
-		expiry = g_clock + period + ( delay or 0.0 ),
+		expiry = g_clock + ( delay or 0.0 ),
 		func = func,
 	} )
 end
@@ -27,7 +27,7 @@ minetest.register_globalstep( function ( dtime )
 	g_clock = g_clock + dtime
 
 	for i, v in ipairs( g_timer_list ) do
-		if g_clock >= v.expiry or g_clock == 0.0 then
+		if g_clock >= v.expiry then
 			v.expiry = g_clock + v.period
 			-- callback( cycles, period, uptime, overrun )
 			v.func( v.cycles, v.period, g_clock, g_clock - v.expiry )