You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/developer/downloading-and-building.mdx
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -41,7 +41,7 @@ For more details on our testing infrastructure, please refer to the [Regression
41
41
If you only want to build without running any tests, you can use `./gradlew assemble` instead.
42
42
Both the assemble and the build task will create a distribution package containing our command line tools in `build/distribution`.
43
43
There is also an installed version of this package in `build/install/lf-cli/`.
44
-
If you run `build/install/lf-cli/bin/lfc` this will run lfc as it was last build.
44
+
If you run `build/install/lf-cli/bin/lfc` this will run lfc as it was last built.
45
45
Thus, you can choose if you want to use `bin/lfc-dev`, which first builds `lfc` using the latest code and then runs it, or if you prefer to run `./gradlew build` and then separately invoke `build/install/lf-cli/bin/lfc`.
Have a look at the [Lingua Franca playground](https://github.com/lf-lang/playground-lingua-franca) for more details.
20
+
Have a look at the [Lingua Franca playground](https://github.com/lf-lang/playground-lingua-franca) for example programs and more details on the cloud-based dev environments.
21
21
22
22
## Visual Studio Code
23
23
24
-
Our Visual Studio Code extension can be installed via the Marketplace or built from source, as detailed below. See the [handbook](./tools/code-extension.mdx) for usage instructions.
24
+
Our Visual Studio Code extension can be installed via the Marketplace or built from source, as detailed below. This extension also works with VS Code-compatible tools such as [Cursor](https://cursor.com). See the [handbook](./tools/code-extension.mdx) for usage instructions.
25
25
26
26
### Marketplace
27
27
@@ -37,6 +37,13 @@ Alternatively, you can run the following command in your terminal:
To use the nightly pre-release of the extension instead of the latest release, find the Lingua Franca extension in the Extensions tab and click on the "Switch to Pre-Release Version" button.
41
48
42
49
### From Source
@@ -56,6 +63,13 @@ Run the following command in your terminal to install the latest release (on Win
The Lingua Franca compiler is packaged in [nixpkgs](https://github.com/NixOS/nixpkgs/blob/nixos-23.11/pkgs/development/compilers/lingua-franca/default.nix#L28) and is available via the binary cache.
84
-
85
-
Run
97
+
The Lingua Franca compiler is packaged in [nixpkgs](https://github.com/NixOS/nixpkgs/blob/nixos-23.11/pkgs/development/compilers/lingua-franca/default.nix#L28) and is available via the binary cache. Run
Copy file name to clipboardExpand all lines: docs/introduction.md
+23-10Lines changed: 23 additions & 10 deletions
Original file line number
Diff line number
Diff line change
@@ -6,23 +6,36 @@ slug: /
6
6
7
7
Lingua Franca (LF) is a polyglot coordination language built to enrich mainstream target programming languages (currently C, C++, Python, TypeScript, and Rust) with deterministic reactive concurrency and the ability to specify timed behavior. LF is supported by a runtime system that is capable of concurrent and distributed execution of reactive programs that are deployable on the Cloud, the Edge, and even on bare-iron embedded platforms.
8
8
9
-
A Lingua Franca program specifies the interactions between components called reactors. The logic of each reactor is written in plain target code. A code generator synthesizes one or more programs in the target language, which are then compiled using standard tool chains. If the application has exploitable parallelism, then it executes transparently on multiple cores without compromising determinacy. A distributed application translates into multiple programs and scripts to launch those programs on distributed machines. The communication fabric connecting components is synthesized as part of the programs.
9
+
As you build your programs, the tools automatically generate interactive diagrams that show the components of your program. For example:
10
+
11
+
import RegressionTestSVG from "./assets/images/diagrams/MainReactor.svg"
12
+
13
+
<RegressionTestSVGtitle="Lingua Franca diagram: RegressionTest"role="img"width="700" />
14
+
15
+
A Lingua Franca program specifies the interactions between concurrent components called reactors. There are three reactors above. Each reactor contains one or more reactions, which specify code (in C, C++, Python, Rust, or TypeScript) to execute when triggered by events. Events come from timers (periodic and aperiodic), input ports, or from the environment.
16
+
17
+
If the application has exploitable parallelism, then it executes transparently on multiple cores or multiple machines without compromising determinacy. The above program shows a simple pipeline chain, where reactions A1, B1, and the reactions in C all can execute in parallel. The logical delays of 100 ms on connections between ports enable such parallel execution. In ReactorC, reactions C1 and C2 do not execute in parallel because they (potentially) share state variables. The deterministic semantics of LF ensures that for the above program, reaction C1 will always process the previous result of B1 (not the one being computed in parallel), which is triggered by the 200ms-old result from A1. Only after reaction C1 completes, reaction C2 will process the 200ms-old result from A1. Hence, despite the parallel execution, and even if this program is distributed across networked hosts, the computation is deterministic and repeatable.
18
+
19
+
The `lfc` code generator synthesizes one or more programs in the target language, which are then compiled using standard tool chains. A distributed (federated) application translates into multiple programs and scripts to launch those programs on distributed machines. The communication fabric connecting components is synthesized as part of the programs.
20
+
10
21
11
22
## Reactor-Oriented Programming
12
-
Lingua Franca programs are compositions of reactors, which are stateful
13
-
components with event-triggered routines that may read inputs, write outputs, manipulate the reactor's state and schedule future events.
14
-
Reactors are similar to actors, software components that send each other messages, but unlike classical actors, messages are timestamped, and concurrent composition of reactors is deterministic by default. When nondeterministic interactions are tolerable or desired, they must be explicitly coded. LF itself is a polyglot composition language, not a complete programming language. LF describes the interfaces and composition of reactors. See our [publications and presentations](/research) on reactors and Lingua Franca.
23
+
Reactors are stateful components with event-triggered routines that may read inputs, write outputs, manipulate the reactor's state and schedule future events.
24
+
Reactors are similar to actors, software components that send each other messages, but unlike classical actors, messages are timestamped, and concurrent composition of reactors is deterministic by default. When nondeterministic interactions are tolerable or desired, they must be explicitly coded.
25
+
26
+
LF itself is a polyglot composition language, not a complete programming language. LF describes the interfaces and composition of reactors. See our [publications and presentations](/research) on reactors and Lingua Franca.
15
27
16
28
The reactor-oriented programming paradigm is informally described via the following principles:
17
29
18
-
1._Components_ — Reactors can have input ports, actions, and timers, all of which are triggers. They can also have output ports, local state, parameters, and an ordered list of reactions.
30
+
1._Components_ — Reactors can have input ports, actions, and timers, all of which are triggers. Actions are used to schedule irregular (non-periodic) events, whereas timers specify periodic events. Reactors can also have output ports, local state, parameters, and an ordered list of reactions.
19
31
2._Composition_ — A reactor may contain other reactors and manage their connections. The connections define the flow of messages, and two reactors can be connected if they are contained by the same reactor or one is directly contained in the other (i.e., connections span at most one level of hierarchy). An output port may be connected to multiple input ports, but an input port can only be connected to a single output port.
20
-
3._Events_ — Messages sent from one reactor to another, and timer and action events each have a tag (i.e., a timestamp), a value on a logical time line. These are tagged events that can trigger reactions. Each port, timer, and action can have at most one such event at any tag. An event may carry a value that will be passed as an argument to triggered reactions.
21
-
4._Reactions_ — A reaction is a procedure in a target language that is invoked in response to a trigger event, and only in response to a trigger event. A reaction can read input ports, even those that do not trigger it, and can produce outputs, but it must declare all inputs that it may read and output ports to which it may write. All inputs that it reads and outputs that it produces bear the same timestamp as its triggering event. I.e., the reaction itself is logically instantaneous, so any output events it produces are logically simultaneous with the triggering event (the two events bear the same timestamp).
22
-
5._Flow of Time_ — Successive invocations of any single reaction occur at strictly increasing tags. Any messages that are not read by a reaction triggered at the timestamp of the message are lost.
23
-
6._Mutual Exclusion_ — The execution of any two reactions of the same reactor are mutually exclusive (atomic with respect to one another). Moreover, any two reactions that are invoked at the same tag are invoked in the order specified by the reactor definition. This avoids race conditions between reactions accessing the reactor state variables.
32
+
3._Events_ — Every event has a tag (a form of timestamp), and every reactor reacts to events in tag order. When a reactor reacts to more than one event with the same tag, the reaction order is deterministic, so the results are predictable. Each port, timer, and action can have at most one event at any tag. An event may carry a value that will be passed as an argument to triggered reactions.
33
+
4._Reactions_ — A reaction is a procedure in a target language that is invoked in response to a trigger event, and only in response to a trigger event. A reaction can read input ports, even those that do not trigger it, and can produce outputs, but it must declare all inputs that it may read and output ports to which it may write. All inputs that it reads and outputs that it produces bear the same tag as its triggering event. I.e., the reaction itself is logically instantaneous, so any output events it produces are logically simultaneous with the triggering event (the two events bear the same timestamp).
34
+
5._Flow of Time_ — Successive invocations of any single reaction occur at strictly increasing tags. Any messages that are not read by a reaction triggered at the tag of the message are lost.
35
+
6._Mutual Exclusion_ — The execution of any two reactions _of the same reactor_ are mutually exclusive (atomic with respect to one another). Moreover, any two reactions that are invoked at the same tag are invoked in the order specified by the reactor definition. This avoids race conditions between reactions accessing the reactor state variables.
24
36
7._Determinism_ — A Lingua Franca program is deterministic unless the programmer explicit uses nondeterministic constructs. Given the same input data, a composition of reactors has exactly one correct behavior. This makes Lingua Franca programs _testable_.
25
-
8._Concurrency_ — Dependencies between reactions are explicitly declared in a Lingua Franca program, and reactions that are not dependent on one another can be executed in parallel on a multi-core machine. If the target provides a support for federated execution, then execution can also be distributed across networks.
37
+
8._Concurrency_ — Dependencies between reactions are explicitly declared in a Lingua Franca program, and reactions that are not dependent on one another can be executed in parallel on a multi-core machine. For targets supporting federated execution (currently C, Python, and TypeScript), execution can be distributed across networks.
38
+
9._Feedback_ - Messages can flow in feedback cycles. The compiler automatically identifies causality loops that may be introduced by the programmer. A causality loop makes it impossible for the compiler to determine an order of reaction invocation at a tag that preserves determinism.
26
39
27
40
## Getting Started
28
41
To get started with Lingua Franca, [set up a development environment](./installation.md) and learn how to write [a first reactor](./writing-reactors/a-first-reactor.mdx). There are also a number of potentially useful [videos](./videos.mdx) available.
Lingua Franca offers a straightforward way to write multi-threaded applications that ensure determinism by default, eliminating concerns about thread management, synchronization, and race conditions.
23
+
Lingua Franca offers a straightforward way to write deterministic multi-threaded and distributed applications, eliminating concerns about thread management, synchronization, and race conditions.
Consider a game of "rock paper scissors" where two players need to reveal their choice simultaneously. In Lingua Franca, "at the same time" has a clear and precise meaning.
91
-
This makes the implementation simple and intuitive, and guarantees it to be fair. If the Player class were to observe the other's choice before revealing its own, Lingua Franca's causality analysis would find a causality loop and tell you that the program was invalid.
92
+
This makes the implementation simple and intuitive, and guarantees it to be fair. If the Player class were to observe the other's choice before revealing its own, Lingua Franca's causality analysis would find a causality loop and tell you that the program is invalid.
Copy file name to clipboardExpand all lines: versioned_docs/version-0.5.0/developer/downloading-and-building.mdx
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -41,7 +41,7 @@ For more details on our testing infrastructure, please refer to the [Regression
41
41
If you only want to build without running any tests, you can use `./gradlew assemble` instead.
42
42
Both the assemble and the build task will create a distribution package containing our command line tools in `build/distribution`.
43
43
There is also an installed version of this package in `build/install/lf-cli/`.
44
-
If you run `build/install/lf-cli/bin/lfc` this will run lfc as it was last build.
44
+
If you run `build/install/lf-cli/bin/lfc` this will run lfc as it was last built.
45
45
Thus, you can choose if you want to use `bin/lfc-dev`, which first builds `lfc` using the latest code and then runs it, or if you prefer to run `./gradlew build` and then separately invoke `build/install/lf-cli/bin/lfc`.
0 commit comments