Add asyncio support

[sveinse]

This PR adds support of asyncio to canopen. The overall goals is to make canopen able to be used in either with asyncio or regular synchronous mode (but not at the same time) from the same code base.

Note that this work is still work in progress. This PR was created to discuss the specific solutions for async and non-async as mentioned in #272. This PR closes #272.

Current status until feature complete:

• Implement ABlockUploadStream, ABlockDownloadStream and ATextIOWrapper for async in SdoClient. Not needed
• Implement EcmyConsumer.wait() for async
• Async implementation of LssMaster Only fast_scan
• ~Async implementation of BaseNode402~Omitted for now
• Implement async variant of Network.add_node()
• Update unittests for async
• Update examples
• Update documentation

[sveinse]

What is the best way to deal with Variable attributes? The feedback from #355 indicates that it is desirable to keep the attr based get/set mechanisms. However, this scheme cannot be used for async as there is no await mechanism built into @data.setter.

    var = param.data   # Non-async use
    var = await param.aget_data()   # Async use

My goal has been to keep the async and non-async uses of canopen as equal as possible, but this is an area where users will see a difference.

[acolomb]

There is an implementation for .read() and .write() on the underlying canopen.variable.Variable type. Could that be used in an async wrapper, or something similar added for async?

[sveinse]

@acolomb I'm not precisely sure what you mean, so let me guess: You need separate async methods for read and right and they should only call their respective async setters/getters.

[acolomb]

Sorry, I was trying to answer your question in the previous comment about synchronous getters / setters used in the properties. What I meant was that instead we already do have methods to access a variable remotely. Those might be a better fit to mirror to the async world:

value = sdo_var.raw  # This is the usual, terse style recommended in the docs
value = sdo_var.read(fmt='raw')  # This also works already
value = await sdo_var.aread(fmt='raw')  # Feels like a natural enhancement for async

Note that the fmt='raw' argument can of course be left out, it's only needed for phys or desc variants. This would give us an easy way to support async without changing the existing synchronous property-based access.

[codecov]

Codecov Report

Attention: Patch coverage is 70.38217% with 93 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
canopen/pdo/base.py	51.11%	38 Missing and 6 partials ⚠️
canopen/variable.py	47.91%	25 Missing ⚠️
canopen/network.py	77.50%	7 Missing and 2 partials ⚠️
canopen/sdo/base.py	74.19%	8 Missing ⚠️
canopen/lss.py	77.77%	2 Missing ⚠️
canopen/nmt.py	87.50%	1 Missing and 1 partial ⚠️
canopen/emcy.py	88.88%	1 Missing ⚠️
canopen/objectdictionary/eds.py	80.00%	1 Missing ⚠️
canopen/sdo/client.py	96.42%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[sveinse]

This branch is ready for review and integration into the project. Its not fully complete (I suppose it never will). The biggest lack is that there is no documentation for async.

The branch's README (https://github.com/sveinse/canopen-asyncio?tab=readme-ov-file#difference-between-async-and-non-async-version) contains an overview over the current differences between this branch and the main project.

The port is quite "naive" async-wise as it relies on asyncio.to_thread() on many async operations, which not ideal. The back-end of the canopen library relies on synchronous callbacks which doesn't work too well from an async perspective. To be able to support both non-async (regular) and async use, this approach have been chosen. In time I hope we can refactor the inner working of the library such that we can do it independent of the communication (e.g. vis sansio).

[acolomb]

Phew, that's a lot of material and I hope you don't mind my elaborate review comments. But first, let's take a step back and see if we can better define what the PR does and what the goals are.

I'm not really experienced with asyncio based programming in Python, but I do know pretty well what an event loop and coroutines are. So my main mental challenge with this is trying to imagine what an application would really look like if using asyncio to handle its functionality elegantly. From own experience, I'd say moving long-blocking background activities from threads to a (cooperatively scheduled) task is one of the main motivations -- such as waiting for a drive homing procedure to finish.

My impression on what this focuses on, with some overall remarks about the implementation:

1. Finding and marking all API functions potentially blocking on I/O. This is a useful thing in itself, but I don't think we want the NOTE comments in the code indefinitely. It makes sense to gather findings like you did now, but provides little extra value to the library consumer and will bit-rot really fast I suppose.

2. Detecting improper use of blocking functions in async context, which would block the main loop. This is useful but totally optional IMHO, so could better be moved to its own PR to focus on the actual async capabilities first. An approach with a single assert canopen.async_guard.ensure_not_async line (or similar) could be just as good as the decorator approach, but clearer.

3. Arranging user callbacks to be scheduled in the event loop instead of called immediately. I see several alternatives to the current dispatcher solution, so let's clarify what situation this applies to: A CAN message arrives on the network and the application needs to passively react to this external trigger. The reaction may be an internal callback (as in p402.py) or an arbitrarily long-running external application function. This uncertainty must be contained to not block the main event loop. Traditionally, it is executed inside the RX thread of python-can's Notifier anyway, blocking that at worst. There is already functionality in there to schedule callbacks as tasks if they are coroutines, execute directly otherwise. So the easiest would be for the application to provide a coroutine directly as callback -- this just needs to be passed through the canopen library, so that the listener is also an async / await wrapper around the application callback. But shouldn't it be an application responsibility to decide whether the callback happens inside the RX background thread, or as a task on the event loop?

