Doc improvements.

Author: peterhinch

FASTPOLL.md

@@ -1,22 +1,19 @@
 # fast_io: A modified version of uasyncio
 
-MicroPython firmware now enables device drivers for stream devices to be
-written in Python, via `uio.IOBase`. This mechanism can be applied to any
-situation where a piece of hardware or an asynchronously set flag needs to be
-polled. Such polling is efficient because it is handled in C using
-`select.poll`, and because the coroutine accessing the device is descheduled
-until polling succeeds.
-
-Unfortunately official `uasyncio` polls I/O with a relatively high degree of
-latency. It also has a bug whereby bidirectional devices such as UARTS can
-fail to handle concurrent input and output.
+This version is a "drop in" replacement for official `uasyncio`. Existing
+applications should run under it unchanged and with essentially identical
+performance.
 
-This version has the following changes:
+This version has the following features:
  * 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.
  * Callbacks can similarly be scheduled with low priority. 
- * The bug with read/write device drivers is fixed.
+ * A [bug](https://github.com/micropython/micropython/pull/3836#issuecomment-397317408)
+ whereby bidirectional devices such as UARTS can fail to handle concurrent
+ input and output is fixed.
+ * It is compatible with `rtc_time.py` for micro-power applications documented
+ [here](./lowpower/README.md).
  * An assertion failure is produced if `create_task` or `run_until_complete`
  is called with a generator function
  [PR292](https://github.com/micropython/micropython-lib/pull/292). This traps
@@ -34,13 +31,8 @@ version.
 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
-should be deleted from your system.
-
-The facility for low priority coros formerly provided by `asyncio_priority.py`
-is now implemented.
-
-This version also provides for ultra low power consumption using a module
-documented [here](./lowpower/README.md).
+should be deleted from your system. The facility for low priority coros
+formerly provided by `asyncio_priority.py` is now implemented.
 
 ###### [Main README](./README.md)
 
@@ -61,6 +53,7 @@ documented [here](./lowpower/README.md).
   3.5 [Low priority callbacks](./FASTPOLL.md#35-low-priority-callbacks)  
  4. [ESP Platforms](./FASTPOLL.md#4-esp-platforms)  
  5. [Background](./FASTPOLL.md#4-background)  
+ 6. [Performance](./FASTPOLL.md#6-performance)
 
 # 1. Installation
 
@@ -104,6 +97,16 @@ be run against the official and priority versions of usayncio.
 
 # 2. Rationale
 
+MicroPython firmware now enables device drivers for stream devices to be
+written in Python, via `uio.IOBase`. This mechanism can be applied to any
+situation where a piece of hardware or an asynchronously set flag needs to be
+polled. Such polling is efficient because it is handled in C using
+`select.poll`, and because the coroutine accessing the device is descheduled
+until polling succeeds.
+
+Unfortunately official `uasyncio` polls I/O with a relatively high degree of
+latency.
+
 Applications may need to poll a hardware device or a flag set by an interrupt
 service routine (ISR). An overrun may occur if the scheduling of the polling
 coroutine (coro) is subject to excessive latency. Fast devices with interrupt
@@ -454,3 +457,25 @@ fast scheduling took place
 [in issue 2664](https://github.com/micropython/micropython/issues/2664).
 
 Support was finally [added here](https://github.com/micropython/micropython/pull/3836).
+
+# 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 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 |
+| --- | --- | --- |
+| rate | Official V2 | 156μs | 0% |
+| rate | fast_io | 162μs | 3.4% |
+| rate_fastio | fast_io | 206μs | 32% |
+
+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.

README.md

@@ -1,13 +1,13 @@
 # 1. The MicroPython uasyncio library
 
-This GitHub repository consists of the following parts. Firstly a modified
-`fast_io` version of `uasyncio` offering some benefits over the official
-version.
+This repository comprises the following parts.  
+ 1. A modified [fast_io](./FASTPOLL.md) version of `uasyncio`. This is a "drop
+ in" replacement for the official version providing additional functionality.
+ 2. A module enabling the `fast_io` version to run with very low power draw.
+ 3. Resources for users of official or `fast_io` versions:
 
-Secondly the following resources relevant to users of official or `fast_io`
-versions:
  * [A tutorial](./TUTORIAL.md) An introductory tutorial on asynchronous
- programming and the use of the uasyncio library (asyncio subset).
+ programming and the use of the `uasyncio` library (asyncio subset).
  * [Asynchronous device drivers](./DRIVERS.md). A module providing drivers for
  devices such as switches and pushbuttons.
  * [Synchronisation primitives](./PRIMITIVES.md). Provides commonly used
@@ -29,34 +29,9 @@ versions:
  * [Under the hood](./UNDER_THE_HOOD.md) A guide to help understand the
  `uasyncio` code. For scheduler geeks and those wishing to modify `uasyncio`.
 
-## 1.1 The "fast_io" version.
-
-This repo included `asyncio_priority.py` which is now deprecated. Its primary
-purpose was to provide a means of servicing fast hardware devices by means of
-coroutines running at a high priority. The official firmware now includes
-[this major improvement](https://github.com/micropython/micropython/pull/3836)
-which offers a much more efficient way of achieving this end. The tutorial has
-details of how to use this.
-
-The current `uasyncio` suffers from high levels of latency when scheduling I/O
-in typical applications. It also has an issue which can cause bidirectional
-devices such as UART's to block.
-
-A modified version of `uasyncio` is described [here](./FASTPOLL.md) which
-provides an option for I/O scheduling with much reduced latency. It also fixes
-the bug. It is hoped that these changes will be accepted into mainstream in due
-course.
-
-### 1.1.1 A Pyboard-only low power version
-
-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 the library on battery powered projects.
-
 # 2. Version and installation of uasyncio
 
-The documentation and code in this repository are based on `uasyncio` version
+The documentation and code in this repository assume `uasyncio` version
 2.0, which is the version on PyPi and in the official micropython-lib. This
 requires firmware dated 22nd Feb 2018 or later. Use of the stream I/O mechanism
 requires firmware after 17th June 2018.
@@ -114,7 +89,32 @@ The `loop.time` method returns an integer number of milliseconds whereas
 CPython returns a floating point number of seconds. `call_at` follows the
 same convention.
 
-# 4. The asyn.py library
+# 4. The "fast_io" version.
+
+Official `uasyncio` suffers from high levels of latency when scheduling I/O in
+typical applications. It also has an issue which can cause bidirectional
+devices such as UART's to block. The `fast_io` version fixes the bug. It also
+provides a facility for reducing I/O latency which can substantially improve
+the performance of stream I/O drivers. It provides other features aimed at
+providing greater control over scheduling behaviour.
+
+## 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 replaced. Its main
+purpose was to provide a means of servicing fast hardware devices by means of
+coroutines running at a high priority. The official firmware now includes
+[this major improvement](https://github.com/micropython/micropython/pull/3836)
+which offers a much more efficient way of achieving this end. The tutorial has
+details of how to use this.
+
+# 5. The asyn.py library
 
 This library ([docs](./PRIMITIVES.md)) provides 'micro' implementations of the
 `asyncio` synchronisation primitives.

benchmarks/rate.py

@@ -3,7 +3,9 @@
 # This measures the rate at which uasyncio can schedule a minimal coro which
 # mereley increments a global.
 
-# Outcome: minimal coros are scheduled at an interval of ~150us
+# Outcome: 100 minimal coros are scheduled at an interval of ~156μs on official
+# uasyncio V2. On fast_io version 0.1 (including low priority) at 162μs.
+# fast_io overhead is < 4%
 
 import uasyncio as asyncio
 

benchmarks/rate_fastio.py

@@ -4,7 +4,8 @@
 # This measures the rate at which uasyncio can schedule a minimal coro which
 # mereley increments a global.
 
-# Outcome: minimal coros are scheduled at an interval of ~200us
+# This is identical to rate.py but instantiates io and lp queues
+# Outcome: minimal coros are scheduled at an interval of ~206μs
 
 import uasyncio as asyncio
 
@@ -41,7 +42,7 @@ async def test():
     done = True
 
 ntasks = max(num_coros) + 2
-loop = asyncio.get_event_loop(ntasks, ntasks, 6)
+loop = asyncio.get_event_loop(ntasks, ntasks, 6, 6)
 loop.create_task(test())
 loop.run_until_complete(report())