Initial commit of sched module

Author: peterhinch

v3/README.md

@@ -25,6 +25,12 @@ Documented in the tutorial. Comprises:
  * Classes for interfacing switches and pushbuttons.
  * A software retriggerable monostable timer class, similar to a watchdog.
 
+### A scheduler
+
+This [lightweight scheduler](./docs/SCHEDULE.md) enables tasks to be scheduled
+at future times. These can be assigned in a flexible way: a task might run at
+4.10am on Monday and Friday if there's no "r" in the month.
+
 ### Asynchronous device drivers  
 
 These device drivers are intended as examples of asynchronous code which are

v3/as_drivers/sched/__init__.py

@@ -0,0 +1,40 @@
+# asynctest.py Demo of asynchronous code scheduling tasks with cron
+
+# Copyright (c) 2020 Peter Hinch
+# Released under the MIT License (MIT) - see LICENSE file
+
+import uasyncio as asyncio
+from sched.sched import schedule
+from sched.cron import cron
+from time import localtime
+
+def foo(txt):  # Demonstrate callback
+    yr, mo, md, h, m, s, wd = localtime()[:7]
+    fst = 'Callback {} {:02d}:{:02d}:{:02d} on {:02d}/{:02d}/{:02d}'
+    print(fst.format(txt, h, m, s, md, mo, yr))
+
+async def bar(txt):  # Demonstrate coro launch
+    yr, mo, md, h, m, s, wd = localtime()[:7]
+    fst = 'Coroutine {} {:02d}:{:02d}:{:02d} on {:02d}/{:02d}/{:02d}'
+    print(fst.format(txt, h, m, s, md, mo, yr))
+    await asyncio.sleep(0)
+
+async def main():
+    print('Asynchronous test running...')
+    cron4 = cron(hrs=None, mins=range(0, 60, 4))
+    asyncio.create_task(schedule(cron4, foo, ('every 4 mins',)))
+
+    cron5 = cron(hrs=None, mins=range(0, 60, 5))
+    asyncio.create_task(schedule(cron5, foo, ('every 5 mins',)))
+
+    cron3 = cron(hrs=None, mins=range(0, 60, 3))  # Launch a coroutine
+    asyncio.create_task(schedule(cron3, bar, ('every 3 mins',)))
+
+    cron2 = cron(hrs=None, mins=range(0, 60, 2))
+    asyncio.create_task(schedule(cron2, foo, ('one shot',), True))
+    await asyncio.sleep(900)  # Quit after 15 minutes
+
+try:
+    asyncio.run(main())
+finally:
+    _ = asyncio.new_event_loop()

v3/as_drivers/sched/asynctest.py

