|
| 1 | +--- |
| 2 | +layout: page |
| 3 | +title: "Working with Async" |
| 4 | +description: "A breakdown of all the different ways to work with the asynchronous core of Home Assistant." |
| 5 | +date: 2016-10-17 21:49 |
| 6 | +sidebar: true |
| 7 | +comments: false |
| 8 | +sharing: true |
| 9 | +footer: true |
| 10 | +--- |
| 11 | + |
| 12 | +Although we have a backwards compatible API, using the async core directly will be a lot faster. Most core components have already been rewritten to leverage the async core. This includes the EntityComponent helper (foundation of light, switch, etc), scripts, groups and automation. |
| 13 | + |
| 14 | +## {% linkable_title Interacting with the core %} |
| 15 | + |
| 16 | +[All methods in the Home Assistant core][dev-docs] are implemented in two flavors: an async version and a version to be called from other threads. The versions for other are merely wrappers that call the async version in a threadsafe manner using [the available async utilities][dev-docs-async]. |
| 17 | + |
| 18 | +So if you are making calls to the core (the hass object) from within a callback or coroutine, use the methods that start with async_. If you need to call an async_ function that is a coroutine, your task must also be a coroutine. |
| 19 | + |
| 20 | +## {% linkable_title Implementing an async component %} |
| 21 | + |
| 22 | +We currently do not support async setup for components. We do however support using async functions as service handlers. Just define your handlers as a callback or coroutine and register them as usual. |
| 23 | + |
| 24 | +## {% linkable_title Implementing an async platform %} |
| 25 | + |
| 26 | +For platforms we support async setup. Instead of setup_platform you need to have a coroutine async_setup_platform. |
| 27 | + |
| 28 | +```python |
| 29 | +setup_platform(hass, config, add_entities, discovery_info=None): |
| 30 | + # Setup your platform outside of the event loop. |
| 31 | +``` |
| 32 | + |
| 33 | +Will turn into: |
| 34 | + |
| 35 | +```python |
| 36 | +import asyncio |
| 37 | + |
| 38 | +@asyncio.coroutine |
| 39 | +def async_setup_platform(hass, config, async_add_entities, |
| 40 | + discovery_info=None): |
| 41 | + # Setup your platform inside of the event loop |
| 42 | +``` |
| 43 | + |
| 44 | +The only difference with the original parameters is that the add_entities function has been replaced by the coroutine `async_add_entities`. |
| 45 | + |
| 46 | +## {% linkable_title Implementing an async entity %} |
| 47 | + |
| 48 | +You can make your entity async friendly by converting your update method to be async. This requires the dependency of your entities to also be async friendly! |
| 49 | + |
| 50 | +```python |
| 51 | +class MyEntity(Entity): |
| 52 | + def update(self): |
| 53 | + """Retrieve latest state.""" |
| 54 | + self._state = fetch_state() |
| 55 | +``` |
| 56 | + |
| 57 | +Will turn into: |
| 58 | + |
| 59 | +```python |
| 60 | +import asyncio |
| 61 | + |
| 62 | +class MyEntity(Entity): |
| 63 | + @asyncio.coroutine |
| 64 | + def async_update(self): |
| 65 | + """Retrieve latest state.""" |
| 66 | + self._state = yield from async_fetch_state() |
| 67 | +``` |
| 68 | + |
| 69 | +Make sure that all properties defined on your entity do not result in I/O being done. All data has to be fetched inside the update method and cached on the entity. This is because these properties are read from within the event loop and thus doing I/O will result in the core of Home Assistant waiting until your I/O is done. |
| 70 | + |
| 71 | +## {% linkable_title Calling async functions from threads %} |
| 72 | + |
| 73 | +Sometimes it will happen that you’re in a thread and you want to call a function that is only available as async. Home Assistant includes a few async helper utilities to help with this. |
| 74 | + |
| 75 | +In the following example, `say_hello` will schedule `async_say_hello` and block till the function has run and get the result back. |
| 76 | + |
| 77 | +```python |
| 78 | +from homeassistant.util.async import run_callback_threadsafe |
| 79 | + |
| 80 | +def say_hello(hass, target): |
| 81 | + return run_callback_threadsafe( |
| 82 | + hass.loop, async_say_hello, target).result() |
| 83 | + |
| 84 | +def async_say_hello(hass, target): |
| 85 | + return "Hello {}!".format(target) |
| 86 | +``` |
| 87 | + |
| 88 | +## {% linkable_title Dealing with passed in functions %} |
| 89 | + |
| 90 | +If your code takes in functions from other code, you will not know which category the function belongs to and how they should be invoked. This usually only occurs if your code supplies an event helper like `mqtt.async_subscribe` or `track_state_change_listener`. |
| 91 | + |
| 92 | +To help with this, there are two helper methods on the hass object that you can call from inside the event loop: |
| 93 | + |
| 94 | +#### {% linkable_title hass.async_run_job %} |
| 95 | + |
| 96 | +Use this method if the function should be called as soon as possible. This will call callbacks immediately, schedule coroutines for execution on the event loop and schedule other functions to be run inside the thread pool. |
| 97 | + |
| 98 | +| Callback | Call immediately. |
| 99 | +| Coroutine | Schedule for execution on the event loop. |
| 100 | +| Other functions | Schedule for execution in the thread pool. |
| 101 | + |
| 102 | +#### {% linkable_title hass.async_add_job %} |
| 103 | + |
| 104 | +Use this method if the function should be called but not get priority over already scheduled calls. |
| 105 | + |
| 106 | +| Callback | Schedule for execution on the event loop. |
| 107 | +| Coroutine | Schedule for execution on the event loop. |
| 108 | +| Other functions | Schedule for execution in the thread pool. |
| 109 | + |
| 110 | +### [Next step: Miscellaneous »](/developers/asyncio_misc/) |
| 111 | + |
| 112 | +[dev-docs]: https://dev-docs.home-assistant.io/en/master/api/core.html |
| 113 | +[dev-docs-async]: https://dev-docs.home-assistant.io/en/dev/api/util.html#module-homeassistant.util.async |
0 commit comments