docs: Rename uasyncio to asyncio.

This work was funded through GitHub Sponsors.

Signed-off-by: Jim Mussared <jim.mussared@gmail.com>

1 files changed, 360 insertions, 0 deletions

diff --git a/docs/library/asyncio.rst b/docs/library/asyncio.rst
new file mode 100644
index 000000000..9a2c14e7e
--- /dev/null
+++ b/docs/library/asyncio.rst
@@ -0,0 +1,360 @@
+:mod:`asyncio` --- asynchronous I/O scheduler
+=============================================
+
+.. module:: asyncio
+   :synopsis: asynchronous I/O scheduler for writing concurrent code
+
+|see_cpython_module|
+`asyncio <https://docs.python.org/3.8/library/asyncio.html>`_
+
+Example::
+
+    import asyncio
+
+    async def blink(led, period_ms):
+        while True:
+            led.on()
+            await asyncio.sleep_ms(5)
+            led.off()
+            await asyncio.sleep_ms(period_ms)
+
+    async def main(led1, led2):
+        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
+    asyncio.run(main(LED(1), LED(2)))
+
+    # Running on a generic board
+    from machine import Pin
+    asyncio.run(main(Pin(1), Pin(2)))
+
+Core functions
+--------------
+
+.. function:: create_task(coro)
+
+    Create a new task from the given coroutine and schedule it to run.
+
+    Returns the corresponding `Task` object.
+
+.. function:: current_task()
+
+    Return the `Task` object associated with the currently running task.
+
+.. function:: run(coro)
+
+    Create a new task from the given coroutine and run it until it completes.
+
+    Returns the value returned by *coro*.
+
+.. function:: sleep(t)
+
+    Sleep for *t* seconds (can be a float).
+
+    This is a coroutine.
+
+.. function:: sleep_ms(t)
+
+    Sleep for *t* milliseconds.
+
+    This is a coroutine, and a MicroPython extension.
+
+Additional functions
+--------------------
+
+.. function:: wait_for(awaitable, timeout)
+
+    Wait for the *awaitable* to complete, but cancel it if it takes longer
+    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 ``asyncio.TimeoutError``:
+    this should be trapped by the caller.  The task receives
+    ``asyncio.CancelledError`` which may be ignored or trapped using ``try...except``
+    or ``try...finally`` to run cleanup code.
+
+    Returns the return value of *awaitable*.
+
+    This is a coroutine.
+
+.. function:: wait_for_ms(awaitable, timeout)
+
+    Similar to `wait_for` but *timeout* is an integer in milliseconds.
+
+    This is a coroutine, and a MicroPython extension.
+
+.. function:: gather(*awaitables, return_exceptions=False)
+
+    Run all *awaitables* concurrently.  Any *awaitables* that are not tasks are
+    promoted to tasks.
+
+    Returns a list of return values of all *awaitables*.
+
+    This is a coroutine.
+
+class Task
+----------
+
+.. class:: Task()
+
+    This object wraps a coroutine into a running task.  Tasks can be waited on
+    using ``await task``, which will wait for the task to complete and return
+    the return value of the task.
+
+    Tasks should not be created directly, rather use `create_task` to create them.
+
+.. method:: Task.cancel()
+
+    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``.
+
+class Event
+-----------
+
+.. class:: Event()
+
+    Create a new event which can be used to synchronise tasks.  Events start
+    in the cleared state.
+
+.. method:: Event.is_set()
+
+    Returns ``True`` if the event is set, ``False`` otherwise.
+
+.. method:: Event.set()
+
+    Set the event.  Any tasks waiting on the event will be scheduled to run.
+
+    Note: This must be called from within a task. It is not safe to call this
+    from an IRQ, scheduler callback, or other thread. See `ThreadSafeFlag`.
+
+.. method:: Event.clear()
+
+    Clear the event.
+
+.. method:: Event.wait()
+
+    Wait for the event to be set.  If the event is already set then it returns
+    immediately.
+
+    This is a coroutine.
+
+class ThreadSafeFlag
+--------------------
+
+.. class:: ThreadSafeFlag()
+
+    Create a new flag which can be used to synchronise a task with code running
+    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.
+
+.. method:: ThreadSafeFlag.set()
+
+    Set the flag.  If there is a task waiting on the flag, it will be scheduled
+    to run.
+
+.. method:: ThreadSafeFlag.clear()
+
+    Clear the flag. This may be used to ensure that a possibly previously-set
+    flag is clear before waiting for it.
+
+.. method:: ThreadSafeFlag.wait()
+
+    Wait for the flag to be set.  If the flag is already set then it returns
+    immediately.  The flag is automatically reset upon return from ``wait``.
+
+    A flag may only be waited on by a single task at a time.
+
+    This is a coroutine.
+
+class Lock
+----------
+
+.. class:: Lock()
+
+    Create a new lock which can be used to coordinate tasks.  Locks start in
+    the unlocked state.
+
+    In addition to the methods below, locks can be used in an ``async with`` statement.
+
+.. method:: Lock.locked()
+
+    Returns ``True`` if the lock is locked, otherwise ``False``.
+
+.. method:: Lock.acquire()
+
+    Wait for the lock to be in the unlocked state and then lock it in an atomic
+    way.  Only one task can acquire the lock at any one time.
+
+    This is a coroutine.
+
+.. method:: Lock.release()
+
+    Release the lock.  If any tasks are waiting on the lock then the next one in the
+    queue is scheduled to run and the lock remains locked.  Otherwise, no tasks are
+    waiting an the lock becomes unlocked.
+
+TCP stream connections
+----------------------
+
+.. function:: open_connection(host, port)
+
+    Open a TCP connection to the given *host* and *port*.  The *host* address will be
+    resolved using `socket.getaddrinfo`, which is currently a blocking call.
+
+    Returns a pair of streams: a reader and a writer stream.
+    Will raise a socket-specific ``OSError`` if the host could not be resolved or if
+    the connection could not be made.
+
+    This is a coroutine.
+
+.. function:: start_server(callback, host, port, backlog=5)
+
+    Start a TCP server on the given *host* and *port*.  The *callback* will be
+    called with incoming, accepted connections, and be passed 2 arguments: reader
+    and writer streams for the connection.
+
+    Returns a `Server` object.
+
+    This is a coroutine.
+
+.. class:: Stream()
+
+    This represents a TCP stream connection.  To minimise code this class implements
+    both a reader and a writer, and both ``StreamReader`` and ``StreamWriter`` alias to
+    this class.
+
+.. method:: Stream.get_extra_info(v)
+
+    Get extra information about the stream, given by *v*.  The valid values for *v* are:
+    ``peername``.
+
+.. method:: Stream.close()
+
+    Close the stream.
+
+.. method:: Stream.wait_closed()
+
+    Wait for the stream to close.
+
+    This is a coroutine.
+
+.. method:: Stream.read(n=-1)
+
+    Read up to *n* bytes and return them.  If *n* is not provided or -1 then read all
+    bytes until EOF.  The returned value will be an empty bytes object if EOF is
+    encountered before any bytes are read.
+
+    This is a coroutine.
+
+.. method:: Stream.readinto(buf)
+
+    Read up to n bytes into *buf* with n being equal to the length of *buf*.
+
+    Return the number of bytes read into *buf*.
+
+    This is a coroutine, and a MicroPython extension.
+
+.. method:: Stream.readexactly(n)
+
+    Read exactly *n* bytes and return them as a bytes object.
+
+    Raises an ``EOFError`` exception if the stream ends before reading *n* bytes.
+
+    This is a coroutine.
+
+.. method:: Stream.readline()
+
+    Read a line and return it.
+
+    This is a coroutine.
+
+.. method:: Stream.write(buf)
+
+    Accumulated *buf* to the output buffer.  The data is only flushed when
+    `Stream.drain` is called.  It is recommended to call `Stream.drain` immediately
+    after calling this function.
+
+.. method:: Stream.drain()
+
+    Drain (write) all buffered output data out to the stream.
+
+    This is a coroutine.
+
+.. class:: Server()
+
+    This represents the server class returned from `start_server`.  It can be used
+    in an ``async with`` statement to close the server upon exit.
+
+.. method:: Server.close()
+
+    Close the server.
+
+.. method:: Server.wait_closed()
+
+    Wait for the server to close.
+
+    This is a coroutine.
+
+Event Loop
+----------
+
+.. function:: get_event_loop()
+
+    Return the event loop used to schedule and run tasks.  See `Loop`.
+
+.. function:: new_event_loop()
+
+    Reset the event loop and return it.
+
+    Note: since MicroPython only has a single event loop this function just
+    resets the loop's state, it does not create a new one.
+
+.. class:: Loop()
+
+    This represents the object which schedules and runs tasks.  It cannot be
+    created, use `get_event_loop` instead.
+
+.. method:: Loop.create_task(coro)
+
+    Create a task from the given *coro* and return the new `Task` object.
+
+.. method:: Loop.run_forever()
+
+    Run the event loop until `stop()` is called.
+
+.. method:: Loop.run_until_complete(awaitable)
+
+    Run the given *awaitable* until it completes.  If *awaitable* is not a task
+    then it will be promoted to one.
+
+.. method:: Loop.stop()
+
+    Stop the event loop.
+
+.. method:: Loop.close()
+
+    Close the event loop.
+
+.. method:: Loop.set_exception_handler(handler)
+
+    Set the exception handler to call when a Task raises an exception that is not
+    caught.  The *handler* should accept two arguments: ``(loop, context)``.
+
+.. method:: Loop.get_exception_handler()
+
+    Get the current exception handler.  Returns the handler, or ``None`` if no
+    custom handler is set.
+
+.. method:: Loop.default_exception_handler(context)
+
+    The default exception handler that is called.
+
+.. method:: Loop.call_exception_handler(context)
+
+    Call the current exception handler.  The argument *context* is passed through and
+    is a dictionary containing keys: ``'message'``, ``'exception'``, ``'future'``.