4. Provide async (coroutine) variants of common blocking operation methods. This is the core of the "async integration" API-wise. But it's actually much less of a concern than the callback handling. Because the caller can always just do as you did in many places, calling await asyncio.to_thread() on the existing synchronous function. Some of the really interesting functions are not converted to async variants yet. I suppose that to_thread() approach is a stop-gap solution before implementing real, awaitable internal methods.

5. Add unit tests for the new API. This is probably the largest portion of the diff, but I haven't checked it thoroughly as these high-level review points must be discussed and solved first.

Sorry if I missed something now, or it's just my lack of understanding asyncio in general. Plus I get too tired when tackling such a complex and large review late at night. But that's already lots of food for discussion I suppose.

[acolomb]

As discussed in #556, this can simply be set between __init__() and connect(), with the latter only creating one if not already set (as you did).

[sveinse]

Yes, that should be possible. Why the reluctance to add to the signature of __init__() thou? It is not altering any existing behavior.

I personally find the first more elegant that the latter:

# Easy
network = Network(bus=bus, notifier=mynotifier)

# More clunky
network = Network(bus=bus)
network.notifier = mynotifer

[acolomb]

Should be a @property.

[sveinse]

Fixed. I'm curious: What makes you want this to be a property? What's wrong with a method?

[acolomb]

This is one of the central elements it seems, making it easy to influence what exactly "invoking a callback" means and does. The approach is alright and the Network seems like a good place to handle such a definition centrally.

However, I'm unsure whether this is the best / only solution regarding callbacks. One alternative that springs to mind is to wrap each given callback function when it is registered somewhere, replacing it with a callable that creates the corresponding task instead of executing the given callback directly.

[sveinse]

I'm not sure what you precisely mean by the first comment, but the term "callback" is consistently used for any function that that handles incoming CAN messages via the notification & listener system from python-can.

The reason for adding def dispatch_callbacks() is that coroutine callbacks needs special steps to be called. In order to run a coroutine a task be created and the future object must be kept so the GC doesn't delete the object before ever running the callback.

[acolomb]

This sounds a lot like duplicating what python-can already provides. Can we embrace that lower-level concept more instead of building our own dispatcher?

[sveinse]

Yes we can. It does require a refactor of the callback system if we want that. See the main comment for more.

[acolomb]

Since there is no blocking access, we don't really need the async method variants on the SdoServer (nor SdoBase for that matter). Unless LocalNode.get_data() is also allowed to be a blocking access pattern, implemented as a coroutine itself, there is no value in wrapping it here like this. The only expected blocking I/O on the library side is the SdoClient, thus the async methods can be introduced only there.

[sveinse]

The idea I've attempted to be consistent about is that the async API should mirror the regular API (that's what you'd expect from an async API, right?). The SdoServer.aupload() implementation happen to be equal to SdoServer.upload() and could be removed. On the other hand SdoClient.aupload() is not equal to SdoClient.upload(). It happens to be that way because of how we've implemented SdoServer. Should the user need to know that when using it? If we do remove SdoServer.aupload() the user will have to change its implementation if SdoServer.upload() becomes blocking and we then need SdoServer.aupload().

[acolomb]

I like this solution. Maybe a similar pattern can be applied in other places?

[sveinse]

Yes, this concept is called sansio. This is what we need to make the SDO protocol handlers and all the other completely independent of what IO type (blocking vs async) is used. Basically its a system to put data in -> get something to send. Rinse and repeat until done.

[sveinse]

Thank you for reviewing them @acolomb. You certainly did a thorough job! I'm currently on a sick leave, so I don't think I'll get any change to look at them immediately thou. This is what I propose as next steps:

1. Let me sync this branch so it aligns with the current master. I haven't done that in a very long while
2. I will review your comments and potentially make fixes where the resolution is obvious

Regarding the "NOTE" and "Blocking call". These are markers I put in the after doing an investigation of what breaks. As we've been discussing before, this library does a lot of blocking IO in unconventional calls, such as in properties, so it took some efforts to find them all. My intentions is to remove these markers before the final merge.

[sveinse]

Again, thank you @acolomb for the detailed review. This is a lengthy reponse, with this comment and the answers to the code comments.

I've update the PR to align with the current master and I've made cleanups and some fixes. I hope you'll find the PR less cluttered now.

I recognize that this PR is huge and it contains many different elements. Should we maybe split this PR into multiple parts?

There is an elephant in the room: Is getting this adopted into canopen the way everyone wants it is too much effort? Perhaps the need for having async support isn't that big. This can live side by side.

Goal

The overall goal for this initiative is to add async support to canopen. With it the user shall be able to decide if the canopen library should be used with regular blocking calls or using asyncio. With async the user will be able to invoke many concurrent requests without needing to revert to threads.

