From 0e89fb24bae3c3dcd446b64f9bbc6d9581c08632 Mon Sep 17 00:00:00 2001
From: Nathaniel Wesley Filardo
 <VP331RHQ115POU58JFRLKB7OPA0L18E3@cmx.ietfng.org>
Date: Tue, 22 Jan 2019 21:59:41 +0000
Subject: [PATCH] Expunge integer timers (#2603)

---
 app/modules/tmr.c   |  64 ++-----
 docs/modules/tmr.md | 394 +++++++++++++++++++++-----------------------
 2 files changed, 210 insertions(+), 248 deletions(-)

diff --git a/app/modules/tmr.c b/app/modules/tmr.c
index 2d479a7c..b89e2c85 100644
--- a/app/modules/tmr.c
+++ b/app/modules/tmr.c
@@ -16,7 +16,7 @@ tmr.delay() -- not changed
 tmr.alarm() -- not changed
 tmr.stop()  -- changed, see below. use tmr.unregister for old functionality
 
-tmr.register(id, interval, mode, function)
+tmr.register(ref, interval, mode, function)
 	bind function with timer and set the interval in ms
 	the mode can be:
 		tmr.ALARM_SINGLE for a single run alarm
@@ -24,20 +24,20 @@ tmr.register(id, interval, mode, function)
 		tmr.ALARM_AUTO for a repating alarm
 	tmr.register does NOT start the timer
 	tmr.alarm is a tmr.register & tmr.start macro
-tmr.unregister(id)
+tmr.unregister(ref)
 	stop alarm, unbind function and clean up memory
 	not needed for ALARM_SINGLE, as it unregisters itself
-tmr.start(id)
+tmr.start(ref)
 	ret: bool
 	start a alarm, returns true on success
-tmr.stop(id)
+tmr.stop(ref)
 	ret: bool
 	stops a alarm, returns true on success
 	this call dose not free any memory, to do so use tmr.unregister
 	stopped alarms can be started with start
-tmr.interval(id, interval)
+tmr.interval(ref, interval)
 	set alarm interval, running alarm will be restarted
-tmr.state(id)
+tmr.state(ref)
 	ret: (bool, int) or nil
 	returns alarm status (true=started/false=stopped) and mode
 	nil if timer is unregistered
@@ -73,7 +73,8 @@ static const char* MAX_TIMEOUT_ERR_STR = "Range: 1-"STRINGIFY(MAX_TIMEOUT_DEF);
 
 typedef struct{
 	os_timer_t os;
-	sint32_t lua_ref, self_ref;
+	sint32_t lua_ref;	/* Reference to the callback function */
+	sint32_t self_ref;	/* Reference to this structure as userdata */
 	uint32_t interval;
 	uint8_t mode;
 }timer_struct_t;
@@ -93,7 +94,6 @@ static uint32_t last_rtc_time=0;
 static uint64_t last_rtc_time_us=0;
 
 static sint32_t soft_watchdog  = -1;
-static timer_struct_t alarm_timers[NUM_TMR];
 static os_timer_t rtc_timer;
 
 static void alarm_timer_common(void* arg){
@@ -102,12 +102,7 @@ static void alarm_timer_common(void* arg){
 	if(tmr->lua_ref == LUA_NOREF)
 		return;
 	lua_rawgeti(L, LUA_REGISTRYINDEX, tmr->lua_ref);
-	if (tmr->self_ref == LUA_REFNIL) {
-		uint32_t id = tmr - alarm_timers;
-		lua_pushinteger(L, id);
-	} else {
-		lua_rawgeti(L, LUA_REGISTRYINDEX, tmr->self_ref);
-	}
+	lua_rawgeti(L, LUA_REGISTRYINDEX, tmr->self_ref);
 	//if the timer was set to single run we clean up after it
 	if(tmr->mode == TIMER_MODE_SINGLE){
 		luaL_unref(L, LUA_REGISTRYINDEX, tmr->lua_ref);
@@ -148,19 +143,13 @@ static int tmr_now(lua_State* L){
 }
 
 static timer_t tmr_get( lua_State *L, int stack ) {
-	// Deprecated: static 0-6 timers control by index.
-	luaL_argcheck(L, (lua_isuserdata(L, stack) || lua_isnumber(L, stack)), 1, "timer object or numerical ID expected");
-	if (lua_isuserdata(L, stack)) {
-		return (timer_t)luaL_checkudata(L, stack, "tmr.timer");
-	} else {
-		uint32_t id = luaL_checkinteger(L, 1);
-		luaL_argcheck(L, platform_tmr_exists(id), 1, "invalid timer index");
-		return &alarm_timers[id];
-	}
-	return 0;
+	timer_t t = (timer_t)luaL_checkudata(L, stack, "tmr.timer");
+	if (t == NULL)
+		return (timer_t)luaL_error(L, "timer object expected");
+	return t;
 }
 
-// Lua: tmr.register( id / ref, interval, mode, function )
+// Lua: tmr.register( ref, interval, mode, function )
 static int tmr_register(lua_State* L){
 	timer_t tmr = tmr_get(L, 1);
 
@@ -389,8 +378,8 @@ static const LUA_REG_TYPE tmr_dyn_map[] = {
 	{ LSTRKEY( "state" ),       LFUNCVAL( tmr_state ) },
 	{ LSTRKEY( "interval" ),    LFUNCVAL( tmr_interval) },
 #ifdef TIMER_SUSPEND_ENABLE
-	{ LSTRKEY( "suspend" ),      LFUNCVAL( tmr_suspend ) },
-  { LSTRKEY( "resume" ),       LFUNCVAL( tmr_resume ) },
+	{ LSTRKEY( "suspend" ),     LFUNCVAL( tmr_suspend ) },
+	{ LSTRKEY( "resume" ),      LFUNCVAL( tmr_resume ) },
 #endif
 	{ LSTRKEY( "__gc" ),        LFUNCVAL( tmr_unregister ) },
 	{ LSTRKEY( "__index" ),     LROVAL( tmr_dyn_map ) },
@@ -403,19 +392,10 @@ static const LUA_REG_TYPE tmr_map[] = {
 	{ LSTRKEY( "wdclr" ),        LFUNCVAL( tmr_wdclr ) },
 	{ LSTRKEY( "softwd" ),       LFUNCVAL( tmr_softwd ) },
 	{ LSTRKEY( "time" ),         LFUNCVAL( tmr_time ) },
-	{ LSTRKEY( "register" ),     LFUNCVAL( tmr_register ) },
-	{ LSTRKEY( "alarm" ),        LFUNCVAL( tmr_alarm ) },
-	{ LSTRKEY( "start" ),        LFUNCVAL( tmr_start ) },
-  { LSTRKEY( "stop" ),         LFUNCVAL( tmr_stop ) },
 #ifdef TIMER_SUSPEND_ENABLE
-  { LSTRKEY( "suspend" ),      LFUNCVAL( tmr_suspend ) },
-  { LSTRKEY( "suspend_all" ),  LFUNCVAL( tmr_suspend_all ) },
-  { LSTRKEY( "resume" ),       LFUNCVAL( tmr_resume ) },
-  { LSTRKEY( "resume_all" ),   LFUNCVAL( tmr_resume_all ) },
+	{ LSTRKEY( "suspend_all" ),  LFUNCVAL( tmr_suspend_all ) },
+	{ LSTRKEY( "resume_all" ),   LFUNCVAL( tmr_resume_all ) },
 #endif
-	{ LSTRKEY( "unregister" ),   LFUNCVAL( tmr_unregister ) },
-	{ LSTRKEY( "state" ),        LFUNCVAL( tmr_state ) },
-	{ LSTRKEY( "interval" ),     LFUNCVAL( tmr_interval ) },
 	{ LSTRKEY( "create" ),       LFUNCVAL( tmr_create ) },
 	{ LSTRKEY( "ALARM_SINGLE" ), LNUMVAL( TIMER_MODE_SINGLE ) },
 	{ LSTRKEY( "ALARM_SEMI" ),   LNUMVAL( TIMER_MODE_SEMI ) },
@@ -425,16 +405,8 @@ static const LUA_REG_TYPE tmr_map[] = {
 
 #include "pm/swtimer.h"
 int luaopen_tmr( lua_State *L ){
-	int i;	
-
 	luaL_rometatable(L, "tmr.timer", (void *)tmr_dyn_map);
 
-	for(i=0; i<NUM_TMR; i++){
-		alarm_timers[i].lua_ref = LUA_NOREF;
-		alarm_timers[i].self_ref = LUA_REFNIL;
-		alarm_timers[i].mode = TIMER_MODE_OFF;
-		os_timer_disarm(&alarm_timers[i].os);
-	}
 	last_rtc_time=system_get_rtc_time(); // Right now is time 0
 	last_rtc_time_us=0;
 
diff --git a/docs/modules/tmr.md b/docs/modules/tmr.md
index 6f163c64..cfe4135a 100644
--- a/docs/modules/tmr.md
+++ b/docs/modules/tmr.md
@@ -9,63 +9,27 @@ It is aimed at setting up regularly occurring tasks, timing out operations, and
 
 What the tmr module is *not* however, is a time keeping module. While most timeouts are expressed in milliseconds or even microseconds, the accuracy is limited and compounding errors would lead to rather inaccurate time keeping. Consider using the [rtctime](rtctime.md) module for "wall clock" time.
 
-NodeMCU provides 7 static timers, numbered 0-6, and dynamic timer creation function [`tmr.create()`](#tmrcreate).
-
 !!! attention
 
-    Static timers are deprecated and will be removed later. Use the OO API initiated with [`tmr.create()`](#tmrcreate).
-
-## tmr.alarm()
-
-This is a convenience function combining [`tmr.register()`](#tmrregister) and [`tmr.start()`](#tmrstart) into a single call.
-
-To free up the resources with this timer when done using it, call [`tmr.unregister()`](#tmrunregister) on it. For one-shot timers this is not necessary, unless they were stopped before they expired.
-
-#### Syntax
-`tmr.alarm([id/ref], interval_ms, mode, func())`
-
-#### Parameters
-- `id`/`ref` timer id (0-6) or object, obsolete for OO API (→ [`tmr.create()`](#tmrcreate))
-- `interval_ms` timer interval in milliseconds. Maximum value is 6870947 (1:54:30.947).
-- `mode` timer mode:
-	- `tmr.ALARM_SINGLE` a one-shot alarm (and no need to call [`tmr.unregister()`](#tmrunregister))
-	- `tmr.ALARM_SEMI` manually repeating alarm (call [`tmr.start()`](#tmrstart) to restart)
-	- `tmr.ALARM_AUTO` automatically repeating alarm
-- `func(timer)` callback function which is invoked with the timer object as an argument
-
-#### Returns
-`true` if the timer was started, `false` on error
-
-#### Example
-```lua
-if not tmr.create():alarm(5000, tmr.ALARM_SINGLE, function()
-  print("hey there")
-end)
-then
-  print("whoopsie")
-end
-```
-#### See also
-- [`tmr.create()`](#tmrcreate)
-- [`tmr.register()`](#tmrregister)
-- [`tmr.start()`](#tmrstart)
-- [`tmr.unregister()`](#tmrunregister)
+    NodeMCU formerly provided 7 static timers, numbered 0-6, which could be
+    used instead of OO API timers initiated with [`tmr.create()`](#tmrcreate).
+    After a long period of deprecation, these were removed in 2019 Q1.
 
 ## tmr.create()
 
-Creates a dynamic timer object.
+Creates a dynamic timer object; see below for its method table.
 
 Dynamic timer can be used instead of numeric ID in control functions. Also can be controlled in object-oriented way.
 
 Functions supported in timer object:
 
-- [`t:alarm()`](#tmralarm)
-- [`t:interval()`](#tmrinterval)
-- [`t:register()`](#tmrregister)
-- [`t:start()`](#tmrstart)
-- [`t:state()`](#tmrstate)
-- [`t:stop()`](#tmrstop)
-- [`t:unregister()`](#tmrunregister)
+- [`t:alarm()`](#tobjalarm)
+- [`t:interval()`](#tobjinterval)
+- [`t:register()`](#tobjregister)
+- [`t:start()`](#tobjstart)
+- [`t:state()`](#tobjstate)
+- [`t:stop()`](#tobjstop)
+- [`t:unregister()`](#tobjunregister)
 
 #### Parameters
 none
@@ -76,14 +40,8 @@ none
 #### Example
 ```lua
 local mytimer = tmr.create()
-
--- oo calling
 mytimer:register(5000, tmr.ALARM_SINGLE, function (t) print("expired"); t:unregister() end)
 mytimer:start()
-
--- with self parameter
-tmr.register(mytimer, 5000, tmr.ALARM_SINGLE, function (t) print("expired"); tmr.unregister(t) end)
-tmr.start(mytimer)
 ```
 
 ## tmr.delay()
@@ -108,28 +66,6 @@ Also note that the actual amount of time delayed for may be noticeably greater,
 tmr.delay(100)
 ```
 
-## tmr.interval()
-
-Changes a registered timer's expiry interval.
-
-#### Syntax
-`tmr.interval([id/ref], interval_ms)`
-
-#### Parameters
-- `id`/`ref` timer id (0-6) or object, obsolete for OO API (→ [`tmr.create()`](#tmrcreate))
-- `interval_ms` new timer interval in milliseconds. Maximum value is 6870947 (1:54:30.947).
-
-#### Returns
-`nil`
-
-#### Example
-```lua
-mytimer = tmr.create()
-mytimer:register(10000, tmr.ALARM_AUTO, function() print("hey there") end)
-mytimer:interval(3000) -- actually, 3 seconds is better!
-mytimer:start()
-```
-
 ## tmr.now()
 
 Returns the system counter, which counts in microseconds. Limited to 31 bits, after that it wraps around back to zero. That is essential if you use this function to [debounce or throttle GPIO input](https://github.com/hackhitchin/esp8266-co-uk/issues/2).
@@ -149,39 +85,6 @@ print(tmr.now())
 print(tmr.now())
 ```
 
-## tmr.register()
-
-Configures a timer and registers the callback function to call on expiry.
-
-To free up the resources with this timer when done using it, call [`tmr.unregister()`](#tmrunregister) on it. For one-shot timers this is not necessary, unless they were stopped before they expired.
-
-#### Syntax
-`tmr.register([id/ref], interval_ms, mode, func())`
-
-#### Parameters
-- `id`/`ref` timer id (0-6) or object, obsolete for OO API (→ [`tmr.create()`](#tmrcreate))
-- `interval_ms` timer interval in milliseconds. Maximum value is 6870947 (1:54:30.947).
-- `mode` timer mode:
-	- `tmr.ALARM_SINGLE` a one-shot alarm (and no need to call [`tmr.unregister()`](#tmrunregister))
-	- `tmr.ALARM_SEMI` manually repeating alarm (call [`tmr.start()`](#tmrunregister) to restart)
-	- `tmr.ALARM_AUTO` automatically repeating alarm
-- `func(timer)` callback function which is invoked with the timer object as an argument
-
-Note that registering does *not* start the alarm.
-
-#### Returns
-`nil`
-
-#### Example
-```lua
-mytimer = tmr.create()
-mytimer:register(5000, tmr.ALARM_SINGLE, function() print("hey there") end)
-mytimer:start()
-```
-#### See also
-- [`tmr.create()`](#tmrcreate)
-- [`tmr.alarm()`](#tmralarm)
-
 ## tmr.softwd()
 
 Provides a simple software watchdog, which needs to be re-armed or disabled before it expires, or the system will be restarted.
@@ -207,78 +110,6 @@ tmr.softwd(5)
 complex_stuff_which_might_never_call_the_callback(on_success_callback)
 ```
 
-## tmr.start()
-
-Starts or restarts a previously configured timer.
-
-#### Syntax
-`tmr.start([id/ref])`
-
-#### Parameters
-`id`/`ref` timer id (0-6) or object, obsolete for OO API (→ [`tmr.create()`](#tmrcreate))
-
-#### Returns
-`true` if the timer was started, `false` on error
-
-#### Example
-```lua
-mytimer = tmr.create()
-mytimer:register(5000, tmr.ALARM_SINGLE, function() print("hey there") end)
-if not mytimer:start() then print("uh oh") end
-```
-#### See also
-- [`tmr.create()`](#tmrcreate)
-- [`tmr.register()`](#tmrregister)
-- [`tmr.stop()`](#tmrstop)
-- [`tmr.unregister()`](#tmrunregister)
-
-## tmr.state()
-
-Checks the state of a timer.
-
-#### Syntax
-`tmr.state([id/ref])`
-
-#### Parameters
-`id`/`ref` timer id (0-6) or object, obsolete for OO API (→ [`tmr.create()`](#tmrcreate))
-
-#### Returns
-(bool, int) or `nil`
-
-If the specified timer is registered, returns whether it is currently started and its mode. If the timer is not registered, `nil` is returned.
-
-#### Example
-```lua
-mytimer = tmr.create()
-print(mytimer:state()) -- nil
-mytimer:register(5000, tmr.ALARM_SINGLE, function() print("hey there") end)
-running, mode = mytimer:state()
-print("running: " .. tostring(running) .. ", mode: " .. mode) -- running: false, mode: 0
-```
-
-## tmr.stop()
-
-Stops a running timer, but does *not* unregister it. A stopped timer can be restarted with [`tmr.start()`](#tmrstart).
-
-#### Syntax
-`tmr.stop([id/ref])`
-
-#### Parameters
-`id`/`ref` timer id (0-6) or object, obsolete for OO API (→ [`tmr.create()`](#tmrcreate))
-
-#### Returns
-`true` if the timer was stopped, `false` on error
-
-#### Example
-```lua
-mytimer = tmr.create()
-if not mytimer:stop() then print("timer not stopped, not registered?") end
-```
-#### See also
-- [`tmr.register()`](#tmrregister)
-- [`tmr.stop()`](#tmrstop)
-- [`tmr.unregister()`](#tmrunregister)
-
 ## tmr.time()
 
 Returns the system uptime, in seconds. Limited to 31 bits, after that it wraps around back to zero.
@@ -297,28 +128,6 @@ the system uptime, in seconds, possibly wrapped around
 print("Uptime (probably):", tmr.time())
 ```
 
-## tmr.unregister()
-
-Stops the timer (if running) and unregisters the associated callback.
-
-This isn't necessary for one-shot timers (`tmr.ALARM_SINGLE`), as those automatically unregister themselves when fired.
-
-#### Syntax
-`tmr.unregister([id/ref])`
-
-#### Parameters
-`id`/`ref` timer id (0-6) or object, obsolete for OO API (→ [`tmr.create()`](#tmrcreate))
-
-#### Returns
-`nil`
-
-#### Example
-```lua
-tmr.unregister(0)
-```
-#### See also
-[`tmr.register()`](#tmrregister)
-
 ## tmr.wdclr()
 
 Feed the system watchdog.
@@ -335,3 +144,184 @@ none
 
 #### Returns
 `nil`
+
+## Timer Object Methods
+
+### tobj:alarm()
+
+This is a convenience function combining [`tobj:register()`](#tobjregister) and [`tobj:start()`](#tobjstart) into a single call.
+
+To free up the resources with this timer when done using it, call [`tobj:unregister()`](#tobjunregister) on it. For one-shot timers this is not necessary, unless they were stopped before they expired.
+
+#### Syntax
+`tobj:alarm(interval_ms, mode, func())`
+
+#### Parameters
+- `interval_ms` timer interval in milliseconds. Maximum value is 6870947 (1:54:30.947).
+- `mode` timer mode:
+	- `tmr.ALARM_SINGLE` a one-shot alarm (and no need to call [`unregister()`](#tobjunregister))
+	- `tmr.ALARM_SEMI` manually repeating alarm (call [`start()`](#tobjstart) to restart)
+	- `tmr.ALARM_AUTO` automatically repeating alarm
+- `func(timer)` callback function which is invoked with the timer object as an argument
+
+#### Returns
+`true` if the timer was started, `false` on error
+
+#### Example
+```lua
+if not tmr.create():alarm(5000, tmr.ALARM_SINGLE, function()
+  print("hey there")
+end)
+then
+  print("whoopsie")
+end
+```
+#### See also
+- [`tobj:create()`](#tobjcreate)
+- [`tobj:register()`](#tobjregister)
+- [`tobj:start()`](#tobjstart)
+- [`tobj:unregister()`](#tobjunregister)
+
+### tobj:interval()
+
+Changes a registered timer's expiry interval.
+
+#### Syntax
+`tobj:interval(interval_ms)`
+
+#### Parameters
+- `interval_ms` new timer interval in milliseconds. Maximum value is 6870947 (1:54:30.947).
+
+#### Returns
+`nil`
+
+#### Example
+```lua
+mytimer = tmr.create()
+mytimer:register(10000, tmr.ALARM_AUTO, function() print("hey there") end)
+mytimer:interval(3000) -- actually, 3 seconds is better!
+mytimer:start()
+```
+
+### tobj:register()
+
+Configures a timer and registers the callback function to call on expiry.
+
+To free up the resources with this timer when done using it, call [`tobj:unregister()`](#tobjunregister) on it. For one-shot timers this is not necessary, unless they were stopped before they expired.
+
+#### Syntax
+`tobj:register(interval_ms, mode, func())`
+
+#### Parameters
+- `interval_ms` timer interval in milliseconds. Maximum value is 6870947 (1:54:30.947).
+- `mode` timer mode:
+	- `tmr.ALARM_SINGLE` a one-shot alarm (and no need to call [`tobj:unregister()`](#tobjunregister))
+	- `tmr.ALARM_SEMI` manually repeating alarm (call [`tobj:start()`](#tobjunregister) to restart)
+	- `tmr.ALARM_AUTO` automatically repeating alarm
+- `func(timer)` callback function which is invoked with the timer object as an argument
+
+Note that registering does *not* start the alarm.
+
+#### Returns
+`nil`
+
+#### Example
+```lua
+mytimer = tmr.create()
+mytimer:register(5000, tmr.ALARM_SINGLE, function() print("hey there") end)
+mytimer:start()
+```
+#### See also
+- [`tobj:create()`](#tobjcreate)
+- [`tobj:alarm()`](#tobjalarm)
+
+### tobj:start()
+
+Starts or restarts a previously configured timer.
+
+#### Syntax
+`tobj:start()`
+
+#### Parameters
+None
+
+#### Returns
+`true` if the timer was started, `false` on error
+
+#### Example
+```lua
+mytimer = tmr.create()
+mytimer:register(5000, tmr.ALARM_SINGLE, function() print("hey there") end)
+if not mytimer:start() then print("uh oh") end
+```
+#### See also
+- [`tobj:create()`](#tobjcreate)
+- [`tobj:register()`](#tobjregister)
+- [`tobj:stop()`](#tobjstop)
+- [`tobj:unregister()`](#tobjunregister)
+
+### tobj:state()
+
+Checks the state of a timer.
+
+#### Syntax
+`tobj:state()`
+
+#### Parameters
+None
+
+#### Returns
+(bool, int) or `nil`
+
+If the specified timer is registered, returns whether it is currently started and its mode. If the timer is not registered, `nil` is returned.
+
+#### Example
+```lua
+mytimer = tmr.create()
+print(mytimer:state()) -- nil
+mytimer:register(5000, tmr.ALARM_SINGLE, function() print("hey there") end)
+running, mode = mytimer:state()
+print("running: " .. tostring(running) .. ", mode: " .. mode) -- running: false, mode: 0
+```
+
+### tobj:stop()
+
+Stops a running timer, but does *not* unregister it. A stopped timer can be restarted with [`tobj:start()`](#tobjstart).
+
+#### Syntax
+`tobj:stop()`
+
+#### Parameters
+None
+
+#### Returns
+`true` if the timer was stopped, `false` on error
+
+#### Example
+```lua
+mytimer = tmr.create()
+if not mytimer:stop() then print("timer not stopped, not registered?") end
+```
+#### See also
+- [`tobj:register()`](#tobjregister)
+- [`tobj:stop()`](#tobjstop)
+- [`tobj:unregister()`](#tobjunregister)
+
+### tobj:unregister()
+
+Stops the timer (if running) and unregisters the associated callback.
+
+This isn't necessary for one-shot timers (`tmr.ALARM_SINGLE`), as those automatically unregister themselves when fired.
+
+#### Syntax
+`tobj:unregister()`
+
+#### Parameters
+None
+
+#### Returns
+`nil`
+
+#### See also
+[`tobj:register()`](#tobjregister)
+