@@ -0,0 +1,113 @@
+# cron.py
+
+# Copyright (c) 2020 Peter Hinch
+# Released under the MIT License (MIT) - see LICENSE file
+
+from time import mktime, localtime
+# Validation
+_valid = ((0, 59, 'secs'), (0, 59, 'mins'), (0, 23, 'hrs'),
+          (1, 31, 'mday'), (1, 12, 'month'), (0, 6, 'wday'))
+_mdays = {2:28, 4:30, 6:30, 9:30, 11:30}
+# A call to the inner function takes 270-520μs on Pyboard depending on args
+def cron(*, secs=0, mins=0, hrs=3, mday=None, month=None, wday=None):
+    # Given an arg and current value, return offset between arg and cv
+    # If arg is iterable return offset of next arg +ve for future -ve for past (add modulo)
+    def do_arg(a, cv):  # Arg, current value
+        if a is None:
+            return 0
+        elif isinstance(a, int):
+            return a - cv
+        try:
+            return min(x for x in a if x >= cv) - cv
+        except ValueError:  # wrap-round
+            return min(a) - cv  # -ve
+        except TypeError:
+            raise ValueError('Invalid argument type', type(a))
+
+    if secs is None:  # Special validation for seconds
+        raise ValueError('Invalid None value for secs')
+    if not isinstance(secs, int) and len(secs) > 1:  # It's an iterable
+        ss = sorted(secs)
+        if min((a[1] - a[0] for a in zip(ss, ss[1:]))) < 2:
+            raise ValueError("Can't have consecutive seconds.", last, x)
+    args = (secs, mins, hrs, mday, month, wday)  # Validation for all args
+    valid = iter(_valid)
+    vestr = 'Argument {} out of range'
+    vmstr = 'Invalid no. of days for month'
+    for arg in args:  # Check for illegal arg values
+        lower, upper, errtxt = next(valid)
+        if isinstance(arg, int):
+            if not lower <= arg <= upper:
+                raise ValueError(vestr.format(errtxt))
+        elif arg is not None:  # Must be an iterable
+            if any(v for v in arg if not lower <= v <= upper):
+                raise ValueError(vestr.format(errtxt))
+    if mday is not None and month is not None:  # Check mday against month
+        max_md = mday if isinstance(mday, int) else max(mday)
+        if isinstance(month, int):
+            if max_md > _mdays.get(month, 31):
+                raise ValueError(vmstr)
+        elif sum((m for m in month if max_md > _mdays.get(m, 31))):
+            raise ValueError(vmstr)
+    if mday is not None and wday is not None and do_arg(mday, 23) > 0:
+        raise ValueError('mday must be <= 22 if wday also specified.')
+
+    def inner(tnow):
+        tev = tnow  # Time of next event: work forward from time now
+        yr, mo, md, h, m, s, wd = localtime(tev)[:7]
+        init_mo = mo  # Month now
+        toff = do_arg(secs, s)
+        tev += toff if toff >= 0 else 60 + toff
+
+        yr, mo, md, h, m, s, wd = localtime(tev)[:7]
+        toff = do_arg(mins, m)
+        tev += 60 * (toff if toff >= 0 else 60 + toff)
+
+        yr, mo, md, h, m, s, wd = localtime(tev)[:7]
+        toff = do_arg(hrs, h)
+        tev += 3600 * (toff if toff >= 0 else 24 + toff)
+
+        yr, mo, md, h, m, s, wd = localtime(tev)[:7]
+        toff = do_arg(month, mo)
+        mo += toff
+        md = md if mo == init_mo else 1
+        if toff < 0:
+            yr += 1
+        tev = mktime((yr, mo, md, h, m, s, wd, 0))
+        yr, mo, md, h, m, s, wd = localtime(tev)[:7]
+        if mday is not None:
+            if mo == init_mo:  # Month has not rolled over or been changed
+                toff = do_arg(mday, md)  # see if mday causes rollover
+                md += toff
+                if toff < 0:
+                    toff = do_arg(month, mo + 1)  # Get next valid month
+                    mo += toff + 1  # Offset is relative to next month
+                    if toff < 0:
+                        yr += 1
+            else:  # Month has rolled over: day is absolute
+                md = do_arg(mday, 0)
+
+        if wday is not None:
+            if mo == init_mo:
+                toff = do_arg(wday, wd)
+                md += toff % 7  # mktime handles md > 31 but month may increment
+                tev = mktime((yr, mo, md, h, m, s, wd, 0))
+                cur_mo = mo
+                _, mo = localtime(tev)[:2]  # get month
+                if mo != cur_mo:
+                    toff = do_arg(month, mo)  # Get next valid month
+                    mo += toff  # Offset is relative to new, incremented month
+                    if toff < 0:
+                        yr += 1
+                    tev = mktime((yr, mo, 1, h, m, s, wd, 0))  # 1st of new month
+                    yr, mo, md, h, m, s, wd = localtime(tev)[:7]  # get day of week
+                    toff = do_arg(wday, wd)
+                    md += toff % 7
+            else:
+                md = 1 if mday is None else md
+                tev = mktime((yr, mo, md, h, m, s, wd, 0))  # 1st of new month
+                yr, mo, md, h, m, s, wd = localtime(tev)[:7]  # get day of week
+                md += (do_arg(wday, 0) - wd) % 7
+
+        return mktime((yr, mo, md, h, m, s, wd, 0)) - tnow
+    return inner

