events.py: Add ELO class.

Author: peterhinch

v3/docs/EVENTS.md

@@ -20,9 +20,10 @@ This document assumes familiarity with `asyncio`. See [official docs](http://doc
   5.1 [Use of Delay_ms](./EVENTS.md#51-use-of-delay_ms) A retriggerable delay  
   5.2 [Long and very long button press](./EVENTS.md#52-long-and-very-long-button-press)  
   5.3 [Application example](./EVENTS.md#53-application-example)  
- 6. [Drivers](./EVENTS.md#6-drivers) Minimal Event-based drivers  
-  6.1 [ESwitch](./EVENTS.md#61-eswitch) Debounced switch  
-  6.2 [EButton](./EVENTS.md#62-ebutton) Debounced pushbutton with double and long press events  
+ 6. [ELO class](./EVENTS.md#6-elo-class) Convert a coroutine or task to an event-like object.
+ 7. [Drivers](./EVENTS.md#7-drivers) Minimal Event-based drivers  
+  7.1 [ESwitch](./EVENTS.md#71-eswitch) Debounced switch  
+  7.2 [EButton](./EVENTS.md#72-ebutton) Debounced pushbutton with double and long press events  
 
 [Appendix 1 Polling](./EVENTS.md#100-appendix-1-polling)  
 
@@ -61,6 +62,11 @@ Users only need to know the names of the bound `Event` instances. By contast
 there is no standard way to specify callbacks, to define the passing of
 callback arguments or to define how to retrieve their return values.
 
+There are other ways to define an API without callbacks, notably the stream
+mechanism and the use of asynchronous iterators with `async for`. This doc
+discusses the `Event` based approach which is ideal for sporadic occurrences
+such as responding to user input.
+
 ###### [Contents](./EVENTS.md#0-contents)
 
 # 2. Rationale
@@ -135,6 +141,10 @@ ELO examples are:
 | [Delay_ms][2m]       | Y    | Y     | Y   | Self-setting      |
 | [WaitAll](./EVENTS.md#42-waitall)              | Y    | Y     | N   | See below         |
 | [WaitAny](./EVENTS.md#41-waitany)              | Y    | Y     | N   |                   |
+| [ELO instances](./EVENTS.md#44-elo-class)  | Y    | N     | N   |                   |
+
+The `ELO` class converts coroutines or `Task` instances to event-like objects,
+allowing them to be included in the arguments of event based primitives.
 
 Drivers exposing `Event` instances include:
 
@@ -316,19 +326,118 @@ async def foo():
         else:
             # Normal outcome, process readings
 ```
+###### [Contents](./EVENTS.md#0-contents)
+
+# 6. ELO class
+
+This converts a task to an "event-like object", enabling tasks to be included in
+`WaitAll` and `WaitAny` arguments. An `ELO` instance is a wrapper for a `Task`
+instance and its lifetime is that of its `Task`. The constructor can take a
+coroutine or a task as its first argument; in the former case the coro is
+converted to a `Task`.
+
+#### Constructor args
+
+1. `coro` This may be a coroutine or a `Task` instance.
+2. `*args` Positional args for a coroutine (ignored if a `Task` is passed).
+3. `**kwargs` Keyword args for a coroutine (ignored if a `Task` is passed).
+
+If a coro is passed it is immediately converted to a `Task` and scheduled for
+execution.
+
+#### Asynchronous method
+
+1. `wait` Pauses until the `Task` is complete or is cancelled. In the latter
+case no exception is thrown.
+
+#### Synchronous method
+
+1. `__call__` Returns the instance's `Task`. If the instance's `Task` was
+cancelled the `CancelledError` exception is returned. The function call operator
+allows a running task to be accessed, e.g. for cancellation. It also enables return values to be
+retrieved.
+
+#### Usage example
+
+In most use cases an `ELO` instance is a throw-away object which allows a coro
+to participate in an event-based primitive:
+```python
+evt = asyncio.Event()
+async def my_coro(t):
+    await asyncio.wait(t)
+
+async def foo():  # Puase until the event has been triggered and coro has completed
+    await WaitAll((evt, ELO(my_coro, 5))).wait()  # Note argument passing
+```
+#### Retrieving results
+
+A task may return a result on completion. This may be accessed by awaiting the
+`ELO` instance's `Task`. A reference to the `Task` may be acquired with function
+call syntax. The following code fragment illustrates usage. It assumes that
+`task` has already been created, and that `my_coro` is a coroutine taking an
+integer arg. There is an `EButton` instance `ebutton` and execution pauses until
+tasks have run to completion and the button has been pressed.
+```python
+async def foo():
+    elos = (ELO(my_coro, 5), ELO(task))
+    events = (ebutton.press,)
+    await WaitAll(elos + events).wait()
+    for e in elos:  # Retrieve results from each task
+        r = await e()  # Works even though task has already completed
+        print(r)
+```
+This works because it is valid to `await` a task which has already completed.
+The `await` returns immediately with the result. If `WaitAny` were used an `ELO`
+instance might contain a running task. In this case the line
+```python
+r = await e()
+```
+would pause before returning the result.
+
+#### Cancellation
+
+The `Task` in `ELO` instance `elo` may be retrieved by issuing `elo()`. For
+example the following will subject an `ELO` instance to a timeout:
+```python
+async def elo_timeout(elo, t):
+    await asyncio.sleep(t)
+    elo().cancel()  # Retrieve the Task and cancel it
+
+async def foo():
+    elo = ELO(my_coro, 5)
+    asyncio.create_task(elo_timeout(2))
+    await WaitAll((elo, ebutton.press)).wait()  # Until button press and ELO either finished or timed out
+```
+If the `ELO` task is cancelled, `.wait` terminates; the exception is retained.
+Thus `WaitAll` or `WaitAny` behaves as if the task had terminated normally. A
+subsequent call to `elo()` will return the exception. In an application
+where the task might return a result or be cancelled, the following may be used:
+```python
+async def foo():
+    elos = (ELO(my_coro, 5), ELO(task))
+    events = (ebutton.press,)
+    await WaitAll(elos + events).wait()
+    for e in elos:  # Check each task
+        t = e()
+        if isinstance(t, asyncio.CancelledError):
+            # Handle exception
+        else:  # Retrieve results
+            r = await t  # Works even though task has already completed
+            print(r)
+```
 
 ###### [Contents](./EVENTS.md#0-contents)
 
-# 6. Drivers
+# 7. Drivers
 
 The following device drivers provide an `Event` based interface for switches and
 pushbuttons.
 
-## 6.1 ESwitch
+## 7.1 ESwitch
 
 This is now documented [here](./DRIVERS.md#31-eswitch-class).
 
-## 6.2 EButton
+## 7.2 EButton
 
 This is now documented [here](./DRIVERS.md#41-ebutton-class).
 

v3/primitives/__init__.py

@@ -11,6 +11,8 @@
 
 async def _g():
     pass
+
+
 type_coro = type(_g())
 
 # If a callback is passed, run it and return.
@@ -22,14 +24,18 @@ def launch(func, tup_args):
         res = asyncio.create_task(res)
     return res
 
+
 def set_global_exception():
     def _handle_exception(loop, context):
         import sys
+
         sys.print_exception(context["exception"])
         sys.exit()
+
     loop = asyncio.get_event_loop()
     loop.set_exception_handler(_handle_exception)
 
+
 _attrs = {
     "AADC": "aadc",
     "Barrier": "barrier",
@@ -44,6 +50,7 @@ def _handle_exception(loop, context):
     "Switch": "switch",
     "WaitAll": "events",
     "WaitAny": "events",
+    "ELO": "events",
     "ESwitch": "events",
     "EButton": "events",
     "RingbufQueue": "ringbuf_queue",

v3/primitives/events.py

@@ -1,6 +1,6 @@
 # events.py Event based primitives
 
-# Copyright (c) 2022 Peter Hinch
+# Copyright (c) 2022-2024 Peter Hinch
 # Released under the MIT License (MIT) - see LICENSE file
 
 import uasyncio as asyncio
@@ -34,9 +34,10 @@ def event(self):
         return self.trig_event
 
     def clear(self):
-        for evt in (x for x in self.events if hasattr(x, 'clear')):
+        for evt in (x for x in self.events if hasattr(x, "clear")):
             evt.clear()
 
+
 # An Event-like class that can wait on an iterable of Event-like instances,
 # .wait pauses until all passed events have been set.
 class WaitAll:
@@ -46,6 +47,7 @@ def __init__(self, events):
     async def wait(self):
         async def wt(event):
             await event.wait()
+
         tasks = (asyncio.create_task(wt(event)) for event in self.events)
         try:
             await asyncio.gather(*tasks)
@@ -54,15 +56,65 @@ async def wt(event):
                 task.cancel()
 
     def clear(self):
-        for evt in (x for x in self.events if hasattr(x, 'clear')):
+        for evt in (x for x in self.events if hasattr(x, "clear")):
             evt.clear()
 
+
+# Convert to an event-like object: either a running task or a coro with args.
+# Motivated by a suggestion from @sandyscott iss #116
+class ELO_x:
+    def __init__(self, coro, *args, **kwargs):
+        self._coro = coro
+        self._args = args
+        self._kwargs = kwargs
+        self._task = None  # Current running task (or exception)
+
+    async def wait(self):
+        cr = self._coro
+        istask = isinstance(cr, asyncio.Task)  # Instantiated with a Task
+        if istask and isinstance(self._task, asyncio.CancelledError):
+            return  # Previously awaited and was cancelled/timed out
+        self._task = cr if istask else asyncio.create_task(cr(*self._args, **self._kwargs))
+        try:
+            await self._task
+        except asyncio.CancelledError as e:
+            self._task = e  # Let WaitAll or WaitAny complete
+
+    # User can retrieve task/coro results by awaiting .task() (even if task had
+    # run to completion). If task was cancelled CancelledError is returned.
+    # If .task() is called before .wait() returns None or result of prior .wait()
+    # Caller issues isinstance(task, CancelledError)
+    def task(self):
+        return self._task
+
+
+# Convert to an event-like object: either a running task or a coro with args.
+# Motivated by a suggestion from @sandyscott iss #116
+class ELO:
+    def __init__(self, coro, *args, **kwargs):
+        tsk = isinstance(coro, asyncio.Task)  # Instantiated with a Task
+        self._task = coro if tsk else asyncio.create_task(coro(*args, **kwargs))
+
+    async def wait(self):
+        try:
+            await self._task
+        except asyncio.CancelledError as e:
+            self._task = e  # Let WaitAll or WaitAny complete
+
+    # User can retrieve task/coro results by awaiting elo() (even if task had
+    # run to completion). If task was cancelled CancelledError is returned.
+    # If .task() is called before .wait() returns None or result of prior .wait()
+    # Caller issues isinstance(task, CancelledError)
+    def __call__(self):
+        return self._task
+
+
 # Minimal switch class having an Event based interface
 class ESwitch:
     debounce_ms = 50
 
     def __init__(self, pin, lopen=1):  # Default is n/o switch returned to gnd
-        self._pin = pin # Should be initialised for input with pullup
+        self._pin = pin  # Should be initialised for input with pullup
         self._lopen = lopen  # Logic level in "open" state
         self.open = asyncio.Event()
         self.close = asyncio.Event()
@@ -92,6 +144,7 @@ def deinit(self):
         self.open.clear()
         self.close.clear()
 
+
 # Minimal pushbutton class having an Event based interface
 class EButton:
     debounce_ms = 50  # Attributes can be varied by user
@@ -103,13 +156,14 @@ def __init__(self, pin, suppress=False, sense=None):
         self._supp = suppress
         self._sense = pin() if sense is None else sense
         self._state = self.rawstate()  # Initial logical state
-        self._ltim = Delay_ms(duration = EButton.long_press_ms)
-        self._dtim = Delay_ms(duration = EButton.double_click_ms)
+        self._ltim = Delay_ms(duration=EButton.long_press_ms)
+        self._dtim = Delay_ms(duration=EButton.double_click_ms)
         self.press = asyncio.Event()  # *** API ***
         self.double = asyncio.Event()
         self.long = asyncio.Event()
         self.release = asyncio.Event()  # *** END API ***
-        self._tasks = [asyncio.create_task(self._poll(EButton.debounce_ms))]  # Tasks run forever. Poll contacts
+        # Tasks run forever. Poll contacts
+        self._tasks = [asyncio.create_task(self._poll(EButton.debounce_ms))]
         self._tasks.append(asyncio.create_task(self._ltf()))  # Handle long press
         if suppress:
             self._tasks.append(asyncio.create_task(self._dtf()))  # Double timer