uasyncio README changes.

uasyncio_iostream/README.md

@@ -1,7 +1,8 @@
-# Changes to usayncio
+# 1. Changes to usayncio
 
-This archive contains suggestions for changes to new `uasyncio`. Item 3 below
-added 2 Dec, task queue name reverted to `_queue` as this can now be private.
+This archive contains suggestions for changes to new `uasyncio`.
+
+## 1.1 Changes implemented
 
  1. Implement as a Python package.
  2. Implement synchronisation primitives as package modules to conserve RAM.
@@ -11,7 +12,7 @@ added 2 Dec, task queue name reverted to `_queue` as this can now be private.
  priority on a per-device basis.
  5. Rename task queue class `TQueue` to avoid name clash with Queue primitive.
 
-## Minor changes
+### Minor changes
 
  1. Move `StreamReader` and `StreamWriter` assignments out of legacy section of
  code: these classes exist in `asyncio` 3.8.
@@ -19,10 +20,17 @@ added 2 Dec, task queue name reverted to `_queue` as this can now be private.
  Avoids obscure traceback if someone omits the parens.
  3. Add machine readable version info. Useful in testing.
 
-# CPython-compatible synchronisation primitives
+## 1.2 Suggested changes
+
+I haven't implemented these.
+
+ 1. Make `Event.set` capable of being triggered from an ISR.
+ 2. Implement `wait_for_ms` as per V2.
+
+# 2. CPython-compatible synchronisation primitives
 
 These aim to work efficiently with the new version. All are separate modules to
-conserve RAM. Items 1-4 use classes based on `uasyncio.Primitive`.
+conserve RAM. Items 1-4 subclass `uasyncio.Primitive`.
 
  1. `Event`: Moved to separate module.
  2. `Lock`: Kevin Köck's solution.
@@ -30,7 +38,7 @@ conserve RAM. Items 1-4 use classes based on `uasyncio.Primitive`.
  4. `Semaphore`: Also implements `BoundedSemaphore`.
  5. `Condition`.
 
-# Other primitives
+# 3. Other primitives
 
 Included as examples of user-contributed primitives - see final section.
 
@@ -40,33 +48,32 @@ Included as examples of user-contributed primitives - see final section.
  without the controlling coro: a barrier is shared between peers and may be
  used in loops.
 
-# Test scripts
+# 4. Test scripts
 
 Hopefully these are self-documenting on import.
 
- 1. `prim_test.py` Tests for synchronisation primitives.
+ 1. `prim_test.py` Tests for synchronisation primitives. Runs on MicroPython and
+ CPython V3.5-3.8. Demonstrates that MicroPython primitives behave similarly to
+ native CPython ones.
  2. `test_fast_scheduling.py` Demonstrates difference between normal and priority
  I/O scheduling. Runs on Pyboard.
  3. `ms_timer.py` and `ms_timer_test.py` A practical use of priority scheduling to
  implement a timer with higher precision than `asyncio.sleep_ms`. Runs on Pyboard.
 
-# CPython compatibility
+# 5. CPython compatibility of user primitives
 
-`prim_test.py` runs on MicroPython or CPython 3.8, demonstrating that MicroPython
-primitives behave similarly to the native CPython ones.
-
-`Message` is common to CPython and MicroPython.
+`Message` is common to CPython and MicroPython.  
 There are two implementations of `Barrier` with the same functionality: a CPython
 version and a MicroPython version with specific optimisations. The `Barrier` class
 is loosely based on
 [a Microsoft concept](https://docs.microsoft.com/en-us/windows/win32/sync/synchronization-barriers).
 
-## Directory structure
+## 5.1 Directory structure of primitives
 
 MicroPython optimised primitives are in `uasyncio/`. Primitives compatible with
 `asyncio` are in `primitives/`.
 
-# Future uasyncio implementations
+# 6. Future uasyncio implementations
 
 If part of `uasyncio` is to be implemented in C, it would be good if the following
 capabilities were retained to facilitate writing efficient add-on modules along the
@@ -78,17 +85,19 @@ lines of the `Message` and `Barrier` classes:
 The mechanism for doing these things might change, but it would be a shame to lose
 the capability.
 
-# Suggestion
+# 7. Revisiting topics discussed via email
 
-Implement `wait_for_ms` as per V2.
+I am revising my tutorial to promote Python 3.8 syntax and to verify that code
+samples run under MicroPython and CPython 3.8. I'm removing references to event
+loop methods except for one minor section. This describes how to code for
+compatibility with CPython versions 3.5-3.7.
 
-# Awaitable classes
+Here are my observations on issues previously discussed.
 
-I reviewed the code samples in my tutorial: with minor changes to remove event
-loop methods they will run under CPython 3.8 and the new uasyncio without
-version-specific code. The one exception remains awaitable classes. The `Foo`
-class works under both versions but isn't pretty. I guess this is a minor
-problem: a similar hack is required for V2 and nobody has complained.
+## 7.1 Awaitable classes
+
+I now have portable code which produces no syntax errors under CPython 3.8. It
+is arguably hacky but a similar hack is required for V2. Nobody has complained.
 ```python
 up = False  # Running under MicroPython?
 try:
@@ -122,3 +131,30 @@ async def bar():
 
 asyncio.run(bar())
 ```
+
+## 7.2 run_forever() behaviour
+
+In an email I commented that the following code sample never terminates under
+CPython 3.8, whereas under MicroPython it does:
+```python
+try:
+    import asyncio
+except ImportError:
+    import uasyncio as asyncio
+
+async def test():
+    print("test")
+    for _ in range(2):
+        await asyncio.sleep(0)
+        print('test2')
+        await asyncio.sleep(0.5)
+    print('Done')
+
+loop=asyncio.get_event_loop()
+loop.create_task(test())
+loop.run_forever()
+# asyncio.run(test())
+```
+While the observation is true, using the preferred (commented out) syntax it
+terminates in CPython 3.8 and in MicroPython. My view is that it's not worth
+fixing.