API's for asynchronous events

[peterhinch]

The traditional approach in a toolkit such as a GUI is to use callbacks. If a user adjusts a control or clicks on a virtual button, a callback runs which does something like change a variable available to the main application code. This has the merit of being familiar. It also means that the application developer can write conventional synchronous code - although it doesn't preclude using asynchronous code if the application requires it.

In my efforts such as micro-gui and interfaces to mechanical contacts I adopted the callback approach largely out of habit. Callbacks do introduce complications such as how to pass arguments to them and how to retrieve a return value. These aren't insurmountable, but they do add code.

It occurred to me that the fact that uasyncio has a very efficient Event class offers an alternative to callbacks. A task waiting on an Event consumes minimal resources. Further, uasyncio can support large numbers of waiting tasks. Consider this case where a task waits on a switch closure:

from primitives import Switch  # Implemented in my Switch and Pushbutton classes
sw = Switch(Pin(1, Pin.IN, Pin.PULL_UP))
sw.close_func = None  # Creates a closure Event rather than a callback

async def handle_closure():
    while True:
        sw.close.clear()  # Clear the closure Event
        await sw.close.wait()  # Wait for switch closure
        # Do something

The "do something" might set a variable or run some asynchronous code. It could replicate the traditional interface, the callback function being passed to handle_closure and running after the event occurred.

My suggestion is that the interface to asynchronous objects can be simplified to managing a bound Event. Such an interface allows the user to run callbacks if required, but also offers other options. The drawbacks are:

1. An application might have a lot of very simple tasks, most of which will be waiting on Events.
2. Application designers are forced into using uasyncio.

I'd be interested to hear any comments. Do any actual GUI's use this kind of approach?

[jimmo]

Thanks @peterhinch great question!

I will reply in more detail later because this is something that I have lots of thoughts about, but two quick points that aren't GUI-related but kind of broadly related to this discussion. I'd be really interested to hear from people familiar with other languages that also now support async/await such as Javascript/TypeScript, C#, Swift, etc.... I don't think Java has native support, but Kotlin does.

• Not GUI-related, but in designing aioble I initially spent a lot of time trying to figure out whether callbacks made sense. e.g. "the client has written a value to this peripheral's characteristic", or "the peripheral has notified on this characteristic". (Or even simpler things like connection and disconnection). In the end, I decided not to use callbacks anywhere, and every event is something that can be awaited. This means that to use aioble, you will likely end up with several cooperating tasks. Some of those tasks might use gather to await multiple incoming events. It also works well with timeouts and cancellations. Personally, I really like how this works, I find it quite natural to implement and there's a lot more linear code (exactly like you'd expect from asyncio). Would recommend (although would love to hear from other people who have used aioble to see if they would agree! @mattytrentini @andrewleech @peitschie).

• (Mostly for other people reading this, I know @peterhinch you already know this) As @peterhinch mentions, it's relatively easy to wrap a callback-based interface into an event one with Event, although be careful, in general you want to use ThreadSafeFlag because the callback is likely executing in a context that cannot set an event. See e.g. extmod/uasyncio: Add ThreadSafeEvent. #6886 (comment) for an AsyncPin that allows await pin.wait_edge(). But we want to make this more efficient, integrate with low-power/sleep, and more broadly useful across the various hardware APIs. See extmod: implement basic "uevent" module (RFC, WIP) #6125 (and the linked earlier PRs) for more on this. I'd love to see awaitable DMA transfers, e.g. SPI write, etc.

[andrewleech]

I'm 100% in favour of the concept of async events rather than traditional callbacks for the same reasons mentioned earlier, but most importantly the variable scope management and the readable / linear code path. I hate nothing more than trying to debug the callback hell that JS code often becomes.

Most of the patterns in use in aioble are an excellent example of how beautifully clean this can be, however in my opinion there's one outlier still; the on-write handlers.