v3/as_drivers/sched/cron.py

@@ -0,0 +1,72 @@
+# crontest.py
+
+# Copyright (c) 2020 Peter Hinch
+# Released under the MIT License (MIT) - see LICENSE file
+
+from time import time, ticks_diff, ticks_us, localtime
+from sched.cron import cron
+import sys
+
+maxruntime = 0
+fail = 0
+def result(t, msg):
+    global fail
+    if t != next(iexp):
+        print('FAIL', msg, t)
+        fail += 1
+        return
+    print('PASS', msg, t)
+
+def test(*, secs=0, mins=0, hrs=3, mday=None, month=None, wday=None, tsource=None):
+    global maxruntime
+    ts = int(time() if tsource is None else tsource)  # int() for Unix build
+    cg = cron(secs=secs, mins=mins, hrs=hrs, mday=mday, month=month, wday=wday)
+    start = ticks_us()
+    t = cg(ts)  # Time relative to ts
+    delta = ticks_diff(ticks_us(), start)
+    maxruntime = max(maxruntime, delta)
+    print('Runtime = {}μs'.format(delta))
+    tev = t + ts  # Absolute time of 1st event
+    yr, mo, md, h, m, s, wd = localtime(tev)[:7]
+    print('{:02d}:{:02d}:{:02d} on {:02d}/{:02d}/{:02d}'.format(h, m, s, md, mo, yr))
+    return t  # Relative time
+
+now = 1596074400 if sys.platform == 'linux' else 649393200  # 3am Thursday (day 3) 30 July 2020
+iexp = iter([79500, 79500, 86700, 10680, 13564800, 17712000,
+             12781800, 11217915, 5443200, 21600, 17193600,
+             18403200, 5353140, 13392000, 18662400])
+# Expect 01:05:00 on 31/07/2020
+result(test(wday=4, hrs=(1,2), mins=5, tsource=now), 'wday and time both cause 1 day increment.')
+# 01:05:00 on 31/07/2020
+result(test(hrs=(1,2), mins=5, tsource=now), 'time causes 1 day increment.')
+# 03:05:00 on 31/07/2020
+result(test(wday=4, mins=5, tsource=now), 'wday causes 1 day increment.')
+# 05:58:00 on 30/07/2020
+result(test(hrs=(5, 23), mins=58, tsource=now), 'time increment no day change.')
+# 03:00:00 on 03/01/2021
+result(test(month=1, wday=6, tsource=now), 'month and year rollover, 1st Sunday')
+# 03:00:00 on 20/02/2021
+result(test(month=2, mday=20, tsource=now), 'month and year rollover, mday->20 Feb')
+# 01:30:00 on 25/12/2020
+result(test(month=12, mday=25, hrs=1, mins=30, tsource=now), 'Forward to Christmas day, hrs backwards')
+# 23:05:15 on 06/12/2020
+result(test(month=12, wday=6, hrs=23, mins=5, secs=15, tsource=now), '1st Sunday in Dec 2020')
+# 03:00:00 on 01/10/2020
+result(test(month=10, tsource=now), 'Current time on 1st Oct 2020')
+# 09:00:00 on 30/07/2020
+result(test(month=7, hrs=9, tsource=now), 'Explicitly specify current month')
+# 03:00:00 on 14/02/2021
+result(test(month=2, mday=8, wday=6, tsource=now), 'Second Sunday in February 2021')
+# 03:00:00 on 28/02/2021
+result(test(month=2, mday=22, wday=6, tsource=now), 'Fourth Sunday in February 2021')  # last day of month
+# 01:59:00 on 01/10/2020
+result(test(month=(7, 10), hrs=1, mins=59, tsource=now + 24*3600), 'Time causes month rollover to next legal month')
+# 03:00:00 on 01/01/2021
+result(test(month=(7, 1), mday=1, tsource=now), 'mday causes month rollover to next year')
+# 03:00:00 on 03/03/2021
+result(test(month=(7, 3), wday=(2, 6), tsource=now), 'wday causes month rollover to next year')
+print('Max runtime {}μs'.format(maxruntime))
+if fail:
+    print(fail, 'FAILURES OCCURRED')
+else:
+    print('ALL TESTS PASSED')

