diff --git a/docs/library/uasyncio.rst b/docs/library/asyncio.rst similarity index 92% rename from docs/library/uasyncio.rst rename to docs/library/asyncio.rst index 4cbcfa9f98..9a2c14e7e0 100644 --- a/docs/library/uasyncio.rst +++ b/docs/library/asyncio.rst @@ -1,7 +1,7 @@ -:mod:`uasyncio` --- asynchronous I/O scheduler -============================================== +:mod:`asyncio` --- asynchronous I/O scheduler +============================================= -.. module:: uasyncio +.. module:: asyncio :synopsis: asynchronous I/O scheduler for writing concurrent code |see_cpython_module| @@ -9,27 +9,27 @@ Example:: - import uasyncio + import asyncio async def blink(led, period_ms): while True: led.on() - await uasyncio.sleep_ms(5) + await asyncio.sleep_ms(5) led.off() - await uasyncio.sleep_ms(period_ms) + await asyncio.sleep_ms(period_ms) async def main(led1, led2): - uasyncio.create_task(blink(led1, 700)) - uasyncio.create_task(blink(led2, 400)) - await uasyncio.sleep_ms(10_000) + asyncio.create_task(blink(led1, 700)) + asyncio.create_task(blink(led2, 400)) + await asyncio.sleep_ms(10_000) # Running on a pyboard from pyb import LED - uasyncio.run(main(LED(1), LED(2))) + asyncio.run(main(LED(1), LED(2))) # Running on a generic board from machine import Pin - uasyncio.run(main(Pin(1), Pin(2))) + asyncio.run(main(Pin(1), Pin(2))) Core functions -------------- @@ -71,9 +71,9 @@ Additional functions than *timeout* seconds. If *awaitable* is not a task then a task will be created from it. - If a timeout occurs, it cancels the task and raises ``uasyncio.TimeoutError``: + If a timeout occurs, it cancels the task and raises ``asyncio.TimeoutError``: this should be trapped by the caller. The task receives - ``uasyncio.CancelledError`` which may be ignored or trapped using ``try...except`` + ``asyncio.CancelledError`` which may be ignored or trapped using ``try...except`` or ``try...finally`` to run cleanup code. Returns the return value of *awaitable*. @@ -108,7 +108,7 @@ class Task .. method:: Task.cancel() - Cancel the task by injecting ``uasyncio.CancelledError`` into it. The task may + Cancel the task by injecting ``asyncio.CancelledError`` into it. The task may ignore this exception. Cleanup code may be run by trapping it, or via ``try ... finally``. @@ -148,7 +148,7 @@ class ThreadSafeFlag .. class:: ThreadSafeFlag() Create a new flag which can be used to synchronise a task with code running - outside the uasyncio loop, such as other threads, IRQs, or scheduler + outside the asyncio loop, such as other threads, IRQs, or scheduler callbacks. Flags start in the cleared state. The class does not currently work under the Unix build of MicroPython. diff --git a/docs/library/espnow.rst b/docs/library/espnow.rst index f821de59aa..f344983700 100644 --- a/docs/library/espnow.rst +++ b/docs/library/espnow.rst @@ -632,7 +632,7 @@ Supporting asyncio ------------------ A supplementary module (`aioespnow`) is available to provide -:doc:`asyncio` support. +:doc:`asyncio` support. **Note:** Asyncio support is available on all ESP32 targets as well as those ESP8266 boards which include the asyncio module (ie. ESP8266 devices with at @@ -642,7 +642,7 @@ A small async server example:: import network import aioespnow - import uasyncio as asyncio + import asyncio # A WLAN interface must be active to send()/recv() network.WLAN(network.STA_IF).active(True) @@ -680,7 +680,7 @@ A small async server example:: asyncio.run(main(e, peer, 120, 10)) .. module:: aioespnow - :synopsis: ESP-NOW :doc:`uasyncio` support + :synopsis: ESP-NOW :doc:`asyncio` support .. class:: AIOESPNow() diff --git a/docs/library/index.rst b/docs/library/index.rst index e428f3a062..69bc81ade5 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -57,6 +57,7 @@ library. :maxdepth: 1 array.rst + asyncio.rst binascii.rst builtins.rst cmath.rst @@ -77,7 +78,6 @@ library. struct.rst sys.rst time.rst - uasyncio.rst zlib.rst _thread.rst diff --git a/docs/library/machine.I2S.rst b/docs/library/machine.I2S.rst index 2244ef4202..84edb94e78 100644 --- a/docs/library/machine.I2S.rst +++ b/docs/library/machine.I2S.rst @@ -47,7 +47,7 @@ I2S objects can be created and initialized using:: 3 modes of operation are supported: - blocking - non-blocking - - uasyncio + - asyncio blocking:: @@ -63,13 +63,13 @@ non-blocking:: audio_in.irq(i2s_callback) # i2s_callback is called when buf is filled num_read = audio_in.readinto(buf) # returns immediately -uasyncio:: +asyncio:: - swriter = uasyncio.StreamWriter(audio_out) + swriter = asyncio.StreamWriter(audio_out) swriter.write(buf) await swriter.drain() - sreader = uasyncio.StreamReader(audio_in) + sreader = asyncio.StreamReader(audio_in) num_read = await sreader.readinto(buf) Some codec devices like the WM8960 or SGTL5000 require separate initialization diff --git a/docs/reference/isr_rules.rst b/docs/reference/isr_rules.rst index bdb838c590..ea330acad3 100644 --- a/docs/reference/isr_rules.rst +++ b/docs/reference/isr_rules.rst @@ -219,20 +219,20 @@ Exceptions If an ISR raises an exception it will not propagate to the main loop. The interrupt will be disabled unless the exception is handled by the ISR code. -Interfacing to uasyncio ------------------------ +Interfacing to asyncio +---------------------- -When an ISR runs it can preempt the `uasyncio` scheduler. If the ISR performs a `uasyncio` +When an ISR runs it can preempt the `asyncio` scheduler. If the ISR performs a `asyncio` operation the scheduler's operation can be disrupted. This applies whether the interrupt is hard or soft and also applies if the ISR has passed execution to another function via `micropython.schedule`. In particular creating or cancelling tasks is invalid in an ISR context. -The safe way to interact with `uasyncio` is to implement a coroutine with synchronisation performed by -`uasyncio.ThreadSafeFlag`. The following fragment illustrates the creation of a task in response +The safe way to interact with `asyncio` is to implement a coroutine with synchronisation performed by +`asyncio.ThreadSafeFlag`. The following fragment illustrates the creation of a task in response to an interrupt: .. code:: python - tsf = uasyncio.ThreadSafeFlag() + tsf = asyncio.ThreadSafeFlag() def isr(_): # Interrupt handler tsf.set() @@ -240,7 +240,7 @@ to an interrupt: async def foo(): while True: await tsf.wait() - uasyncio.create_task(bar()) + asyncio.create_task(bar()) In this example there will be a variable amount of latency between the execution of the ISR and the execution of ``foo()``. This is inherent to cooperative scheduling. The maximum latency is application