micropython-samples/uasyncio_iostream

1. Changes to usayncio

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.
3. Primitive class has methods common to most synchronisation primitives. Avoids the need for primitives to access the task queue directly.
4. Add .priority method to Stream class. Enables I/O to be handled at high priority on a per-device basis.
5. Rename task queue class TQueue to avoid name clash with Queue primitive.

Minor changes

1. Move StreamReader and StreamWriter assignments out of legacy section of code: these classes exist in asyncio 3.8.
2. .CreateTask produces an assertion fail if called with a generator function. Avoids obscure traceback if someone omits the parens.
3. Add machine readable version info. Useful in testing.

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 subclass uasyncio.Primitive.

1. Event: Moved to separate module.
2. Lock: Kevin Köck's solution.
3. Queue: Paul's solution adapted for efficiency.
4. Semaphore: Also implements BoundedSemaphore.
5. Condition.

3. Other primitives

Included as examples of user-contributed primitives - see final section.

1. Message: Awaitable Event subclass with a data payload.
2. Barrier: Multiple tasks wait until all are either waiting on a Barrier instance or have triggered the instance without waiting. Similar to gather without the controlling coro: a barrier is shared between peers and may be used in loops.

4. Test scripts

Hopefully these are self-documenting on import.

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.
4. test_can.py Demonstrates differences in behaviour between CPython 3.8 and MicroPython. See code comments.

5. CPython compatibility of user primitives

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.

5.1 Directory structure of primitives

MicroPython optimised primitives are in uasyncio/. Primitives compatible with asyncio are in primitives/.

6. Future uasyncio implementations

If part of uasyncio is to be implemented in C, it would be good if the following capabilities were retained:

1. The ability to subclass the asyncio compatible primitives.
2. The ability to subclass uasyncio.Primitive (or provide other access to that functionality).
3. A means of replacing the timebase by one based on the RTC for low power applications.
4. A means of creating awaitable classes (e.g. __iter__).

7. Revisiting topics discussed via email

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.

Here are my observations on issues previously discussed.

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.

up = False  # Running under MicroPython?
try:
    import uasyncio as asyncio
    up = True  # Or can use sys.implementation.name
except ImportError:
    import asyncio

async def times_two(n):  # Coro to await
    await asyncio.sleep(1)
    return 2 * n

class Foo():
    def __await__(self):
        res = 1
        for n in range(5):
            print('__await__ called')
            if up:  # MicroPython
                res = yield from times_two(res)
            else:  # CPython
                res = yield from times_two(res).__await__()
        return res

    __iter__ = __await__  # MicroPython compatibility

async def bar():
    foo = Foo()  # foo is awaitable
    print('waiting for foo')
    res = await foo  # Retrieve value
    print('done', res)

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:

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.