add regular scheduled functions, now also callable on yield() (#6039)

* add regular scheduled functions, now also callable on `yield()`

added bool schedule_function_us(std::function<bool(void)> fn, uint32_t repeat_us)
lambda must return true to be not removed from the schedule function list
if repeat_us is 0, then the function is called only once.

Legacy schedule_function() is preserved

This addition allows network drivers like ethernet chips on lwIP to be regularly called
- even if some user code loops on receiving data without getting out from main loop
  (callable from yield())
- without the need to call the driver handling function
  (transparent)

This may be also applicable with common libraries (mDNS, Webserver, )

Author: d-a-v

Diff for: cores/esp8266/Esp.h

@@ -213,7 +213,8 @@ uint32_t EspClass::getCycleCount()
     __asm__ __volatile__("esync; rsr %0,ccount":"=a" (ccount));
     return ccount;
 }
-#endif
+
+#endif // !defined(CORE_MOCK)
 
 extern EspClass ESP;
 

Diff for: cores/esp8266/FunctionalInterrupt.cpp

@@ -1,7 +1,6 @@
 #include <FunctionalInterrupt.h>
 #include <Schedule.h>
 #include "Arduino.h"
-#include <ScheduledFunctions.h>
 
 // Duplicate typedefs from core_esp8266_wiring_digital_c
 typedef void (*voidFuncPtr)(void);
