V0.24 Fast response to cancellation and timeout.

Author: peterhinch

FASTPOLL.md

@@ -2,9 +2,15 @@
 
 This version is a "drop in" replacement for official `uasyncio`. Existing
 applications should run under it unchanged and with essentially identical
-performance.
+performance except that task cancellation and timeouts are expedited "soon"
+rather than being deferred until the task is next scheduled.
+
+"Priority" features are only enabled if the event loop is instantiated with
+specific arguments.
 
-This version has the following features:
+This version has the following features relative to official V2.0:
+ * Timeouts and task cancellation are handled promptly, rather than being
+ deferred until the coroutine is next scheduled.
  * I/O can optionally be handled at a higher priority than other coroutines
  [PR287](https://github.com/micropython/micropython-lib/pull/287).
  * Tasks can yield with low priority, running when nothing else is pending.
@@ -18,7 +24,7 @@ This version has the following features:
  is called with a generator function
  [PR292](https://github.com/micropython/micropython-lib/pull/292). This traps
  a common coding error which otherwise results in silent failure.
- * The presence of the `fast_io` version can be tested at runtime.
+ * The presence and version of the `fast_io` version can be tested at runtime.
  * The presence of an event loop instance can be tested at runtime.
  * `run_until_complete(coro())` now returns the value returned by `coro()` as
  per CPython
@@ -31,6 +37,12 @@ adding just one line of code. This implies that if official `uasyncio` acquires
 a means of prioritising I/O other than that in this version, application code
 changes should be minimal. 
 
+#### Changes incompatible with prior versions
+
+V0.24  
+The `version` bound variable now retuens a 2-tuple.
+
+Prior versions.  
 The high priority mechanism formerly provided in `asyncio_priority.py` was a
 workround based on the view that stream I/O written in Python would remain
 unsupported. This is now available so `asyncio_priority.py` is obsolete and
@@ -63,7 +75,7 @@ formerly provided by `asyncio_priority.py` is now implemented.
 The basic approach is to install and test `uasyncio` on the target hardware.
 Replace `core.py` and `__init__.py` with the files in the `fast_io` directory.
 
-The current MicroPython release build (1.9.4) has `uasyncio` implemented as a
+The current MicroPython release build (1.10) has `uasyncio` implemented as a
 frozen module. The following options for installing `fast_io` exist:
 
  1. Use a daily build, install `uasyncio` as per the tutorial then replace the
@@ -75,33 +87,43 @@ frozen module. The following options for installing `fast_io` exist:
  bytecode. If this is deleted and appended to the end, frozen files will only
  be found if there is no match in the filesystem.
 
+```python
+import sys
+sys.path.append(sys.path.pop(0))  # Prefer modules in filesystem
+```
+
 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.
+The following files demonstrate the performance gains offered by prioritisation
+and the improvements to task cancellation and timeouts. They also show the use
+of these features. Documentation is in the code.
 
+Tests and benchmarks to run against the official and `fast_io` versions:
  * `benchmarks/latency.py` Shows the effect on latency with and without low
  priority usage.
  * `benchmarks/rate.py` Shows the frequency with which uasyncio schedules
  minimal coroutines (coros).
  * `benchmarks/rate_esp.py` As above for ESP32 and ESP8266.
+ * `fast_io/ms_timer.py` An I/O device driver providing a timer with higher
+ precision timing than `wait_ms()` when run under the `fast_io` version.
+ * `fast_io/ms_timer_test.py` Test/demo program for above.
+ * `fast_io/pin_cb.py` An I/O device driver which causes a pin state change to
+ trigger a callback. This is a driver, not an executable test program.
+ * `fast_io/pin_cb_test.py` Demo of above driver: illustrates performance gain
+ under `fast_io`.
+
+Tests requiring the current version of the `fast_io` fork:
  * `benchmarks/rate_fastio.py` Measures the rate at which coros can be scheduled
  if the fast I/O mechanism is used but no I/O is pending.
- * `benchmarks/call_lp.py` Demos low priority callbacks.
+ * `benchmarks/call_lp.py` Demo of low priority callbacks.
  * `benchmarks/overdue.py` Demo of maximum overdue feature.
  * `benchmarks/priority_test.py` Cancellation of low priority coros.
- * `fast_io/ms_timer.py` Provides higher precision timing than `wait_ms()`.
- * `fast_io/ms_timer_test.py` Test/demo program for above.
- * `fast_io/pin_cb.py` Demo of an I/O device driver which causes a pin state
- change to trigger a callback.
- * `fast_io/pin_cb_test.py` Demo of above.
-
-With the exceptions of `call_lp`, `priority` and `rate_fastio`, benchmarks can
-be run against the official and priority versions of usayncio.
+ * `fast_io/fast_can_test.py` Demo of cancellation of paused tasks.
+ * `fast_io/iorw_can.py` Cancellation of task waiting on I/O.
+ * `fast_io/iorw_to.py` Timeouts applies to tasks waiting on I/O.
 
 # 2. Rationale
 
@@ -325,8 +347,8 @@ See [Low priority callbacks](./FASTPOLL.md#35-low-priority-callbacks)
 ## 3.3 Other Features
 
 Variable:  
- * `version` Contains 'fast_io'. Enables the presence of this version to be
- determined at runtime.
+ * `version` Returns a 2-tuple. Current contents ('fast_io', '0.24'). Enables
+ the presence and realease state of this version to be determined at runtime.
 
 Function:
  * `got_event_loop()` No arg. Returns a `bool`: `True` if the event loop has
@@ -348,6 +370,8 @@ bar = Bar()  # Constructor calls get_event_loop()
 # and renders these args inoperative
 loop = asyncio.get_event_loop(runq_len=40, waitq_len=40)
 ```
+This is mainly for retro-fitting to existing classes and functions. The
+preferred approach is to pass the event loop to classes as a constructor arg.
 
 ###### [Contents](./FASTPOLL.md#contents)
 
@@ -415,8 +439,8 @@ priority task to become overdue by more than 1s.
 ### 3.4.1 Task Cancellation and Timeouts
 
 Tasks which yield in a low priority manner may be subject to timeouts or be
-cancelled in the same way as normal tasks. See [Task cancellation](./TUTORIAL.md#36-task-cancellation)
-and [Coroutines with timeouts](./TUTORIAL.md#44-coroutines-with-timeouts).
+cancelled in the same way as normal tasks. See [Task cancellation](./TUTORIAL.md#521-task-cancellation)
+and [Coroutines with timeouts](./TUTORIAL.md#522-coroutines-with-timeouts).
 
 ###### [Contents](./FASTPOLL.md#contents)
 
@@ -468,22 +492,27 @@ Support was finally [added here](https://github.com/micropython/micropython/pull
 
 # 6. Performance
 
-This version is designed to enable existing applications to run without change
-to code and to minimise the effect on raw scheduler performance in the case
-where the added functionality is unused.
+The `fast_io` version is designed to enable existing applications to run
+unchanged and to minimise the effect on raw scheduler performance in cases
+where the priority functionality is unused.
+
+The benchmark `rate.py` measures the rate at which tasks can be scheduled;
+`rate_fastio` is identical except it instantiates an I/O queue and a low
+priority queue. The benchmarks were run on a Pyboard V1.1 under official
+`uasyncio` V2 and under the current `fast_io` version V0.24. Results were as
+follows:
 
-The benchmark `rate.py` measures the rate at which tasks can be scheduled. It
-was run (on a Pyboard V1.1) under official `uasyncio` V2, then under this
-version. The benchmark `rate_fastio` is identical except it instantiates an I/O
-queue and a low priority queue. Results were as follows.
+| Script | Uasyncio version | Period (100 coros) | Overhead | PBD |
+|:------:|:----------------:|:------------------:|:--------:|:---:|
+| rate | Official V2 | 156μs | 0% | 123μs |
+| rate | fast_io | 162μs | 3.4% | 129μs |
+| rate_fastio | fast_io | 206μs | 32% | 181μs |
 
-| Script | Uasyncio version | Period (100 coros) | Overhead |
-|:------:|:----------------:|:------------------:|:--------:|
-| rate | Official V2 | 156μs | 0% |
-| rate | fast_io | 162μs | 3.4% |
-| rate_fastio | fast_io | 206μs | 32% |
+The last column shows times from a Pyboard D SF2W.
 
 If an I/O queue is instantiated I/O is polled on every scheduler iteration
 (that is its purpose). Consequently there is a significant overhead. In
 practice the overhead will increase with the number of I/O devices being
 polled and will be determined by the efficiency of their `ioctl` methods.
+
+Timings for current `fast_io` V0.24 and the original version were identical.

PRIMITIVES.md

@@ -38,7 +38,6 @@ obvious workround is to produce a version with unused primitives removed.
   4.3 [Class NamedTask](./PRIMITIVES.md#43-class-namedtask) Associate tasks with names for cancellation.  
    4.3.1 [Latency and Barrier objects](./PRIMITIVES.md#431-latency-and-barrier-objects)  
    4.3.2 [Custom cleanup](./PRIMITIVES.md#432-custom-cleanup)  
-   4.3.3 [Changes](./PRIMITIVES.md#433-changes) June 2018 asyn API changes affecting cancellation.
 
 ## 1.1 Synchronisation Primitives
 
@@ -456,18 +455,46 @@ loop.run_until_complete(main(loop))
 
 # 4. Task Cancellation
 
-This has been under active development. Existing users please see
-[Changes](./PRIMITIVES.md#433-changes) for recent API changes.
+All current `uasyncio` versions have a `cancel(coro)` function. This works by
+throwing an exception to the coro in a special way: cancellation is deferred
+until the coro is next scheduled. This mechanism works with nested coros.
 
-`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
-is next scheduled. This mechanism works with nested coros. However there is a
-limitation. If a coro issues `await uasyncio.sleep(secs)` or
-`await uasyncio.sleep_ms(ms)` scheduling will not occur until the time has
-elapsed. This introduces latency into cancellation which matters in some
-use-cases. Other potential sources of latency take the form of slow code. 
-`uasyncio` has no mechanism for verifying when cancellation has actually
-occurred. The `asyn.py` library provides solutions in the form of two classes.
+There is a limitation with official `uasyncio` V2.0. In this version a coro
+which is waiting on a `sleep()` or `sleep_ms()` or pending I/O will not get the
+exception until it is next scheduled. This means that cancellation can take a
+long time: there is often a need to be able to verify when this has occurred.
+
+This problem can now be circumvented in two ways both involving running
+unofficial code. The solutions fix the problem by ensuring that the cancelled
+coro is scheduled promptly. Assuming `my_coro` is coded normally the following
+will ensure that cancellation is complete, even if `my_coro` is paused at the
+time of cancellation:
+```python
+my_coro_instance = my_coro()
+loop.add_task(my_coro_instance)
+# Do something
+asyncio.cancel(my_coro_instance)
+await asyncio.sleep(0)
+# The task is now cancelled
+```
+The unofficial solutions are:
+ * To run the `fast_io` version of `uasyncio` presented her, with official
+ MicroPython firmware.
+ * To run [Paul Sokolovsky's Pycopy firmware fork](https://github.com/pfalcon/pycopy)
+ plus `uasyncio` V2.4 from
+ [Paul Sokolovsky's library fork](https://github.com/pfalcon/micropython-lib)
+
+The following describes workrounds for those wishing to run official code (for
+example the current realease build which includes `uasyncio` V2.0). There is
+usually a need to establish when cancellation has occured: the classes and 
+decorators described below facilitate this.
+
+If a coro issues `await uasyncio.sleep(secs)` or `await uasyncio.sleep_ms(ms)`
+scheduling will not occur until the time has elapsed. This introduces latency
+into cancellation which matters in some use-cases. Other potential sources of
+latency take the form of slow code. `uasyncio` V2.0 has no mechanism for
+verifying when cancellation has actually occurred. The `asyn.py` library
+provides solutions in the form of two classes.
 
 These are `Cancellable` and `NamedTask`. The `Cancellable` class allows the
 creation of named groups of tasks which may be cancelled as a group; this
@@ -759,18 +786,4 @@ async def foo():
         return True  # Normal exit
 ```
 
-### 4.3.3 Changes
-
-The `NamedTask` class has been rewritten as a subclass of `Cancellable`. This
-is to simplify the code and to ensure accuracy of the `is_running` method. The
-latest API changes are:  
- * `Cancellable.stopped()` is no longer a public method.
- * `NamedTask.cancel()` is now asynchronous.
- * `NamedTask` and `Cancellable` coros no longer receive a `TaskId` instance as
- their 1st arg.
- * `@asyn.namedtask` still works but is now an alias for `@asyn.cancellable`.
-
-The drive to simplify code comes from the fact that `uasyncio` is itself under
-development. Tracking changes is an inevitable headache.
-
 ###### [Contents](./PRIMITIVES.md#contents)

README.md

@@ -35,23 +35,25 @@ This repository comprises the following parts.
 
 # 2. Version and installation of uasyncio
 
-As of 24th Dec 2018 Paul Sokolovsky has released uasyncio V2.2. This version
+Paul Sokolovsky (`uasyncio` author) has released `uasyncio` V2.4. This version
 is on PyPi and requires his [Pycopy](https://github.com/pfalcon/micropython)
-fork of MicroPython.
+fork of MicroPython firmware. His `uasyncio` code may also be found in
+[his fork of micropython-lib](https://github.com/pfalcon/micropython-lib).
 
 I support only the official build of MicroPython. The library code guaranteed
 to work with this build is in [micropython-lib](https://github.com/micropython/micropython-lib).
-Most of the resources in here should work with Paul's forks (the great majority
-work with CPython). I am unlikely to fix issues which are only evident in an
-unofficial fork.
+Most of the resources in here should work with Paul's forks (most work with
+CPython).
 
-The documentation and code in this repository assume `uasyncio` version
-2.0.x, the version in [micropython-lib](https://github.com/micropython/micropython-lib).
-This requires firmware dated 22nd Feb 2018 or later. Use of the stream I/O
-mechanism requires firmware after 17th June 2018.
+Most documentation and code in this repository assumes the current official
+version of `uasyncio`. This is V2.0 from
+[micropython-lib](https://github.com/micropython/micropython-lib).
+If release build of MicroPython V1.10 or later is used, V2.0 is incorporated
+and no installation is required. Some examples illustrate the features of the
+`fast_io` fork and therefore require this version.
 
 See [tutorial](./TUTORIAL.md#installing-uasyncio-on-bare-metal) for
-installation instructions.
+installation instructions where a realease build is not used.
 
 # 3. uasyncio development state
 
@@ -114,27 +116,22 @@ providing greater control over scheduling behaviour.
 
 To take advantage of the reduced latency device drivers should be written to
 employ stream I/O. To operate at low latency they are simply run under the
-`fast_io` version. The [tutorial](./TUTORIAL.md#54-writing-streaming-device-drivers)
+`fast_io` version. The [tutorial](./TUTORIAL.md#64-writing-streaming-device-drivers)
 has details of how to write streaming drivers.
 
+The current `fast_io` version 0.24 fixes an issue with task cancellation and
+timeouts. In version 2.0, where a coroutine is waiting on a `sleep()` or on
+I/O, a timeout or cancellation are deferred until the coroutine is next
+scheduled. This introduces uncertainty into when the coroutine is stopped. This
+issue is also addressed in Paul Sokolovsky's fork.
+
 ## 4.1 A Pyboard-only low power module
 
 This is documented [here](./lowpower/README.md). In essence a Python file is
 placed on the device which configures the `fast_io` version of `uasyncio` to
 reduce power consumption at times when it is not busy. This provides a means of
 using `uasyncio` in battery powered projects.
 
-## 4.2 Historical note
-
-This repo formerly included `asyncio_priority.py` which is obsolete. Its main
-purpose was to provide a means of servicing fast hardware devices by means of
-coroutines running at a high priority. This was essentially a workround.
-
-The official firmware now includes
-[this major improvement](https://github.com/micropython/micropython/pull/3836)
-which offers a much more efficient way of achieving the same end using stream
-I/O and efficient polling using `select.poll`.
-
 # 5. The asyn.py library
 
 This library ([docs](./PRIMITIVES.md)) provides 'micro' implementations of the