Example Lua module for coroutining

docs/lua-modules/cohelper.md

@@ -0,0 +1,69 @@
+# cohelper Module
+| Since  | Origin / Contributor  | Maintainer  | Source  |
+| :----- | :-------------------- | :---------- | :------ |
+| 2019-07-24 | [TerryE](https://github.com/TerryE) | [TerryE](https://github.com/TerryE)  | [cohelper.lua](../../lua_modules/cohelper/cohelper.lua) |
+
+This module provides a simple wrapper around long running functions to allow 
+these to execute within the SDK and its advised limit of 15 mSec per individual
+task execution.  It does this by exploiting the standard Lua coroutine 
+functionality as described in the [Lua RM §2.11](https://www.lua.org/manual/5.1/manual.html#2.11) and [PiL Chapter 9](https://www.lua.org/pil/9.html).
+
+The NodeMCU Lua VM fully supports the standard coroutine functionality. Any
+interactive or callback tasks are executed in the default thread, and the coroutine
+itself runs in a second Lua thread. The coroutine can call any library functions,
+but any subsequent callbacks will, of course, execute in the default thread.
+
+Interaction between the coroutine and the parent is through yield and resume 
+statements, and since the order of SDK tasks is indeterminate, the application 
+must take care to handle any ordering issues.  This particular example uses
+the `node.task.post()` API withi the `taskYield()`function to resume itself, 
+so the running code can simple call `taskYield()` at regular points in the 
+processing to spilt the work into separate SDK tasks.
+
+A similar approach could be based on timer or on a socket or pipe CB.  If you 
+want to develop such a variant then start by reviewing the source and understanding
+what it does. 
+
+## Use
+```Lua
+do
+  local function longRunningFunc(yield, ...)
+  -- <content of function to be split into tasks>
+  end
+  require "cohelper".exec(longRunningFunc, params)
+end
+```
+
+## Full Example
+
+Here is a function which recursively walks the globals environment, the ROM table
+and the Registry. Without coroutining, this walk terminate with a PANIC following
+a watchdog timout. I don't want to sprinkle the code with `tmr.wdclr(`) that could
+in turn cause the network stack to fail. Here is how to do it using coroutining:
+
+```Lua
+require "cohelper".exec(
+  function(taskYield, list)
+    local s, n, nCBs = {}, 0, 0
+
+    local function list_entry (name, v) -- upval: taskYield, nCBs
+      print(name, v)
+      n = n + 1
+      if n % 20 == 0 then nCBs = taskYield(nCBs) end
+      if type(v):sub(-5) ~= 'table' or s[v] or name == 'Reg.stdout' then return end
+      s[v]=true
+      for k,tv in pairs(v) do
+        list_entry(name..'.'..k, tv)
+      end
+      s[v] = nil
+    end
+
+    for k,v in pairs(list) do
+      list_entry(k, v)
+    end
+    print ('Total lines, print batches = ', n, nCBs)
+  end,
+  {_G = _G, Reg = debug.getregistry(), ROM = ROM}
+)
+```
+

lua_modules/cohelper/README.md

@@ -0,0 +1,3 @@
+# Coroutine Helper Module
+
+Documentation for this Lua module is available in the [ftpserver.md](../../docs/lua-modules/cohelper.md) file and in the [Official NodeMCU Documentation](https://nodemcu.readthedocs.io/) in `Lua Modules` section.

lua_modules/cohelper/cohelper.lua

@@ -0,0 +1,27 @@
+--[[  A coroutine Helper   T. Ellison,  June 2019
+
+This version of couroutine helper demonstrates the use of corouting within
+NodeMCU execution to split structured Lua code into smaller tasks
+
+]]
+--luacheck: read globals node
+
+local modname = ...
+
+local function taskYieldFactory(co)
+  local post = node.task.post
+  return function(nCBs)  -- upval: co,post
+    post(function () -- upval: co, nCBs
+      coroutine.resume(co, nCBs or 0)
+    end)
+    return coroutine.yield() + 1
+  end
+end
+
+return { exec = function(func, ...) -- upval: modname
+  package.loaded[modname] = nil
+  local co = coroutine.create(func)
+  coroutine.resume(co, taskYieldFactory(co), ... )
+end }
+
+