asyn.py Condition and Gather classes added.

Author: peterhinch

PRIMITIVES.md

@@ -34,7 +34,15 @@ MicroPython firmware or one built from source.
   3.5 [Class Semaphore](./PRIMITIVES.md#35-class-semaphore)
 
    3.5.1 [Class BoundedSemaphore](./PRIMITIVES.md#351-class-boundedsemaphore)
-  
+
+  3.6 [Class Condition](./PRIMITIVES.md#36-class-condition)
+
+   3.6.1 [Definition](./PRIMITIVES.md#361-definition)
+
+  3.7 [Class Gather](./PRIMITIVES.md#37-class-gather)
+
+   3.7.1 [Definition](./PRIMITIVES.md#371-definition)
+
  4. [Task Cancellation](./PRIMITIVES.md#4-task-cancellation)
 
   4.1 [Coro sleep](./PRIMITIVES.md#41-coro-sleep)
@@ -302,6 +310,104 @@ is raised.
 
 ###### [Contents](./PRIMITIVES.md#contents)
 
+## 3.6 Class Condition
+
+A `Condition` instance enables controlled access to a shared resource. In
+typical applications a number of tasks wait for the resource to be available.
+Once this occurs access can be controlled both by the number of tasks and by
+means of a `Lock`.
+
+A task waiting on a `Condition` instance will pause until another task issues
+`condition.notify(n)` or `condition.notify_all()`. If the number of tasks
+waiting on the condition exceeds `n`, only `n` tasks will resume. A `Condition`
+instance has a `Lock` as a member. A task will only resume when it has acquired
+the lock. User code may release the lock as required by the application logic.
+
+Typical use of the class is in a synchronous context manager:
+
+```python
+    with await cond:
+        cond.notify(2)  # Notify 2 tasks
+```
+
+```python
+    with await cond:
+        await cond.wait()
+        # Has been notified and has access to the locked resource
+    # Resource has been unocked by context manager
+```
+### 3.6.1 Definition
+
+Constructor: Optional arg `lock=None`. A `Lock` instance may be specified,
+otherwise the `Condition` instantiates its own.
+
+Synchronous methods:  
+ * `locked` No args. Returns the state of the `Lock` instance.
+ * `release` No args. Release the `Lock`. A `RuntimeError` will occur if the
+ `Lock` is not locked.
+ * `notify` Arg `n=1`. Notify `n` tasks. The `Lock` must be acquired before
+ issuing `notify` otherwise a `RuntimeError` will occur.
+ * `notify_all` No args. Notify all tasks. The `Lock` must be acquired before
+ issuing `notify_all` otherwise a `RuntimeError` will occur.
+
+Asynchronous methods:  
+ * `acquire` No args. Pause until the `Lock` is acquired.
+ * `wait` No args. Await notification and the `Lock`. The `Lock` must be
+ acquired before issuing `wait` otherwise a `RuntimeError` will occur. The
+ sequence is as follows:  
+ The `Lock` is released.  
+ The task pauses until another task issues `notify`.  
+ It continues to pause until the `Lock` has been re-acquired when execution
+ resumes.
+ * `wait_for` Arg: `predicate` a callback returning a `bool`. The task pauses
+ until a notification is received and an immediate test of `predicate()`
+ returns `True`.
+
+###### [Contents](./PRIMITIVES.md#contents)
+
+## 3.7 Class Gather
+
+This aims to replicate some of the functionality of `asyncio.gather` in a
+'micro' form. The user creates a list of `Gatherable` tasks and then awaits a
+`Gather` object. When the last task to complete terminates, this will return a
+list of results returned by the tasks. Timeouts may be assigned to individual
+tasks.
+
+```python
+async def bar(x, y, rats):  # Example coro: note arg passing
+    await asyncio.sleep(1)
+    return x * y * rats
+
+gatherables = [asyn.Gatherable(foo, n) for n in range(4)]
+gatherables.append(asyn.Gatherable(bar, 7, 8, rats=77))
+gatherables.append(asyn.Gatherable(rats, 0, timeout=5))
+res = await asyn.Gather(gatherables)
+```
+
+The result `res` is a 6 element list containing the result of each of the 6
+coros. These are ordered by the position of the coro in the `gatherables` list.
+This is as per `asyncio.gather()`.
+
+See `asyntest.py` function `gather_test()`.
+
+### 3.7.1 Definition
+
+The `Gatherable` class has no user methods. The constructor takes a coro by
+name followed by any positional or keyword arguments for the coro. If an arg
+`timeout` is provided it should have an integer or float value: this is taken
+to be the timeout for the coro in seconds.
+
+The `Gather` class has no user methods. The constructor takes one mandatory
+arg: a list of `Gatherable` instances.
+
+`Gather` instances are awaitable. An `await` on an instance will terminate when
+the last member task completes or times out. It returns a list whose length
+matches the length of the list of `Gatherable` instances. Each element contains
+the return value of the corresponding `Gatherable` instance. Each return value
+may be of any type.
+
+###### [Contents](./PRIMITIVES.md#contents)
+
 # 4. Task Cancellation
 
 This has been under active development. Existing users please see

README.md

@@ -61,6 +61,17 @@ cancellation.
 
 Classes `Task` and `Future` are not supported.
 
+## Synchronisation Primitives and Task Cancellation
+
+The library `asyn.py` provides 'micro' implementations of the `asyncio`
+[synchronisation primitives](https://docs.python.org/3/library/asyncio-sync.html).
+Because `uasyncio` does not support `Task` and `Future` classes `asyncio`
+features such as `wait` and `gather` are unavailable. A `Barrier` class enables
+coroutines to be similarly synchronised. Coroutine cancellation is performed in
+a special efficient manner in `uasyncio`. The `asyn` library enhances this by
+facilitating options to pause until cancellation is complete and to check the
+status of individual coroutines.
+
 ## Asynchronous I/O
 
 At the time of writing this was under development. Asynchronous I/O works with

TUTORIAL.md

@@ -99,10 +99,14 @@ $ python3 -m micropip.py install -p ~/syn micropython-uasyncio
 
   4.1 [Awaitable classes](./TUTORIAL.md#41-awaitable-classes)
 
+   4.1.1 [Use in context managers](./TUTORIAL.md#411-use-in-context-managers)
+
+   4.1.2 [Awaiting a coro](./TUTORIAL.md#412-awaiting-a-coro)
+
   4.2 [Asynchronous iterators](./TUTORIAL.md#42-asynchronous-iterators)
 
   4.3 [Asynchronous context managers](./TUTORIAL.md#43-asynchronous-context-managers)
-  
+
   4.4 [Coroutines with timeouts](./TUTORIAL.md#44-coroutines-with-timeouts)
 
   4.5 [Exceptions](./TUTORIAL.md#45-exceptions)
@@ -430,7 +434,8 @@ ineffective. It will not receive the `TimeoutError` until it has acquired the
 lock. The same observation applies to task cancellation.
 
 The module `asyn.py` offers a `Lock` class which works in these situations. It
-is significantly less efficient than the official class.
+is significantly less efficient than the official class but supports additional
+interfaces as per the CPython version including context manager usage.
 
 ###### [Contents](./TUTORIAL.md#contents)
 
@@ -495,11 +500,14 @@ compensation for this.
 
 ## 3.3 Barrier
 
-This enables multiple coros to rendezvous at a particular point. For example
-producer and consumer coros can synchronise at a point where the producer has
-data available and the consumer is ready to use it. At that point in time the
-`Barrier` can optionally run a callback before releasing the barrier and
-allowing all waiting coros to continue. [Full details.](./PRIMITIVES.md#34-class-barrier)
+This has two uses. Firstly it can cause a coro to pause until one or more other
+coros have terminated.
+
+Secondly it enables multiple coros to rendezvous at a particular point. For
+example producer and consumer coros can synchronise at a point where the
+producer has data available and the consumer is ready to use it. At that point
+in time the `Barrier` can run an optional callback before the barrier is
+released and all waiting coros can continue. [Full details.](./PRIMITIVES.md#34-class-barrier)
 
 The callback can be a function or a coro. In most applications a function is
 likely to be used: this can be guaranteed to run to completion before the
@@ -674,24 +682,91 @@ class Foo():
         for n in range(5):
             print('__await__ called')
             yield from asyncio.sleep(1) # Other coros get scheduled here
+        return 42
 
     __iter__ = __await__  # See note below
 
 async def bar():
     foo = Foo()  # Foo is an awaitable class
     print('waiting for foo')
-    await foo
-    print('done')
+    res = await foo  # Retrieve result
+    print('done', res)
 
 loop = asyncio.get_event_loop()
 loop.run_until_complete(bar())
 ```
 
 Currently MicroPython doesn't support `__await__` (issue #2678) and
 `__iter__` must be used. The line `__iter__ = __await__` enables portability
-between CPython and MicroPython.
+between CPython and MicroPython. Example code may be found in the `Event`,
+`Barrier`, `Cancellable` and `Condition` classes in asyn.py.
+
+### 4.1.1 Use in context managers
+
+Awaitable objects can be used in synchronous or asynchronous CM's by providing
+the necessary special methods. The syntax is:
+
+```python
+with await awaitable as a:  # The 'as' clause is optional
+    # code omitted
+async with awaitable as a:  # Asynchronous CM (see below)
+    # do something
+```
+
+To achieve this the `__await__` generator should return `self`. This is passed
+to any variable in an `as` clause and also enables the special methods to work.
+See `asyn.Condition` and `asyntest.condition_test`, where the `Condition` class
+is awaitable and may be used in a synchronous CM.
+
+###### [Contents](./TUTORIAL.md#contents)
+
+### 4.1.2 Awaiting a coro
+
+The Python language requires that `__await__` is a generator function. In
+MicroPython generators and coroutines are identical, so the solution is to use
+`yield from coro(args)`.
+
+This tutorial aims to offer code portable to CPython 3.5 or above. In CPython
+coroutines and generators are distinct. CPython coros have an `__await__`
+special method which retrieves a generator. This is portable:
+
+```python
+up = False  # Running under MicroPython?
+try:
+    import uasyncio as asyncio
+    up = True  # Or can use sys.implementation.name
+except ImportError:
+    import asyncio
 
-Example code may be found in the `Event` and `Barrier` classes in asyn.py.
+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__
+
+async def bar():
+    foo = Foo()  # foo is awaitable
+    print('waiting for foo')
+    res = await foo  # Retrieve value
+    print('done', res)
+
+loop = asyncio.get_event_loop()
+loop.run_until_complete(bar())
+```
+
+Note that, in `__await__`, `yield from asyncio.sleep(1)` is allowed by CPython.
+I haven't yet established how this is achieved.
 
 ###### [Contents](./TUTORIAL.md#contents)
 
@@ -761,18 +836,22 @@ async def bar(lock):
 As with normal context managers an exit method is guaranteed to be called when
 the context manager terminates, whether normally or via an exception. To
 achieve this the special methods `__aenter__` and `__aexit__` must be
-defined, both being coros waiting on an `awaitable` object. This example comes
-from the `Lock` class:
+defined, both being coros waiting on a coro or `awaitable` object. This example
+comes from the `Lock` class:
 
 ```python
     async def __aenter__(self):
         await self.acquire()  # a coro defined with async def
+        return self
 
     async def __aexit__(self, *args):
         self.release()  # A conventional method
         await asyncio.sleep_ms(0)
 ```
 
+If the `async with` has an `as variable` clause the variable receives the
+value returned by `__aenter__`.
+
 Note there is currently a bug in the implementation whereby if an explicit
 `return` is issued within an `async with` block, the `__aexit__` method
 is not called. The solution is to design the code so that in all cases it runs