Support uasyncio V2.0.

Author: peterhinch

FASTPOLL.md

@@ -4,23 +4,21 @@ This document describes a "priority" version of uasyncio. Its purpose is to
 provide a simple priority mechanism to facilitate the design of applications
 with improved millisecond-level timing accuracy and reduced scheduling latency.
 
-V0.2 Dec 2017. A single module designed to work with the official `uasyncio`
-library. This requires uasyncio.core V1.7 which was released on 16th Dec 2017,
-with firmware of that date or later. It does not yet support `uasyncio` V2.0.
+V0.3 Feb 2018. A single module designed to work with the official `uasyncio`
+library. This requires `uasyncio` V2.0 which requires firmware dated
+22nd Feb 2018 or later.
 
 **API CHANGES**
-The API has been changed to simplify the code and to improve consistency.
- 1. `call_after_ms` Args have changed to match other methods.
- 2. `get_event_loop` now only takes two args - setting the maximum overdue time
- must be done via the `max_overdue_ms` method.
+V2.0 of `uasyncio` changed the arguments to `get_event_loop` so this version
+has corresponding changes. See [section 3](./FASTPOLL.md#3-a-solution).
 
 ###### [Main README](./README.md)
 
 # Contents
 
  1. [Installation](./FASTPOLL.md#1-installation)
 
-  1.1 [Benchmarks](./FASTPOLL.md#11-benchmarks)
+  1.1 [Benchmarks](./FASTPOLL.md#11-benchmarks) Benchmark and demo programs.
 
  2. [Rationale](./FASTPOLL.md#2-rationale)
 
@@ -51,29 +49,34 @@ The API has been changed to simplify the code and to improve consistency.
 # 1. Installation
 
 Install and test uasyncio on the target hardware. Copy `asyncio_priority.py`
-to the target.
+to the target. Users of previous versions should update any of the benchmark
+programs which are to be run.
 
 In MicroPython 1.9 `uasyncio` was implemented as a frozen module on the
-ESP8266. The `asyncio_priority.py` module may be put in the filesystem or
-compiled as frozen bytecode. See [ESP Platforms](./FASTPOLL.md#6-esp-platforms)
-for general comments on the suitability of ESP platforms for systems requiring
-fast response.
+ESP8266. This version is not compatible with `asyncio_priority.py`. Given the
+limited resources of the ESP8266 `uasyncio` and `uasyncio_priority` should be
+implemented as frozen bytecode. See
+[ESP Platforms](./FASTPOLL.md#6-esp-platforms) for general comments on the
+suitability of ESP platforms for systems requiring fast response.
 
 ## 1.1 Benchmarks
 
 The benchmarks directory contains files demonstrating the performance gains
 offered by prioritisation. They also offer illustrations of the use of these
 features. Documentation is in the code.
 
- * latency.py Shows the effect on latency with and without low priority usage.
- * timing.py Shows the effect on timing with and without low priority usage.
- * rate.py Shows the frequency with which the official uasyncio schedules
- minimal coroutines (coros).
- * rate_p.py As above, but measures the overhead of the priority extension.
- * call_lp.py Demos low priority callbacks.
- * overdue.py Demo of maximum overdue feature.
- * priority.py Demo of high priority coro.
- * priority_test.py Cancellation of low priority coros.
+ * `benchmarks/latency.py` Shows the effect on latency with and without low
+ priority usage.
+ * `benchmarks/timing.py` Shows the effect on timing with and without low
+ priority usage.
+ * ``benchmarks/rate.py` Shows the frequency with which the official uasyncio
+ schedules minimal coroutines (coros).
+ * `benchmarks/rate_p.py` As above, but measures the overhead of the priority
+ extension.
+ * `benchmarks/call_lp.py` Demos low priority callbacks.
+ * `benchmarks/overdue.py` Demo of maximum overdue feature.
+ * `benchmarks/priority.py` Demo of high priority coro.
+ * `priority_test.py` Cancellation of low priority coros.
 
 With the exceptions of call_lp and priority.py, benchmarks can be run against
 the official and priority versions of usayncio.

README.md

@@ -18,22 +18,25 @@ This GitHub repository consists of the following parts:
  mechanism. With suitable application design this improves the rate at which
  devices can be polled and improves the accuracy of time delays. Also provides
  for low priority tasks which are only scheduled when normal tasks are paused.
- NOTE: this currently supports uasyncio V1.7.1.
+ NOTE: this requires uasyncio V2.0.
  * [Communication between devices](./syncom_as/README.md) Enables MicroPython
  boards to communicate without using a UART. Primarily intended to enable a
  a Pyboard-like device to achieve bidirectional communication with an ESP8266.
 
 # 2. Version and installation of uasyncio
 
-This has become more involved owing to the development of Paul Sokolovsky's
-fork. At the time of writing his fork supports `uasyncio` version 2.0. The
-version on PyPI is also V2.0.
+The documentation and code in this repository are based on `uasyncio` version
+2.0, which is the version on PyPi. This requires firmware dated 22nd Feb 2018
+or later.
 
-The version in [micropython-lib](https://github.com/micropython/micropython-lib)
-is version 1.7.1.
+Version 2.0 brings only one API change over V1.7.1, namely the arguments to
+`get_event_loop()`. Unless using the priority version all test programs and
+code samples use default args so will work under either version. The priority
+version requires the later version and firmware.
 
-With the exception of the priority version all docs and code samples should be
-compatible with both versions. Testing has been done under V1.7.1.
+[Paul Sokolovsky's library](https://github.com/pfalcon/micropython-lib) has the
+latest `uasyncio` code. At the time of writing (Feb 27th 2018) the version in
+[micropython-lib](https://github.com/micropython/micropython-lib) is 1.7.1.
 
 See [tutorial](./TUTORIAL.md#installing-uasyncio-on-bare-metal) for
 installation instructions.

TUTORIAL.md

@@ -56,7 +56,8 @@ $ python3 -m micropip.py install -p ~/syn micropython-uasyncio
 ```
 
 The `uasyncio` modules may be frozen as bytecode in the usual way, by placing
-the `uasyncio` directory in the port's `modules` directory and rebuilding.
+the `uasyncio` and `collections` directories in the port's `modules` directory
+and rebuilding.
 
 ###### [Main README](./README.md)
 
@@ -454,7 +455,7 @@ ineffective. It will not receive the `TimeoutError` until it has acquired the
 lock. The same observation applies to task cancellation.
 
 The module `asyn.py` offers a `Lock` class which works in these situations
-[Full details.](./PRIMITIVES.md#32-class-lock). It is significantly less
+[full details](./PRIMITIVES.md#32-class-lock). It is significantly less
 efficient than the official class but supports additional interfaces as per the
 CPython version including context manager usage.
 
@@ -630,8 +631,7 @@ controlled. Documentation of this is in the code.
 
 ## 3.6 Task cancellation
 
-This requires `uasyncio` V1.7.1 which was released on 7th Jan 2018, with
-firmware of that date or later.
+This requires `uasyncio` V1.7.1 or later, with suitably recent firmware.
 
 `uasyncio` now provides a `cancel(coro)` function. This works by throwing an
 exception to the coro in a special way: cancellation is deferred until the coro

asyncio_priority.py

@@ -46,7 +46,7 @@ def schedule_lp_task(self, cur_task, tnow):
         tim = time.ticks_diff(t, tnow)
         to_run = self._max_overdue_ms > 0 and tim < -self._max_overdue_ms
         if not to_run:  # No overdue LP task.
-            if len(self.runq):
+            if len(self.runq):  # zero delay tasks go straight to runq
                 return False
             to_run = tim <= 0  # True if LP task is due
             if to_run and self.waitq:  # Set False if a normal tasks is due.
@@ -199,11 +199,11 @@ def run_forever(self):
                 # need to feed anything to the next invocation of coroutine.
                 # If that changes, need to pass that value below.
                 if low_priority:
-                    self.call_after_ms(delay, cb)
+                    self.call_after_ms(delay, cb)  # Put on lpq
                 elif delay:
-                    self.call_later_ms(delay, cb)
+                    self.call_later_ms(delay, cb)  # waitq
                 else:
-                    self.call_soon(cb)
+                    self.call_soon(cb)  # runq
 
             # Wait until next waitq task or I/O availability
             delay = 0