Challenges

• How to make the listener notification / callback back-end system workable for both regular non-async and for async mode.

• How to implement application and protocol logic without ending up with duplicated non-async and async implementation.

• Naming conventions for the regular API vs the async API. Where save() something exists, should we have asave or `async_save?

• API completeness. Should the async API completely mirror the regular API, or just a select few methods?

• How to make good unit tests with both regular and async API

In use

I'd like to mention that the asyncio port isn't untested. At work we use canopen-asyncio as a central development and test tool for the CAN-based products we use and make. We've used it since 2021 (!) when the port was created. These CAN networks typically contains 30-40 canopen nodes, running in parallell with other non-canopen protocols. The asyncio port have been very successful at communicating with many nodes simultaneously, such as doing SDO to different nodes while handling PDOs with others. The code in each task becomes simple to write with no event or "callback-hell" (which is the main advantage of async)

Answers to key questions

2. Detecting improper use of blocking functions in async context, which would block the main loop. This is useful but totally optional IMHO, so could better be moved to its own PR to focus on the actual async capabilities first. An approach with a single assert canopen.async_guard.ensure_not_async line (or similar) could be just as good as the decorator approach, but clearer.

Let's do this in a separate PR. When apps are done right, these guards aren't really needed. But this protection has proven to be most useful, especially when working on async vs non-async development. An incorrect blocking IO call is easy to do by mistake and finding them without the guard can be very challenging.

Which of these two approaches do you think is most clean? I assume you prefer alternative 2?

# Alternative 1
@ensure_not_async
def something_to_protect():
    ...

# Alternative 2
def something_to_protect():
    assert canopen.async_guard.ensure_not_async()
    ...

3. Arranging user callbacks to be scheduled in the event loop instead of called immediately. I see several alternatives to the current dispatcher solution, so let's clarify what situation this applies to: A CAN message arrives on the network and the application needs to passively react to this external trigger. The reaction may be an internal callback (as in p402.py) or an arbitrarily long-running external application function. This uncertainty must be contained to not block the main event loop. Traditionally, it is executed inside the RX thread of python-can's Notifier anyway, blocking that at worst. There is already functionality in there to schedule callbacks as tasks if they are coroutines, execute directly otherwise. So the easiest would be for the application to provide a coroutine directly as callback -- this just needs to be passed through the canopen library, so that the listener is also an async / await wrapper around the application callback. But shouldn't it be an application responsibility to decide whether the callback happens inside the RX background thread, or as a task on the event loop?

This is a key question and it has huge impact on the overall design. There are indeed several ways of doing it.

It is correct that python-can have a mechanism for calling coroutines on rx of CAN messages. If the callback, i.e. can.Listener.__call__() is a coroutine, it will make an async task.

However, all incoming messages are wrapped via Network.notify() which is a regular callback, so any async callbacks deeper in the canopen stack (e.g. in NmtMaster, Emcy) can't utilize this.

There is a way around this if each callback in canopen implements a can.Listener object and registers itself with with the network.notifier.add_listener(). This way callbacks will go directly from python can into the callback instead of a long chain RX trhread -> can.Notifier._on_message_received() -> MessageListener.on_message_received() -> Network.notify() -> the specific callback. It does require a considerable refactor of the callback system (which is independent of async).

Arranging user callbacks to be scheduled in the event loop instead of called immediately.

The whole back-end listener / notification system is based on regular functions which are called immediately in the rx thread. Any user provided non-async callbacks will also be executed in the rx thread. In both async and non-async mode currently. Any coroutine callbacks, will always be executed in the event loop thread.

4. Provide async (coroutine) variants of common blocking operation methods. This is the core of the "async integration" API-wise. But it's actually much less of a concern than the callback handling. Because the caller can always just do as you did in many places, calling await asyncio.to_thread() on the existing synchronous function. Some of the really interesting functions are not converted to async variants yet. I suppose that to_thread() approach is a stop-gap solution before implementing real, awaitable internal methods.

Yes, asyncio.to_thread() is a stop-gap solution. It is not particularly efficient (since it spawns a thread for each call). We should strive to avoid the use of it and we should definitely not have the user need to rely on it for operating the library in async mode.

We currently need this internally because of the way the back-end listener / notification system is built and the usage of blocking locking primitives.

We could completely avoid asyncio.to_thread() if the notifier callback back-end were implemented with async in mind. However that will require double implementation, which is not idea. I have tested this concept. See here for examples of how it might look like. Not very elegant.

5. Add unit tests for the new API. This is probably the largest portion of the diff, but I haven't checked it thoroughly as these high-level review points must be discussed and solved first.

Choosing test strategy was a choice between a rock and a hard place when making the test setup. There are (at least) two options for a dual-stack setup like this:

1. Duplicate all tests. One function for the regular functon test, one for async
2. Make every function runnable in two modes; regular and async mode

So far I've chosen the latter and the first easily makes the async and non-aync drift a part. But I'm not liking the implications the dual mode tests. It makes the unit tests very clunky and very hard to update.