Improvements to delay_ms.py

Author: peterhinch

v3/docs/TUTORIAL.md

@@ -1123,6 +1123,8 @@ Methods:
  5. `rvalue` No argument. If a timeout has occurred and a callback has run,
  returns the return value of the callback. If a coroutine was passed, returns
  the `Task` instance. This allows the `Task` to be cancelled or awaited.
+ 6. `wait` One or more tasks may wait on a `Delay_ms` instance. Execution will
+ proceed when the instance has timed out.
 
 In this example a `Delay_ms` instance is created with the default duration of
 1s. It is repeatedly triggered for 5 secs, preventing the callback from
@@ -1150,6 +1152,32 @@ try:
 finally:
     asyncio.new_event_loop()  # Clear retained state
 ```
+This example illustrates multiple tasks waiting on a `Delay_ms`. No callback is
+used.
+```python
+import uasyncio as asyncio
+from primitives.delay_ms import Delay_ms
+
+async def foo(n, d):
+    await d.wait()
+    print('Done in foo no.', n)
+
+async def my_app():
+    d = Delay_ms()
+    for n in range(4):
+        asyncio.create_task(foo(n, d))
+    d.trigger(3000)
+    print('Waiting on d')
+    await d.wait()
+    print('Done in my_app.')
+    await asyncio.sleep(1)
+    print('Test complete.')
+
+try:
+    asyncio.run(my_app())
+finally:
+    _ = asyncio.new_event_loop()  # Clear retained state
+```
 
 ## 3.9 Message
 

v3/primitives/delay_ms.py

@@ -1,69 +1,67 @@
-# delay_ms.py
+# delay_ms.py Now uses ThreadSafeFlag and has extra .wait() API
+# Usage:
+# from primitives.delay_ms import Delay_ms
 
-# Copyright (c) 2018-2020 Peter Hinch
+# Copyright (c) 2018-2021 Peter Hinch
 # Released under the MIT License (MIT) - see LICENSE file
-# Rewritten for uasyncio V3. Allows stop time to be brought forwards.
 
 import uasyncio as asyncio
 from utime import ticks_add, ticks_diff, ticks_ms
-from micropython import schedule
 from . import launch
-# Usage:
-# from primitives.delay_ms import Delay_ms
 
 class Delay_ms:
-    verbose = False  # verbose and can_alloc retained to avoid breaking code.
-    def __init__(self, func=None, args=(), can_alloc=True, duration=1000):
+
+    class DummyTimer:  # Stand-in for the timer class. Can be cancelled.
+        def cancel(self):
+            pass
+    _fake = DummyTimer()
+
+    def __init__(self, func=None, args=(), duration=1000):
         self._func = func
         self._args = args
-        self._duration = duration  # Default duration
-        self._tstop = None  # Stop time (ms). None signifies not running.
-        self._tsave = None  # Temporary storage for stop time
-        self._ktask = None  # timer task
-        self._retrn = None  # Return value of launched callable
-        self._do_trig = self._trig  # Avoid allocation in .trigger
+        self._durn = duration  # Default duration
+        self._retn = None  # Return value of launched callable
+        self._tend = None  # Stop time (absolute ms).
+        self._busy = False
+        self._trig = asyncio.ThreadSafeFlag()
+        self._tout = asyncio.Event()  # Timeout event
+        self.wait = self._tout.wait  # Allow: await wait_ms.wait()
+        self._ttask = self._fake  # Timer task
+        asyncio.create_task(self._run())
 
-    def stop(self):
-        if self._ktask is not None:
-            self._ktask.cancel()
+    async def _run(self):
+        while True:
+            await self._trig.wait()  # Await a trigger
+            self._ttask.cancel()  # Cancel and replace
+            await asyncio.sleep_ms(0)
+            dt = max(ticks_diff(self._tend, ticks_ms()), 0)  # Beware already elapsed.
+            self._ttask = asyncio.create_task(self._timer(dt))
 
-    def trigger(self, duration=0):  # Update end time
-        now = ticks_ms()
-        if duration <= 0:  # Use default set by constructor
-            duration = self._duration
-        self._retrn = None
-        is_running = self()
-        tstop = self._tstop  # Current stop time
-        # Retriggering normally just updates ._tstop for ._timer
-        self._tstop = ticks_add(now, duration)
-        # Identify special case where we are bringing the end time forward
-        can = is_running and duration < ticks_diff(tstop, now)
-        if not is_running or can:
-            schedule(self._do_trig, can)
+    async def _timer(self, dt):
+        await asyncio.sleep_ms(dt)
+        self._tout.set()  # Only gets here if not cancelled.
+        self._tout.clear()
+        self._busy = False
+        if self._func is not None:
+            self._retn = launch(self._func, self._args)
 
-    def _trig(self, can):
-        if can:
-            self._ktask.cancel()
-        self._ktask = asyncio.create_task(self._timer(can))
+# API
+    # trigger may be called from hard ISR.
+    def trigger(self, duration=0):  # Update absolute end time, 0-> ctor default
+        self._tend = ticks_add(ticks_ms(), duration if duration > 0 else self._durn)
+        self._retn = None  # Default in case cancelled.
+        self._busy = True
+        self._trig.set()
+
+    def stop(self):
+        self._ttask.cancel()
+        self._ttask = self._fake
+        self._busy = False
 
     def __call__(self):  # Current running status
-        return self._tstop is not None
+        return self._busy
 
     running = __call__
 
     def rvalue(self):
-        return self._retrn
-
-    async def _timer(self, restart):
-        if restart:  # Restore cached end time
-            self._tstop = self._tsave
-        try:
-            twait = ticks_diff(self._tstop, ticks_ms())
-            while twait > 0:  # Must loop here: might be retriggered
-                await asyncio.sleep_ms(twait)
-                twait = ticks_diff(self._tstop, ticks_ms())
-            if self._func is not None:  # Timed out: execute callback
-                self._retrn = launch(self._func, self._args)
-        finally:
-            self._tsave = self._tstop  # Save in case we restart.
-            self._tstop = None  # timer is stopped
+        return self._retn