v3/as_drivers/sched/crontest.py

@@ -0,0 +1,31 @@
+# __init__.py Common functions for uasyncio primitives
+
+# Copyright (c) 2018-2020 Peter Hinch
+# Released under the MIT License (MIT) - see LICENSE file
+
+try:
+    import uasyncio as asyncio
+except ImportError:
+    import asyncio
+
+
+async def _g():
+    pass
+type_coro = type(_g())
+
+# If a callback is passed, run it and return.
+# If a coro is passed initiate it and return.
+# coros are passed by name i.e. not using function call syntax.
+def launch(func, tup_args):
+    res = func(*tup_args)
+    if isinstance(res, type_coro):
+        res = asyncio.create_task(res)
+    return res
+
+def set_global_exception():
+    def _handle_exception(loop, context):
+        import sys
+        sys.print_exception(context["exception"])
+        sys.exit()
+    loop = asyncio.get_event_loop()
+    loop.set_exception_handler(_handle_exception)

v3/as_drivers/sched/primitives/__init__.py

@@ -0,0 +1,21 @@
+# sched.py
+
+# Copyright (c) 2020 Peter Hinch
+# Released under the MIT License (MIT) - see LICENSE file
+
+import uasyncio as asyncio
+from sched.primitives import launch
+from time import time
+
+async def schedule(fcron, routine, args=(), run_once=False):
+    maxt = 1000  # uasyncio can't handle arbitrarily long delays
+    done = False
+    while not done:
+        tw = fcron(int(time()))  # Time to wait (s)
+        while tw > 0:  # While there is still time to wait
+            tw = min(tw, maxt)
+            await asyncio.sleep(tw)
+            tw -= maxt
+        launch(routine, args)
+        done = run_once
+        await asyncio.sleep_ms(1200)  # ensure we're into next second

v3/as_drivers/sched/sched.py

@@ -0,0 +1,41 @@
+# synctest.py Demo of synchronous code scheduling tasks with cron
+
+# Copyright (c) 2020 Peter Hinch
+# Released under the MIT License (MIT) - see LICENSE file
+
+from .cron import cron
+from time import localtime, sleep, time
+
+def foo(txt):
+    yr, mo, md, h, m, s, wd = localtime()[:7]
+    fst = "{} {:02d}:{:02d}:{:02d} on {:02d}/{:02d}/{:02d}"
+    print(fst.format(txt, h, m, s, md, mo, yr))
+
+def main():
+    print('Synchronous test running...')
+    tasks = []  # Entries: cron, callback, args, one_shot
+    cron4 = cron(hrs=None, mins=range(0, 60, 4))
+    tasks.append([cron4, foo, ('every 4 mins',), False, False])
+    cron5 = cron(hrs=None, mins=range(0, 60, 5))
+    tasks.append([cron5, foo, ('every 5 mins',), False, False])
+    cron3 = cron(hrs=None, mins=range(0, 60, 3))
+    tasks.append([cron3, foo, ('every 3 mins',), False, False])
+    cron2 = cron(hrs=None, mins=range(0, 60, 2))
+    tasks.append([cron2, foo, ('one shot',), True, False])
+    to_run = []
+    while True:
+        now = int(time())  # Ensure constant: get once per iteration.
+        tasks.sort(key=lambda x:x[0](now))
+        to_run.clear()  # Pending tasks
+        deltat = tasks[0][0](now)  # Time to pending task(s)
+        for task in (t for t in tasks if t[0](now) == deltat):  # Tasks with same delta t
+            to_run.append(task)
+            task[4] = True  # Has been scheduled
+        # Remove on-shot tasks which have been scheduled
+        tasks = [t for t in tasks if not (t[3] and t[4])]
+        sleep(deltat)
+        for tsk in to_run:
+            tsk[1](*tsk[2])
+        sleep(1.2)  # Ensure seconds have rolled over
+
+main()