Skip to content

Parallelism and threads in automations

Leonard Sperry edited this page Nov 28, 2024 · 8 revisions

V10.2

In Home Assistant, there is a concept of a "mode" for an automation. The possible values for this mode are Single, Restart, Queued, and Parallel. See Home Assistant documentation for exact details. Modes are important when your entities trigger faster than your automations can run. They are a mechanism you can use to ensure your system does not become overburdened.

HaKafkaNet also has these modes, and they behave very similarly. However, HaKafkaNet adds one additional Smart mode which is the default. This documentation applies to the Execute method of simple automations and the ContinuesToBeTrue method of delayed automations. See Delayed Automations below for more details.

To set the mode of an automation, either update its Metadata or use the WithMode method of the IAutomationBuilder.

Single

For automations created in Home Assistant this is the default. This mode ensures that only one execution runs at a time. While an automation is running, subsequent triggers are ignored. This is the most performant mode, but it has the draw-back that the last (most recent) trigger could be ignored.

Restart

This mode attempts to ensure that at any point, only one execution is running. It does this by requesting a cancellation via the cancellation token passed to your automation.

Note: If your code does not utilize the state of the cancellation token, you could still end up with multiple thread execution.

Queued

Similar to Single this mode does ensure only one execution at a time. However, any triggers during an execution are queued. All triggers will execute sequentially.

Note: HaKafkaNet does not implement MaxQueueLength. If your trigger continues to fire, this could put pressure on your system's memory

Parallel

Prior to version 10.2, this was the default behavior in HaKafkaNet. All triggers will run in parallel.

Note: this mode can lead to thread pool exhaustion.

Smart

This is the default mode for HaKafkaNet. Its behavior is nearly identical to Single. However, instead of ignoring subsequent triggers, it keeps track of the most recent trigger. After an automation runs, if there is a tracked trigger, it will also execute. This ensures that the most recent state is always represented.

Delayed Automations

All automations that implement the IDelayableAutomation interface, which includes both ICondionalAutomation and ISchedulableAutomation will only have 1 instance of a delay per instance of the automation. So, in a way this aligns with what Home Assistant would call "Single".

Example:

  • An entity triggers a delayed automation rapidly.
  • The mode selected will determine how often and when the ContinuesToBeTrue method is called.
  • After the first time that ContinuesToBeTrue returns true, the execution will be scheduled.
  • As long as the trigger continues to return true, the execution will happen exactly 1 time. Executions are not scheduled multiple times for multiple triggers.