asyncio Unterstützung in Plugins Neu

Python Packages zur Ansteuerung von Peripherie werden zunehmend unter Verwendung von asyncio erstellt. Um diese Packages in Plugins nutzen zu können, muss das jeweilige Plugin asyncio unterstützen. Die Implementierung hiervon ist nicht tirvial und die ersten Plugins die asyncio implementiert haben, tun das sehr unterschiedlich und unter Nutzung der Low-Level Funktionen von asyncio (was ein erhebliches Error-Handling im Plugin voraussetzt).

Um die Nutzung von asyncio zu vereinfachen und in den Plugins zu standardisieren, unterstützt SmartHomeNG ab v1.11 die Nutzung von asyncio in Plugins durch eine Erweiterung der SmartPlugin Klasse um einige Methoden.

Ein Plugin welches die neue asyncio Unterstützung nutzt, ist das hue3 Plugin. Es kann bei der der Erstellung eines neuen Plugins als Beispiel herangezogen werden. |

Methoden zur Unterstützung von asyncio

Im folgenden sind die Methoden beschrieben, die zur asyncio Unterstützung zur SmartPlugin Klasse hinzugekommen sind.

class lib.model.smartplugin.SmartPlugin(**kwargs)

Bases: SmartObject, Utils

The class SmartPlugin implements the base class of all smart-plugins. The implemented methods are described below.

In addition the methods implemented in lib.utils.Utils are inherited.

asyncio_state()

Returns the state of asyncio for the plugin

• ‚unused‘ - If the plugin does not use asyncio (the start_asyncio method has not been successfully executed)

• ‚running‘ - An active eventloop is beeing processed

• ‚stopped‘ - There is no active eventloop

Rückgabetyp:

str

Rückgabe:

‚unused‘ | ‚running‘ | ‚stopped‘

start_asyncio(plugin_coro)

Start the thread for the asyncio loop

The started asyncio thread sets up the asyncio environment and starts the eventloop. The given plugin_coro is added as the main task to the eventloop.

This routine is to be called from the plugin’s run() method

Parameter:

plugin_coro (Coroutine) – The asyncio coroutine which implements the async part of the plugin

Rückgabetyp:

None

stop_asyncio()

stop the eventloop and the thread it is running in

This routine is to be called from the plugin’s stop() method.

Rückgabetyp:

None

run_asyncio_coro(coro, return_exeption=False)

Run a coroutine in the eventloop of the plugin

When the asyncio eventloop of the plugin is running, this method can be used to add a coroutine to the eventloop from the part of the plugin which is thread operated. E.g.: This can be used in the plugins update_item() method to send data to the device through an asyncio package.

This method waits for the coroutine to be finished, to be able to return the result of the coroutine.

Parameter:

• coro (Coroutine) – A coroutine that should be run in the eventloop of the asyncio-thread

• return_exeption (bool) – If set to True, run_asyncio_coro returns exceptions instead of handling (logging) them itself

Rückgabetyp:

Any

return: The result of the coroutine

async wait_for_asyncio_termination()

Wait for the command to stop the plugin_coro

This is used to block the plugin_coro until the plugin should be stopped.

When the plugin should be stopped, a string ‚STOP‘ is written into the queue

Rückgabetyp:

None

put_command_to_run_queue(command)

Put an entry to the run-queue (if implemented in the plugin_coro)

Parameter:

command (str) – command to be executed by the plugin_coro

Rückgabetyp:

None

async get_command_from_run_queue()

Get an entry from the run-queue

When the plugin should be stopped, a string ‚STOP‘ is written into the queue and the plugin_coro can check for the string ‚STOP‘ and terminate itself.

Rückgabetyp:

str

Rückgabe:

First command from the queue

async list_asyncio_tasks()

Log a list of the tasks that are in the eventloop

The intention of this method is to support the plugin development/debugging. It can be called from the executor plugin or from the eval-syntax-checker of the admin gui

Rückgabetyp:

None