Tutorial: further update to stream I/O.

Author: peterhinch

TUTORIAL.md

@@ -119,20 +119,22 @@ and rebuilding.
 
   4.5 [Exceptions](./TUTORIAL.md#45-exceptions)
 
- 5. [Device driver examples](./TUTORIAL.md#5-device-driver-examples)
+ 5. [Interfacing hardware](./TUTORIAL.md#5-interfacing-hardware)
 
-  5.1 [Using the IORead mechnanism](./TUTORIAL.md#51-using-the-ioread-mechanism)
+  5.1 [Timing issues](./TUTORIAL.md#51-timing-issues)
 
-   5.1.1 [A UART driver example](./TUTORIAL.md#511-a-uart-driver-example)
+  5.2 [Polling hardware with a coroutine](./TUTORIAL.md#52-polling-hardware-with-a-coroutine)
 
-  5.2 [Writing IORead device drivers](./TUTORIAL.md#52-writing-ioread-device-drivers)
+  5.3 [Using the IORead mechnanism](./TUTORIAL.md#53-using-the-ioread-mechanism)
 
-  5.3 [Polling hardware without IORead](./TUTORIAL.md#53-polling-hardware-without-ioread)
+   5.3.1 [A UART driver example](./TUTORIAL.md#531-a-uart-driver-example)
 
-  5.4 [A complete example: aremote.py](./TUTORIAL.md#54-a-complete-example-aremotepy)
+  5.4 [Writing IORead device drivers](./TUTORIAL.md#54-writing-ioread-device-drivers)
+
+  5.5 [A complete example: aremote.py](./TUTORIAL.md#55-a-complete-example-aremotepy)
   A driver for an IR remote control receiver.
 
-  5.5 [Driver for HTU21D](./TUTORIAL.md#55-htu21d-environment-sensor) A
+  5.6 [Driver for HTU21D](./TUTORIAL.md#56-htu21d-environment-sensor) A
   temperature and humidity sensor.
 
  6. [Hints and tips](./TUTORIAL.md#6-hints-and-tips)
@@ -380,7 +382,7 @@ This is generally highly desirable, but it does introduce uncertainty in the
 timing as the calling routine will only be rescheduled when the one running at
 the appropriate time has yielded. The amount of latency depends on the design
 of the application, but is likely to be on the order of tens or hundreds of ms;
-this is discussed further in [Section 5](./TUTORIAL.md#5-device-driver-examples).
+this is discussed further in [Section 5](./TUTORIAL.md#5-interfacing-hardware).
 
 Very precise delays may be issued by using the `utime` functions `sleep_ms`
 and `sleep_us`. These are best suited for short delays as the scheduler will
@@ -1006,46 +1008,161 @@ a keyboard interrupt should trap the exception at the event loop level.
 
 ###### [Contents](./TUTORIAL.md#contents)
 
-# 5 Device driver examples
-
-Many devices such as sensors are read-only in nature and need to be polled to
-acquire data. In the case of a driver written in Python this must be done by
-having a coro which does this periodically. This may present problems if there
-is a requirement for rapid polling owing to the round-robin nature of uasyncio
-scheduling: the coro will compete for execution with others. There are two
-solutions to this. The official solution is to delegate polling to the
-scheduler using the IORead mechanism. This is currently subject to limitations.
-
-An alternative is to use the experimental version of uasyncio presented
-[here](./FASTPOLL.md).
-
-Note that where a very repeatable polling interval is required, it should be
-done using a hardware timer with a hard interrupt callback. For "very"
-repeatable read microsecond level (depending on platform).
-
-In many cases less precise timing is acceptable. The definition of "less" is
-application dependent but the latency associated with scheduling the coro which
-is performing the polling may be variable on the order of tens or hundreds of
-milliseconds. Latency is determined as follows. When `await asyncio.sleep(0)`
-is issued all other pending coros will be scheduled in "fair round-robin"
-fashion before it is re-scheduled. Thus its worst-case latency may be
+# 5 Interfacing hardware
+
+At heart all interfaces between `uasyncio` and external asynchronous events
+rely on polling. Hardware requiring a fast response may use an interrupt. But
+the interface between the interrupt service routine (ISR) and a user coro will
+be polled. For example the ISR might trigger an `Event` or set a global flag,
+while a coroutine awaiting the outcome polls the object each time it is
+scheduled.
+
+Polling may be effected in two ways, explicitly or implicitly. The latter is
+performed by using the `IORead` mechanism which is a system designed for stream
+devices such as UARTs and sockets. At its simplest explicit polling may consist
+of code like this:
+
+```python
+async def poll_my_device():
+    global my_flag  # Set by device ISR
+    while True:
+        if my_flag:
+            my_flag = False
+            # service the device
+        await asyncio.sleep(0)
+```
+
+In place of a global, an instance variable, an `Event` object or an instance of
+an awaitable class might be used. Explicit polling is discussed
+further [below](./TUTORIAL.md#52-polling-hardware-with-a-coroutine).
+
+Implicit polling consists of designing the driver to behave like a stream I/O
+device such as a socket or UART, using `IORead`. This polls devices using
+Python's `select.poll` system: because the polling is done in C it is faster
+and more efficient than explicit polling. The use of `IORead` is discussed
+[here](./TUTORIAL.md#53-using-the-ioread-mechanism).
+
+###### [Contents](./TUTORIAL.md#contents)
+
+## 5.1 Timing issues
+
+Both explicit and implicit polling are currently based on round-robin
+scheduling. Assume I/O is operating concurrently with N user coros each of
+which yields with a zero delay. When I/O has been serviced it will next be
+polled once all user coros have been scheduled. The implied latency needs to be
+considered in the design. I/O channels may require buffering, with an ISR
+servicing the hardware in real time from buffers and coroutines filling or
+emptying the buffers in slower time.
+
+The possibility of overrun also needs to be considered: this is the case where
+something being polled by a coroutine occurs more than once before the coro is
+actually scheduled.
+
+Another timing issue is the accuracy of delays. If a coro issues
+
+```python
+    await asyncio.sleep_ms(t)
+    # next line
+```
+
+the scheduler guarantees that execution will pause for at least `t`ms. The
+actual delay may be greater depending on the system state when `t` expires.
+If, at that time, all other coros are waiting on nonzero delays, the next line
+will immediately be scheduled. But if other coros are pending execution (either
+because they issued a zero delay or because their time has also elapsed) they
+may be scheduled first. This introduces a timing uncertainty into the `sleep()`
+and `sleep_ms()` functions. The worst-case value for this overrun may be
 calculated by summing, for every other coro, the worst-case execution time
 between yielding to the scheduler.
 
-If `await asyncio.sleep_ms(t)` is issued where t > 0 the coro is guaranteed not
-to be rescheduled until t has elapsed. If, at that time, all other coros are
-waiting on nonzero delays, it will immediately be scheduled. But if other coros
-are pending execution (either because they issued a zero delay or because their
-time has elapsed) they may be scheduled first. This introduces a timing
-uncertainty into the `sleep()` and `sleep_ms()` functions. The worst-case value
-for this may be calculated as above.
+There is an experimental version of uasyncio presented [here](./FASTPOLL.md).
+This provides for callbacks which run on every iteration of the scheduler
+enabling a coro to wait on an event with much reduced latency. It is hoped
+that improvements to `uasyncio` will remove the need for this in future.
+
+###### [Contents](./TUTORIAL.md#contents)
 
-[This document](./FASTPOLL.md) describes an experimental version of uasyncio
-which offers a means of reducing this latency for critical tasks.
+## 5.2 Polling hardware with a coroutine
+
+This is a simple approach, but is most appropriate to hardware which may be
+polled at a relatively low rate. This is primarily because polling with a short
+(or zero) polling interval may cause the coro to consume more processor time
+than is desirable.
+
+The example `apoll.py` demonstrates this approach by polling the Pyboard
+accelerometer at 100ms intervals. It performs some simple filtering to ignore
+noisy samples and prints a message every two seconds if the board is not moved.
+
+Further examples may be found in `aswitch.py` which provides drivers for
+switch and pushbutton devices.
+
+An example of a driver for a device capable of reading and writing is shown
+below. For ease of testing Pyboard UART 4 emulates the notional device. The
+driver implements a `RecordOrientedUart` class, where data is supplied in
+variable length records consisting of bytes instances. The object appends a
+delimiter before sending and buffers incoming data until the delimiter is
+received. This is a demo and is an inefficient way to use a UART compared to
+IORead.
+
+For the purpose of demonstrating asynchronous transmission we assume the
+device being emulated has a means of checking that transmission is complete
+and that the application requires that we wait on this. Neither assumption is
+true in this example but the code fakes it with `await asyncio.sleep(0.1)`.
+
+Link pins X1 and X2 to run.
+
+```python
+import uasyncio as asyncio
+from pyb import UART
+
+class RecordOrientedUart():
+    DELIMITER = b'\0'
+    def __init__(self):
+        self.uart = UART(4, 9600)
+        self.data = b''
+
+    def __await__(self):
+        data = b''
+        while not data.endswith(self.DELIMITER):
+            yield from asyncio.sleep(0) # Neccessary because:
+            while not self.uart.any():
+                yield from asyncio.sleep(0) # timing may mean this is never called
+            data = b''.join((data, self.uart.read(self.uart.any())))
+        self.data = data
+
+    __iter__ = __await__  # workround for issue #2678
+
+    async def send_record(self, data):
+        data = b''.join((data, self.DELIMITER))
+        self.uart.write(data)
+        await self._send_complete()
+
+    # In a real device driver we would poll the hardware
+    # for completion in a loop with await asyncio.sleep(0)
+    async def _send_complete(self):
+        await asyncio.sleep(0.1)
+
+    def read_record(self):  # Synchronous: await the object before calling
+        return self.data[0:-1] # Discard delimiter
+
+async def run():
+    foo = RecordOrientedUart()
+    rx_data = b''
+    await foo.send_record(b'A line of text.')
+    for _ in range(20):
+        await foo  # Other coros are scheduled while we wait
+        rx_data = foo.read_record()
+        print('Got: {}'.format(rx_data))
+        await foo.send_record(rx_data)
+        rx_data = b''
+
+loop = asyncio.get_event_loop()
+loop.run_until_complete(run())
+```
 
 ###### [Contents](./TUTORIAL.md#contents)
 
-## 5.1 Using the IORead Mechanism
+## 5.3 Using the IORead Mechanism
 
 This can be illustrated using a Pyboard UART. The following code sample
 demonstrates concurrent I/O on one UART. To run, link Pyboard pins X1 and X2
@@ -1077,8 +1194,8 @@ loop.run_forever()
 The supporting code may be found in `__init__.py` in the `uasyncio` library.
 The mechanism works because the device driver (written in C) implements the
 following methods: `ioctl`, `read`, `readline` and `write`. See
-[section 5.2](./TUTORIAL.md#52-writing-ioread-device-drivers) for details on
-how such drivers may be written in Python.
+[Writing IORead device drivers](./TUTORIAL.md#54-writing-ioread-device-drivers)
+for details on how such drivers may be written in Python.
 
 A UART can receive data at any time. The IORead mechanism checks for pending
 incoming characters whenever the scheduler has control. When a coro is running
@@ -1089,7 +1206,7 @@ avoid buffer overflows and data loss. This can be ameliorated by using a larger
 UART read buffer or a lower baudrate. Alternatively hardware flow control will
 provide a solution if the data source supports it.
 
-### 5.1.1 A UART driver example
+### 5.3.1 A UART driver example
 
 The program `auart_hd.py` illustrates a method of communicating with a half
 duplex device such as one responding to the modem 'AT' command set. Half duplex
@@ -1113,7 +1230,7 @@ returned. See the code comments for more details.
 
 ###### [Contents](./TUTORIAL.md#contents)
 
-## 5.2 Writing IORead device drivers
+## 5.4 Writing IORead device drivers
 
 The `IORead` mechanism is provided to support I/O to stream devices. Its
 typical use is to support streaming I/O devices such as UARTs and sockets. The
@@ -1123,8 +1240,8 @@ handlers for any devices which are ready. This is more efficient than running
 multiple coros each polling a device.
 
 It should be noted that currently the task polling I/O devices effectively runs
-in round-robin fashion along with other coroutines. This is arguably sub
-optimal: [see this GitHub RFC](https://github.com/micropython/micropython/issues/2664).
+in round-robin fashion along with other coroutines. Arguably this could be
+improved: [see this GitHub RFC](https://github.com/micropython/micropython/issues/2664).
 
 A device driver capable of employing the IORead mechanism may support
 `StreamReader`, `StreamWriter` instances or both. A readable device must
@@ -1178,89 +1295,7 @@ write-only.
 
 ###### [Contents](./TUTORIAL.md#contents)
 
-## 5.3 Polling hardware without IORead
-
-This is a simple approach, but is only appropriate to hardware which is to be
-polled at a relatively low rate. This is for two reasons. Firstly the variable
-latency caused by the execution of other coros will result in variable polling
-intervals - this may or may not matter depending on the device and application.
-Secondly, attempting to poll with a short polling interval may cause the coro
-to consume more processor time than is desirable.
-
-The example `apoll.py` demonstrates this approach by polling the Pyboard
-accelerometer at 100ms intervals. It performs some simple filtering to ignore
-noisy samples and prints a message every two seconds if the board is not moved.
-
-Further examples may be found in `aswitch.py` which provides drivers for
-switch and pushbutton devices.
-
-An example of a driver for a device capable of reading and writing is shown
-below. For ease of testing Pyboard UART 4 emulates the notional device. The
-driver implements a `RecordOrientedUart` class, where data is supplied in
-variable length records consisting of bytes instances. The object appends a
-delimiter before sending and buffers incoming data until the delimiter is
-received. This is a demo and is an inefficient way to use a UART compared to
-IORead.
-
-For the purpose of demonstrating asynchronous transmission we assume the
-device being emulated has a means of checking that transmission is complete
-and that the application requires that we wait on this. Neither assumption is
-true in this example but the code fakes it with `await asyncio.sleep(0.1)`.
-
-Link pins X1 and X2 to run.
-
-```python
-import uasyncio as asyncio
-from pyb import UART
-
-class RecordOrientedUart():
-    DELIMITER = b'\0'
-    def __init__(self):
-        self.uart = UART(4, 9600)
-        self.data = b''
-
-    def __await__(self):
-        data = b''
-        while not data.endswith(self.DELIMITER):
-            yield from asyncio.sleep(0) # Neccessary because:
-            while not self.uart.any():
-                yield from asyncio.sleep(0) # timing may mean this is never called
-            data = b''.join((data, self.uart.read(self.uart.any())))
-        self.data = data
-
-    __iter__ = __await__  # workround for issue #2678
-
-    async def send_record(self, data):
-        data = b''.join((data, self.DELIMITER))
-        self.uart.write(data)
-        await self._send_complete()
-
-    # In a real device driver we would poll the hardware
-    # for completion in a loop with await asyncio.sleep(0)
-    async def _send_complete(self):
-        await asyncio.sleep(0.1)
-
-    def read_record(self):  # Synchronous: await the object before calling
-        return self.data[0:-1] # Discard delimiter
-
-async def run():
-    foo = RecordOrientedUart()
-    rx_data = b''
-    await foo.send_record(b'A line of text.')
-    for _ in range(20):
-        await foo  # Other coros are scheduled while we wait
-        rx_data = foo.read_record()
-        print('Got: {}'.format(rx_data))
-        await foo.send_record(rx_data)
-        rx_data = b''
-
-loop = asyncio.get_event_loop()
-loop.run_until_complete(run())
-```
-
-###### [Contents](./TUTORIAL.md#contents)
-
-## 5.4 A complete example: aremote.py
+## 5.5 A complete example: aremote.py
 
 This may be found in the `nec_ir` directory. Its use is documented
 [here](./nec_ir/README.md). The demo provides a complete device driver example:
@@ -1277,7 +1312,7 @@ any asyncio latency when setting its delay period.
 
 ###### [Contents](./TUTORIAL.md#contents)
 
-## 5.5 HTU21D environment sensor
+## 5.6 HTU21D environment sensor
 
 This chip provides accurate measurements of temperature and humidity. The
 driver is documented [here](./htu21d/README.md). It has a continuously running