Skip to main content
Version: 0.8.0

Composing Reactors

This article has examples in the following target languages:

Contained Reactors​

Reactors can contain instances of other reactors defined in the same file or in an imported file. Assume the Count and Scale reactors defined in Parameters and State Variables are stored in files Count.lf and Scale.lf, respectively, and that the TestCount reactor from Time and Timers is stored in TestCount.lf. Then the following program composes one instance of each of the three:

target C { timeout: 1 sec, fast: true } import Count from "Count.lf" import Scale from "Scale.lf" import TestCount from "TestCount.lf" main reactor RegressionTest { c = new Count() s = new Scale(factor=4) t = new TestCount(stride=4, num_inputs=11) c.y -> s.x s.y -> t.x }

Diagrams​

As soon as programs consist of more than one reactor, it becomes particularly useful to reference the diagrams that are automatically created and displayed by the Lingua Franca IDEs. The diagram for the above program is as follows:

Lingua Franca diagram: RegressionTestCreator: FreeHEP Graphics2D Driver Producer: de.cau.cs.kieler.klighd.piccolo.freehep.SemanticSVGGraphics2D Revision Source: Date: Sunday, March 27, 2022 at 4:32:52 PM Pacific Daylight TimeRegressionTestt : TestCount21xs : Scalexyc : Count(0, 100 msec)y

In this diagram, the timer is represented by a clock-like icon, the reactions by chevron shapes, and the shutdown event by a diamond. If there were a startup event in this program, it would appear as a circle.

Creating Reactor Instances​

An instance is created with the syntax:

<instance_name> = new <class_name>(parameters)

A bank with several instances can be created in one such statement, as explained in the banks of reactors documentation.

The <parameters> argument is a comma-separated list of assignments:

<parameter_name> = <value>, ...

Like the default value for parameters, <value> can be a numeric constant, a string enclosed in quotation marks, a time value such as 10 msec, target-language code enclosed in {= ... =}, or any of the list forms described in Expressions.

Connections​

Connections between ports are specified with the syntax:

<source_port_reference> -> <destination_port_reference>

where the port references are either <instance_name>.<port_name> or just <port_name>, where the latter form is used for connections that cross hierarchical boundaries, as illustrated in the next section.

On the left and right of a connection statement, you can put a comma-separated list. For example, the above pair of connections can be written,

c.y, s.y -> s.x, t.x

A constraint is that the total number of channels on the left match the total number on the right. In addition, some targets require the types of all the ports to be the same.

A destination port (on the right) can only be connected to a single source port (on the left). However, a source port may be connected to multiple destinations, as in the following example:

reactor A { output y:int } reactor B { input x:int } main reactor { a = new A() b1 = new B() b2 = new B() a.y -> b1.x a.y -> b2.x }
Lingua Franca diagram: MulticastCreator: FreeHEP Graphics2D Driver Producer: de.cau.cs.kieler.klighd.piccolo.freehep.SemanticSVGGraphics2D Revision Source: Date: Saturday, April 2, 2022 at 5:45:26 PM Pacific Daylight TimeMulticast1a : Ayb2 : Bxb1 : Bx

Lingua Franca provides a convenient shortcut for such multicast connections, where the above two lines can be replaced by one as follows:

(a.y)+ -> b1.x, b2.x

The enclosing ( ... )+ means to repeat the enclosed comma-separated list of sources however many times is needed to provide inputs to all the sinks on the right of the connection ->.

Import Statement​

An import statement has the form:

import <classname> as <alias> from "<path>"

where <classname> and <alias> can be a comma-separated list to import multiple reactors from the same file. The <path> specifies another .lf file relative to the location of the current file. The as <alias> portion is optional and specifies alternative class names to use in the new statements.

Hierarchy​

Reactors can be composed in arbitrarily deep hierarchies. For example, the following program combines the Count and Scale reactors within on Container:

target C import Count from "Count.lf" import Scale from "Scale.lf" import TestCount from "TestCount.lf" reactor Container(stride: int = 2) { output y: int c = new Count() s = new Scale(factor=stride) c.y -> s.x s.y -> y } main reactor Hierarchy { c = new Container(stride=4) t = new TestCount(stride=4, num_inputs=11) c.y -> t.x }
Lingua Franca diagram: HierarchyCreator: FreeHEP Graphics2D Driver Producer: de.cau.cs.kieler.klighd.piccolo.freehep.SemanticSVGGraphics2D Revision Source: Date: Tuesday, March 29, 2022 at 10:10:43 AM Pacific Daylight TimeHierarchyt : TestCount21xc : Containers : Scalexyc : Count(0, 100 msec)yy

The Container has a parameter named stride, whose value is passed to the factor parameter of the Scale reactor. The line

s.y -> y;

establishes a connection across levels of the hierarchy. This propagates the output of a contained reactor to the output of the container. A similar notation may be used to propagate the input of a container to the input of a contained reactor,

x -> s.x;

Connections with Logical Delays​

Connections may include a logical delay using the after keyword, as follows:

<source_port_reference> -> <destination_port_reference> after <time_value>

where <time_value> can be any of the forms described in Expressions.

The after keyword specifies that the logical time of the event delivered to the destination port will be larger than the logical time of the reaction that wrote to source port. The time value is required to be non-negative, but it can be zero, in which case the input event at the receiving end will be one microstep later than the event that triggered it.

Physical Connections​

A subtle and rarely used variant of the -> connection is a physical connection, denoted ~>. For example:

main reactor { a = new A(); b = new B(); a.y ~> b.x; }

This is rendered in by the diagram synthesizer as follows:

Lingua Franca diagram: PhysicalConnectionCreator: FreeHEP Graphics2D Driver Producer: de.cau.cs.kieler.klighd.piccolo.freehep.SemanticSVGGraphics2D Revision Source: Date: Saturday, April 2, 2022 at 5:07:16 PM Pacific Daylight TimePhysicalConnectionb : Bxa : Ay

In such a connection, the logical time at the recipient is derived from the local physical clock rather than being equal to the logical time at the sender. The physical time will always exceed the logical time of the sender (unless fast is set to true), so this type of connection incurs a nondeterministic positive logical time delay. Physical connections are useful sometimes in Distributed-Execution in situations where the nondeterministic logical delay is tolerable. Such connections are more efficient because timestamps need not be transmitted and messages do not need to flow through through a centralized coordinator (if a centralized coordinator is being used).