@@ -17,7 +16,6 @@ void ICACHE_RAM_ATTR interruptFunctional(void* arg)
 	if (localArg->functionInfo->reqScheduledFunction)
 	{
 		schedule_function(std::bind(localArg->functionInfo->reqScheduledFunction,InterruptInfo(*(localArg->interruptInfo))));
-//      scheduledInterrupts->scheduleFunctionReg(std::bind(localArg->functionInfo->reqScheduledFunction,InterruptInfo(*(localArg->interruptInfo))), false, true);
 	}
 	if (localArg->functionInfo->reqFunction)
 	{
@@ -54,10 +52,6 @@ void attachInterrupt(uint8_t pin, std::function<void(void)> intRoutine, int mode
 
 void attachScheduledInterrupt(uint8_t pin, std::function<void(InterruptInfo)> scheduledIntRoutine, int mode)
 {
-	if (!scheduledInterrupts)
-	{
-		scheduledInterrupts = new ScheduledFunctions(32);
-	}
 	InterruptInfo* ii = new InterruptInfo;
 
 	FunctionInfo* fi = new FunctionInfo;

Diff for: cores/esp8266/FunctionalInterrupt.h

@@ -4,7 +4,6 @@
 #include <stddef.h>
 #include <stdint.h>
 #include <functional>
-#include <ScheduledFunctions.h>
 
 extern "C" {
 #include "c_types.h"
@@ -29,7 +28,6 @@ struct ArgStructure {
 	FunctionInfo* functionInfo = nullptr;
 };
 
-static ScheduledFunctions* scheduledInterrupts;
 void attachInterrupt(uint8_t pin, std::function<void(void)> intRoutine, int mode);
 void attachScheduledInterrupt(uint8_t pin, std::function<void(InterruptInfo)> scheduledIntRoutine, int mode);
 

Diff for: cores/esp8266/PolledTimeout.h

@@ -153,7 +153,7 @@ class timeoutTemplate
     reset(userTimeout);
   }
 
-  ICACHE_RAM_ATTR
+  IRAM_ATTR // fast
   bool expired()
   {
     YieldPolicyT::execute(); //in case of DoNothing: gets optimized away
@@ -162,7 +162,7 @@ class timeoutTemplate
     return expiredOneShot();
   }
 
-  ICACHE_RAM_ATTR
+  IRAM_ATTR // fast
   operator bool()
   {
     return expired(); 
@@ -178,13 +178,15 @@ class timeoutTemplate
     return _timeout != alwaysExpired;
   }
 
+  IRAM_ATTR // called from ISR
   void reset(const timeType newUserTimeout)
   {
     reset();
     _timeout = TimePolicyT::toTimeTypeUnit(newUserTimeout);
     _neverExpires = (newUserTimeout < 0) || (newUserTimeout > timeMax());
   }
 
+  IRAM_ATTR // called from ISR
   void reset()
   {
     _start = TimePolicyT::time();
@@ -208,7 +210,7 @@ class timeoutTemplate
 
 private:
 
-  ICACHE_RAM_ATTR
+  IRAM_ATTR // fast
   bool checkExpired(const timeType internalUnit) const
   {
     // canWait() is not checked here
@@ -218,7 +220,7 @@ class timeoutTemplate
 
 protected:
 
-  ICACHE_RAM_ATTR
+  IRAM_ATTR // fast
   bool expiredRetrigger()
   {
     if (!canWait())
@@ -234,7 +236,7 @@ class timeoutTemplate
     return false;
   }
 
-  ICACHE_RAM_ATTR
+  IRAM_ATTR // fast
   bool expiredOneShot() const
   {
     // returns "always expired" or "has expired"

Diff for: cores/esp8266/Schedule.cpp

@@ -1,78 +1,131 @@
+
+#include <assert.h>
+
 #include "Schedule.h"
+#include "PolledTimeout.h"
+#include "interrupts.h"
+
+typedef std::function<bool(void)> mFuncT;
 
 struct scheduled_fn_t
 {
-    scheduled_fn_t* mNext;
-    std::function<void(void)> mFunc;
+    scheduled_fn_t* mNext = nullptr;
+    mFuncT mFunc;
+    esp8266::polledTimeout::periodicFastUs callNow;
+
+    scheduled_fn_t() : callNow(esp8266::polledTimeout::periodicFastUs::alwaysExpired) { }
 };
 
-static scheduled_fn_t* sFirst = 0;
-static scheduled_fn_t* sLast = 0;
+static scheduled_fn_t* sFirst = nullptr;
+static scheduled_fn_t* sLast = nullptr;
 
-static scheduled_fn_t* sFirstUnused = 0;
-static scheduled_fn_t* sLastUnused = 0;
+static scheduled_fn_t* sUnused = nullptr;
 
 static int sCount = 0;
 
-static scheduled_fn_t* get_fn() {
-    scheduled_fn_t* result = NULL;
+IRAM_ATTR // called from ISR
+static scheduled_fn_t* get_fn_unsafe()
+{
+    scheduled_fn_t* result = nullptr;
     // try to get an item from unused items list
-    if (sFirstUnused) {
-        result = sFirstUnused;
-        sFirstUnused = result->mNext;
-        if (sFirstUnused == NULL) {
-            sLastUnused = NULL;
-        }
+    if (sUnused)
+    {
+        result = sUnused;
+        sUnused = sUnused->mNext;
+        result->mNext = nullptr;
     }
     // if no unused items, and count not too high, allocate a new one
-    else if (sCount != SCHEDULED_FN_MAX_COUNT) {
+    else if (sCount < SCHEDULED_FN_MAX_COUNT)
+    {
         result = new scheduled_fn_t;
-        result->mNext = NULL;
         ++sCount;
     }
     return result;
 }
 
-static void recycle_fn(scheduled_fn_t* fn)
+static void recycle_fn_unsafe(scheduled_fn_t* fn)
 {
-    if (!sLastUnused) {
-        sFirstUnused = fn;
-    }
-    else {
-        sLastUnused->mNext = fn;
-    }
-    fn->mNext = NULL;
-    sLastUnused = fn;
+    fn->mFunc = nullptr; // special overload in c++ std lib
+    fn->mNext = sUnused;
+    sUnused = fn;
 }
 
-bool schedule_function(std::function<void(void)> fn)
+IRAM_ATTR // (not only) called from ISR
+bool schedule_function_us(std::function<bool(void)>&& fn, uint32_t repeat_us)
 {
-    scheduled_fn_t* item = get_fn();
-    if (!item) {
+    assert(repeat_us < decltype(scheduled_fn_t::callNow)::neverExpires); //~26800000us (26.8s)
+
+    InterruptLock lockAllInterruptsInThisScope;
+
+    scheduled_fn_t* item = get_fn_unsafe();
+    if (!item)
         return false;
-    }
+
+    if (repeat_us)
+        item->callNow.reset(repeat_us);
+
     item->mFunc = fn;
-    item->mNext = NULL;
-    if (!sFirst) {
-        sFirst = item;
-    }
-    else {
+    if (sFirst)
         sLast->mNext = item;
-    }
+    else
+        sFirst = item;
     sLast = item;
+
     return true;
 }
 
+IRAM_ATTR // (not only) called from ISR
+bool schedule_function_us(const std::function<bool(void)>& fn, uint32_t repeat_us)
+{
+    return schedule_function_us(std::function<bool(void)>(fn), repeat_us);
+}
+
+IRAM_ATTR // called from ISR
+bool schedule_function(std::function<void(void)>&& fn)
+{
+    return schedule_function_us([fn]() { fn(); return false; }, 0);
+}
+
+IRAM_ATTR // called from ISR
+bool schedule_function(const std::function<void(void)>& fn)
+{
+    return schedule_function(std::function<void(void)>(fn));
+}
+
 void run_scheduled_functions()
 {
-	scheduled_fn_t* rFirst = sFirst;
-	sFirst = NULL;
-	sLast  = NULL;
-    while (rFirst) {
-        scheduled_fn_t* item = rFirst;
-        rFirst = item->mNext;
-        item->mFunc();
-        item->mFunc = std::function<void(void)>();
-        recycle_fn(item);
+    // Note to the reader:
+    // There is no exposed API to remove a scheduled function:
+    // Scheduled functions are removed only from this function, and
+    // its purpose is that it is never called from an interrupt
+    // (always on cont stack).
+
+    scheduled_fn_t* lastRecurring = nullptr;
+    scheduled_fn_t* toCall = sFirst;
+    while (toCall)
+    {
+        scheduled_fn_t* item = toCall;
+        toCall = toCall->mNext;
+        if (item->callNow)
+        {
+            if (item->mFunc())
+            {
+                lastRecurring = item;
+            }
+            else
+            {
+                InterruptLock lockAllInterruptsInThisScope;
+
+                if (sFirst == item)
+                    sFirst = sFirst->mNext;
+                else if (lastRecurring)
+                    lastRecurring->mNext = item->mNext;
+
+                if (sLast == item)
+                    sLast = lastRecurring;
+
+                recycle_fn_unsafe(item);
+            }
+        }
     }
 }

Diff for: cores/esp8266/Schedule.h

@@ -4,22 +4,28 @@
 #include <functional>
 
 #define SCHEDULED_FN_MAX_COUNT 32
-#define SCHEDULED_FN_INITIAL_COUNT 4
 
-// Warning 
-// This API is not considered stable. 
-// Function signatures will change.
+// This API was not considered stable but is now stabilizing.
+// Function signatures may change, queue must stay FIFO.
 // You have been warned.
 
-// Run given function next time `loop` function returns, 
+// Run given function ONCE next time `loop` function returns,
+// or `yield` is called,
 // or `run_scheduled_functions` is called.
 // Use std::bind to pass arguments to a function, or call a class member function.
 // Note: there is no mechanism for cancelling scheduled functions.
 // Keep that in mind when binding functions to objects which may have short lifetime.
 // Returns false if the number of scheduled functions exceeds SCHEDULED_FN_MAX_COUNT.
-bool schedule_function(std::function<void(void)> fn);
+//bool schedule_function(std::function<void(void)>&& fn);
+bool schedule_function(const std::function<void(void)>& fn);
 
-// Run all scheduled functions. 
+// Run given function periodically about every <repeat_us> microseconds until it returns false.
+// Note that it may be more than <repeat_us> microseconds between calls if `yield` is not called
+// frequently, and therefore should not be used for timing critical operations.
+//bool schedule_function_us(std::function<bool(void)>&& fn, uint32_t repeat_us);
+bool schedule_function_us(const std::function<bool(void)>& fn, uint32_t repeat_us);
+
+// Run all scheduled functions.
 // Use this function if your are not using `loop`, or `loop` does not return
 // on a regular basis.
 void run_scheduled_functions();