These while True: / await event functions are still passed into init like callbacks and require a bit of boilerplate each time. That can be abstracted and I have a function decorator pattern I've been meaning to share for that... though it makes them look/behave even more like callbacks then.

We've (mostly @peitschie) also discovered an issue with these await event task handlers: the order of incoming (often hardware / ble) events can be lost. If two events come in closer together than the time it takes asyncio to service/check all the tasks/events in the loop, then the event that was registered first will get handled first, regardless of which event occurred first. I've been thinking some sort of event queuing might be needed for cases looked this if/when the order of hw events matter (they don't always) but haven't tried to prototype anything yet.

[peterhinch]

the order of incoming (often hardware / ble) events can be lost. ... some sort of event queuing might be needed

An interesting case. Such a queue would need to be thread safe as events may be sourced by ISR's or by other threads/cores. It would be good if a timestamp (e.g. ticks_us()) were stored with the event as some applications may need to determine the relative timing of events.

[peitschie]

Adding my 👍 to aioble's async/await based interface.

I wrote a fairly complex Bluetooth service (object transfer service) with the lower level call-back (well, IRQ based) ubluetooth interface. When @mattytrentini ported this across to aioble, quite a few lines were saved, but more importantly the logical flow of activities required far less error-prone management of global state.

[peterhinch]

I have now applied the event driven approach to some real problems. These are my thoughts.

Rationale

The design of uasyncio V3 and its Event class offers an alternative approach to common problems in firmare design. This is because it has these attributes:

1. A task waiting on an Event is put on a queue where it consumes no CPU cycles until the event is triggered.
2. The design of Event is such that it can be cleared immediately after being set; if multiple tasks are waiting on it, all will be restarted.
3. Alternatively the Event may be cleared later. The timing of clearing the Event determines its behaviour if a task that waits on the Event has not reached the await event.wait() statement at the time when the Event is set. It pauses only if the Event is cleared before it reaches the statement. The ability to control the timing of clearing an Event adds flexibility.
4. uasyncio can support large numbers of tasks (hundreds) on a typical microcontroller. Proliferation of tasks is not a problem, especially where they are small and are paused waiting on queues.

This contrasts with other schedulers (such as uasyncio V2) where there was no built-in Event class; typical solutions used polling and were convenience methods rather than performance solutions.

Device drivers

For easy comptaibility with this approach drivers should expose an asynchronous .wait method. They may optionally expose .clear and/or .set. An example is Delay_ms which exposes .wait and .clear only, with set being used internally.

Primitives

Applying Events to typical logic problems requires two new primitives: WaitAny and WaitAll. Each is an Event-like object. The constructor takes an iterable of Event instances and its .wait method pauses until any or all of the Event instances are set.

The fact that they are Event-like objects enables nesting:

await WaitAll((event1, event2, WaitAny(event3, event4))).wait()

The WaitAny class has an event method which returns the Event which occurred first. This enables the reason for its triggering to be checked.

wa = WaitAny((event1, event2, event3))
await wa.wait()
if wa.event() is event1:
    # event1 caused execution to continue

The primitives' .wait method can be cancelled or subjected to timeouts.

Application example

A measuring instrument is started by pressing a button. The measurement normally runs for five seconds. If the sensor does not detect anything, the test runs until it does, however it is abandoned if nothing has been detected after a minute. While running, extra button presses are ignored. During a normal five second run, extra detections from the sensor are ignored.

This can readily be coded using callbacks and synchronous or asynchronous code,however the outcome is likely to have a fair amount of ad hoc logic.

This is an event based approach:

btn = Pushbutton(args)  # Has Events for press, release, double, long
bp = btn.press
sn = Sensor(args)  # Assumed to have an Event interface.
tm = Ticks_ms(duration=5_000)  # Exposes .wait and .clear only.
events = (sn, tm)
async def foo():
    while True:
        bp.clear()  # Ignore prior button press
        await bp.wait()  # Button pressed
        for event in events:  # Ignore events that were set prior to this moment
            event.clear()
        tm.trigger()  # Start 5 second timer
        try:
            await asyncio.wait_for(WaitAll(events).wait(), 60)
        except asyncio.TimeoutError:
            print("No reading from sensor")
        else:
            # Normal outcome

In my opinion this wins on readability.

Status

There is prototype code so I'm convinced it can be made to work efficiently. I'd welcome any comments, especially in regard to errors of fact. If this approach is common practice I'd be interested to see references.

[peterhinch]

This document contains my conclusions on this with event based drivers and primitives. I'd welcome any feedback, even if only "the old bloke's finally lost it" :-)
@jimmo ?

[jimmo]

I will take a look... sorry haven't made it back around to this one yet but will have a read ASAP.

Possibly related... About 300 browser tabs ago, I came across https://github.com/sbtinstruments/asyncio-mqtt (in the context of a very different thing) but was interested to look into the history and evoloution of the initial "async-ifyed mqtt APIs" which were still very callback-oriented into this style of API that involves async iterators.

[jonathanhogg]

I'm a bit late to this party, but just wanted to add a +1 to the principle. I will try to find the time to delve fully into your wrapper classes and document, @peterhinch, but I'm really up against it with a bunch of projects at the moment (sigh).

I write all of my MPy code using async/await, with callbacks only used to trigger ThreadSafeFlags or to pump thread-safe queues (it'd be great to see a built-in implementation of one of these). This includes a complete async implementation of serial-over-BLE, so I need to take a look at aioble, @jimmo!

What I'd really love is for a general approach to this to be come up with that then can be applied to all of the obvious built-in classes, kind of like the .irq() method that a bunch of classes have. So, e.g., Pin gains a new one-shot .event() method that one might use like:

button = Pin(2, Pin.IN, pull=Pin.PULL_UP)
while True:
    await button.event(Pin.IRQ_FALLING)
    print("Button pushed!")

And/or an iterable multi-shot, queue version:

button = Pin(2, Pin.IN, pull=Pin.PULL_UP)
async for event in button.events(Pin.IRQ_FALLING):
    print("Button pushed!")

It'd also be great to see awaitable versions of DMA-capable things like SPI.write() and UART.write(). At the moment I have to use a hacky _thread wrapper around this to make it async.

I'm an async nut on the whole, but I genuinely feel that this is the sort of thing that really differentiates using a high-level language like Python for firmware development over C/C++, which is also why I'd advocate for it being rolled-into and documented as part of the core MPy distribution rather than being a set of add-on wrappers. Even better would be having internal C APIs for all async event stuff so that latency can be reduced.

[As an aside on event queues: it might be interesting to come up with a core implementation of event queues that can be merged together to maintain event ordering across different internal IRQs. I suspect that would really require going the whole hog and having an Event class hierarchy that one could then switch on in an event loop (roll on match/case in MPy!).

I'm personally more of a fan of methods returning awaitables that return an Event object than having methods return an Event with an awaitable .wait() method as this fits much better with queues and differentiating what happened in a wait-first-event scenario, but I can see the point in events all subclassing uasyncio.Event. This is a general design problem in deciding whether an event is a thing-that-has-happened or a-thing-that-can-happen.]

[peterhinch]

Those code samples might not work well with a pushbutton owing to contact bounce but I agree 100% about the interface which would be great with well-defined signals.

It'd also be great to see awaitable versions of DMA-capable things like SPI.write() and UART.write()

This has been discussed from time to time and would be a major enhancement. An example is Mike Teachman's asynchronous I2S interface which is now part of MP firmware and works very well.

As for Event instances and queues I'll think about that, but it does strike me that your code samples and ideas presuppose a thread-safe Event class capable of interfacing with hard IRQ's. My observations are based on the existing Event class. My understanding of its operation is that tasks are pushed onto the task queue in the order that Event instances are set, so ordering should be preserved. However I haven't tested this.

Maintaining order in a thread-safe manner is a significant challenge. One well above my pay-grade :)

[jonathanhogg]

Yes, this is obviously a terrible way to do a button 😀

Actually, now that I have a solid machine.Counter API in my build, I use that. It provides a simple way to do a hardware de-bounced, IRQ-less, poll-able button object a la:

button = machine.Counter(Pin(2, Pin.IN, pull=Pin.PULL_UP), filter_ns=12500)
while True:
    if button.value(0):
        print("Button pushed!")

Not async but it's fine dropped into a fast spinning event loop.

Of course, now I'm thinking about what async features I could add to the esp32.PCNT API that underlies this…

[peterhinch]

I'm personally more of a fan of methods returning awaitables that return an Event object than having methods return an Event with an awaitable .wait() method as this fits much better with queues and differentiating what happened in a wait-first-event scenario...

Please could you explain this in a bit more detail - despite mulling it over I'm not sure I follow.

I can see the point in events all subclassing uasyncio.Event

This is good but some of my classes have multiple Event instances mandating composition rather than inheritance. For example a pushbutton has .press, .release, .long and .double bound Event instances. Then there is the ThreadSafeFlag which is a separate class. In reasoning about this I use the notion of an "event-like object" (ELO) which has (as a minimum) an asynchronous .wait method. ELO's include Event, ThreadSafeFlag and other classes.

[jonathanhogg]

Please could you explain this in a bit more detail - despite mulling it over I'm not sure I follow.

Yes, of course.

In asyncio the Event class represents a communication primitive that allows one to indicate at some point in the future that an event has happened. So an Event represents a thing that you can wait on. To make it multi-shot, it obviously needs to be an object with methods for setting, clearing and waiting.

However, it's pretty common in lots of observer pattern or event loop frameworks, particularly GUIs, for Event to be a superclass for a hierarchy of simple data objects that capture the details of an event. In this case, the existence of such an object means the event has already happened. In this case, there is some other mechanism for waiting for these objects – an event loop wait function or observer pattern callbacks.

In a simple, single-source, one-shot example, the difference would be:

button = Button()
button_pushed = button.pushed()
await button_pushed.wait()
print("Button pushed!")

becomes:

button = Button()
push_event = await button.pushed()
print("Button pushed!")

Not much difference initially, but the latter scales easily to:

button = Button()
async for push_event in button.pushes():
    print("Button pushed!")

which would internally use an event queue, with the put side registered as a callback handler on the IRQ.

Event queues allow one to deal with multiple presses before the task is awoken, which asyncio.Event.wait() doesn't handle. The simple one-shot Button.pushed() method can be implemented on top by creating an event queue, registering it and then dismantling it after one event.

A mechanism that is more explicit and allows merging a bunch of sources together to deal with the events in the order they occurred (or as close to this as possible) would look like this:

button = Button()
events = EventQueue()
button.register_pushes(events)
async for event in events:
    if isinstance(event, ButtonEvent):
        print("Button pushed!")

If the source offers a ton of different interesting events, then one can just transpose the standard .irq() bit field mechanism to register for events in one go:

button = Button()
events = EventQueue()
button.register_events(events, Button.PRESSED | Button.RELEASED)
async for event in events:
    if isinstance(event, ButtonEvent):
        if event.type == Button.PRESSED:
            print("Button pressed!")
        elif event.type == Button.RELEASED:
            print("Button released!")

My preference would actually be for this, with anything that has an .irq() method gaining a method for registering the source with an event queue instead, where the IRQ handler just pushes the event details into the queue – this is what I do in my code.

It would require a built-in, IRQ-safe, event queue implementation, including an IRQ-safe way of creating the Event class instances with the event details. This could probably be done by having a ring buffer that captures a pointer to the event object constructor and a few native-type args, and then have the get side of the queue instantiate the actual event objects. Such a mechanism could also record event times with a high-resolution timer within the IRQ handler, which is often super-useful.

Basically, like the old BLE ring buffer, but designed for async/await and usable across all hardware classes.

[peterhinch]

Thank you for that explanation. Very clearly written.