Skip to main content
Version: 0.8.0

Reactions

This article has examples in the following target languages:

Reaction Declaration

A reaction declaration has the following form:

reaction [<name>] (triggers) [<uses>] [-> <effects>] [{= ... body ...=}]

Each reaction declares its triggers, uses, and effects:

  • The triggers field can be a comma-separated list of input ports, output ports of contained reactors, timers, actions, or the special events startup, shutdown, and reset (explained here>). There must be at least one trigger for each reaction.
  • The uses field, which is optional, specifies input ports (or output ports of contained reactors) that do not trigger execution of the reaction but may be read by the reaction.
  • The effects field, which is also optional, is a comma-separated lists of output ports ports, input ports of contained reactors, or actions.

Reactions may optionally be named. The name is cosmetic and may serve as additional documentation. Note that reactions cannot be called like functions, even if they are named.

The reaction's behavior is defined by its body, which should be given in the target programming language. Note that the reaction body may only read from actions and ports that it has declared as triggers or uses, and it may only write to actions and ports that is has declared as an effect. The target code generators implement a scoping mechanism, such that only variables that are declared in the reaction signature are accessible in the reaction body.

In some targets, the reaction body may be omitted and the body can be defined natively in the target language in an external file. See the section on Bodyless Reactions for details.

Reaction Order

A reactor may have multiple reactions, and more than one reaction may be enabled at any given tag. In Lingua Franca semantics, if two or more reactions of the same reactor are simultaneously enabled, then they will be invoked sequentially in the order in which they are declared. More strongly, the reactions of a reactor are mutually exclusive and are invoked in tag order primarily and declaration order secondarily. Consider the following example:

target C { timeout: 3 secs } main reactor Alignment { state s: int = 0 timer t1(100 msec, 100 msec) timer t2(200 msec, 200 msec) timer t4(400 msec, 400 msec) reaction(t1) {= self->s += 1; =} reaction(t2) {= self->s -= 2; =} reaction(t4) {= printf("s = %d\n", self->s); =} }

Every 100 ms, this increments the state variable s by 1, every 200 ms, it decrements s by 2, and every 400 ms, it prints the value of s. When these reactions align, they are invoked in declaration order, and, as a result, the printed value of s is always 0.

Overwriting Outputs

Just as the reactions of the Alignment reactor overwrite the state variable s, logically simultaneous reactions can overwrite outputs. Consider the following example:

target C reactor Overwriting { output y: int state s: int = 0 timer t1(100 msec, 100 msec) timer t2(200 msec, 200 msec) reaction(t1) -> y {= self->s += 1; lf_set(y, self->s); =} reaction(t2) -> y {= self->s -= 2; lf_set(y, self->s); =} }

Here, the reaction to t1 will set the output to 1 or 2, but every time it sets it to 2, the second reaction (to t2) will overwrite the output with the value 0. As a consequence, the outputs will be 1, 0, 1, 0, ... deterministically.

Reacting to Outputs of Contained Reactors

A reaction may be triggered by the an input to the reactor, but also by an output of a contained reactor, as illustrated in the following example:

target C import Overwriting from "Overwriting.lf" main reactor { s = new Overwriting() reaction(s.y) {= if (s.y->value != 0 && s.y->value != 1) { lf_print_error_and_exit("Outputs should only be 0 or 1!"); } =} }
Lingua Franca diagram: ContainedCreator: FreeHEP Graphics2D Driver Producer: de.cau.cs.kieler.klighd.piccolo.freehep.SemanticSVGGraphics2D Revision Source: Date: Tuesday, March 29, 2022 at 4:36:03 PM Pacific Daylight TimeContaineds : Overwriting(100 msec, 100 msec)(200 msec, 200 msec)21y

This instantiates the above Overwriting reactor and monitors its outputs.

Triggering Contained Reactors

A reaction can set the input of a contained reactor, thereby triggering its reactions, as illustrated in the following example:

target C reactor Inside { input x: int reaction(x) {= printf("Received %d\n", x->value); =} } main reactor { i = new Inside() reaction(startup) -> i.x {= lf_set(i.x, 42); =} }

The reaction to startup declares the input port of the inside reactor as an effect and then sets it with value 42. This will cause the inside reactor's reaction to execute and print Received 42.

Startup, Shutdown, and Reset Reactions

Reactions may be triggered by the special events startup, shutdown, or reset. For example,

reaction(startup) {= // ... Do something =}

A reaction to startup is triggered at the very first tag when the program begins (or, if within a mode of a modal reactor, when the mode is first entered). This reaction will be logically simultaneous with reactions to timers that have a zero offset. As usual, for logically simultaneous reactions declared within the same reactor, the order in which they are invoked will be governed by the order in which they are declared.

A reaction to shutdown is invoked at program termination. See the Termination section for details.

Reactions to the reset event are not supported in $target-language$ because modal reactors are not supported.

Bodyless Reactions

See Reaction Declarations.