Skip to content

Concept/Rules: Document parallelism of rule execution #2573

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
florian-h05 merged 5 commits into from
Dec 19, 2025
Merged

Concept/Rules: Document parallelism of rule execution #2573

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
aace84a
concept/rules: state that a rule cannot be executed in parallel
dilyanpalauzov Oct 4, 2025
44bfc10
Apply suggestions from code review
florian-h05 Dec 17, 2025
8b7fed6
Apply suggestions from code review
florian-h05 Dec 17, 2025
c6bdb22
Review changes
florian-h05 Dec 19, 2025
e546dd8
Review changes
florian-h05 Dec 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions concepts/rules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,14 @@ openHAB can send a notification to your phone.
Other systems may have a concept of _Automations_, _Tasks_, and other terms.
In openHAB, rules are used to implement all of these concepts.

Rules can be executed, either when fired by their triggers, or when called explicitly - from a script, another rule, or a Main UI widget.
Copy link
Copy Markdown
Contributor Author

@dilyanpalauzov dilyanpalauzov Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There should be no or here. It is possible to execute a rule by calling RunNow. So the list is not exclusive and therefore there should be no final or.

Copy link
Copy Markdown
Contributor

@Nadahar Nadahar Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's not correct, that's not a rule in English and the first form is just invalid/incomplete. Perhaps this rule exists in another language?

Copy link
Copy Markdown
Contributor Author

@dilyanpalauzov dilyanpalauzov Dec 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Omitting conjunctions in a list it discussed at https://english.stackexchange.com/questions/15970/omitting-and-in-a-sentence .

https://www.litcharts.com/literary-devices-and-terms/asyndeton says “Lists that do not include conjunctions leave open the possibility that there could be more elements within a series.”

Copy link
Copy Markdown
Contributor

@Nadahar Nadahar Dec 18, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They are discussing "creative writing", not formal documentation, and the way it's used in the example there is much more "acceptable" than simply ending a sentence in what feels like without completing it.

What I would typically do in such a situation, where I don't want to give the impression that the list is exclusive, is:
"for example from a script, another rule or a Main UI widget."

Copy link
Copy Markdown
Contributor

@rkoshak rkoshak Dec 18, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's not correct, that's not a rule in English and the first form is just invalid/incomplete. Perhaps this rule exists in another language?

It's not a rule of grammar for English in general, but there can be rules set down in style guides and context.

Usually, in technical or academic writing, asyndetons are to be avoided or used sparingly and in a way that does not disrupt the formal tone of the writing.

OH docs do not really follow any specific writing style guide (e.g. MLA, Chicago, AP, IEEE, etc.) but it would qualify as technical and therefore more formal writing. Probably the guide that would be most applicable to the OH docs would be IEEE which, while not mentioning asyndeton by name, has rules which effectively discourage its use in favor of syndetic writing. I can find the exact reference if desired, but this AI summary matches with what I know.

The IEEE Editorial Style Manual and associated technical writing standards do not explicitly mention "asyndeton" by name. Instead, they provide strict grammatical rules for series and lists that effectively discourage asyndetons in favor of clarity and precision.

The consensus for IEEE style can be summarized through its established rules on series and clarity:
Requirement for Conjunctions: IEEE style generally requires a coordinating conjunction (e.g., "and", "or") before the final term in a series to ensure the relationship between items is unambiguous.
The Serial (Oxford) Comma: IEEE dictates using a comma after each term in a series of three or more, followed by a conjunction (e.g., "A, B, and C"). This rule directly contradicts the structure of asyndeton ("A, B, C").
Clarity over Rhetoric: In technical fields like engineering and computing, the primary goal is unambiguous communication. Asyndetons can create "choppy" prose or leave the reader uncertain if a list is complete, which violates IEEE’s emphasis on professionalism and consistency.
Deferral to Chicago Style: For grammatical points not explicitly covered in its own manual, IEEE officially defers to The Chicago Manual of Style. Chicago permits asyndeton in narrative or literary prose but suggests it be avoided in formal or technical contexts where logic and flow are paramount.

Context Preferred (Syndetic) Discouraged (Asyndetic)
Technical Series The system requires a sensor, a processor, and a battery. The system requires a sensor, a processor, a battery.
Author Lists J. Smith and W. Jones [9]. J. Smith, W. Jones [9].
Equations I=1,2,3,…,ncap I equals 1 comma 2 comma 3 comma … comma n𝐼=1,2,3,…,𝑛 I=1,2,3cap I equals 1 comma 2 comma 3𝐼=1,2,3 (unclear if it continues)

In formal writing, if you wanted to omit the "or" and indicate that the list is not complete use "etc.".

Rules can be executed, either when fired by their triggers, or when called explicitly - from a script, another rule, a Main UI widget, etc.

While this seems to violate the rule, the "or" is implit in the word "etcetera" so can be omitted.

When a rule is fired by its trigger, the execution of one and the same rule does not happen in parallel.
If a rule is triggered for execution, while the rule is currently running, it will be queued and run later.

When a rule is called explicitly - from a script, another rule with [`RuleManager.runNow()`](https://www.openhab.org/javadoc/latest/org/openhab/core/automation/rulemanager), from a MainUI widget, then this rule can be executed in parallel.
That is it can start running, while the same rule is executed at the same time.
In this case there is a need to program protection against race conditions.

## Parts of a Rule

These rules take the high level form of _When \_\_t\_\_ happens, if \_\_c\_\_ then do \_\_a\_\__,
Expand Down
3 changes: 2 additions & 1 deletion configuration/rules-dsl.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -801,7 +801,8 @@ Caveat: Please note the semicolon after the return statement which terminates th

### Concurrency Guard

If a rule triggers on UI events it may be necessary to guard against concurrency.
If a rule is explicitly run from another script, rule, MainUI widget, instead of a trigger, the rule can be started before the current execution has ended.
Copy link
Copy Markdown
Contributor

@florian-h05 florian-h05 Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If a rule is explicitly run from another script, rule, MainUI widget, instead of a trigger, the rule can be started before the current execution has ended.
If a rule is explicitly run from another script, rule, a Main UI widget, instead of a trigger, the rule can be started before the current execution has ended.

It may be necessary to guard against concurrency.

```javascript
import java.util.concurrent.locks.ReentrantLock
Expand Down