Merge pull request #98 from lf-lang/cpp-examples

Cleanup pass on Cpp examples and navigation

.gitignore

@@ -14,9 +14,9 @@
 **/src-gen/
 **/fed-gen/
 C/include
-Cpp/include
-Cpp/share
-Cpp/lib
+Cpp/**/include
+Cpp/**/share
+Cpp/**/lib
 # Created by https://www.toptal.com/developers/gitignore/api/intellij,gradle,eclipse,maven,visualstudiocode
 # Edit at https://www.toptal.com/developers/gitignore?templates=intellij,gradle,eclipse,maven,visualstudiocode
 

README.md

@@ -1,14 +1,25 @@
 [![CI](https://github.com/lf-lang/examples-lingua-franca/actions/workflows/ci.yml/badge.svg)](https://github.com/lf-lang/examples-lingua-franca/actions/workflows/ci.yml)
 
 ## 🛝 Lingua Franca Playground
-Get to know the language and tinker with some example Lingua Franca programs!
+Get to know the [Lingua Franca coordination language](https://lf-lang.org) and browse [example programs](examples/README.md).
+To view, edit, and run the programs, you can either run locally on your computer or run in the cloud using either GitHub Codespaces or Gitpod.
 
-### :rocket: Cloud-based dev environment
+## 💻 Running Locally
+Quick start:
+
+1. Clone this repo (`git clone git@github.com:lf-lang/playground-lingua-franca.git`)
+2. Open with [VS Code](https://code.visualstudio.com) (`code playground-lingua-franca`)
+3. Install the [Lingua Franca extension](https://github.com/lf-lang/vscode-lingua-franca) (<kbd>Ctrl</kbd>+<kbd>P</kbd> and enter `ext install lf-lang.vscode-lingua-franca`).
+
+Once in VSCode, navigate to [./examples](./examples) and click on any of the `.lf` files to open them into your editor. To build and run, use <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> and select `Lingua Franca: Build and Run`. Note: You might need not install additional dependencies in order to successfully build some of the code you find in this repository. For more information, see the [setup-env.bash](./utils/scripts/setup-env.bash) script that we use to configure our Docker-based environments.
+
+
+## :rocket: Running in the Cloud
 Spin up a fully configured dev environment in the cloud that start in seconds.
 Any dependencies required for building or running any of the examples are preinstalled.
 A web-based VS Code editor, preloaded with the Lingua Franca extension, is accessible through either **GitHub Codespaces** or **GitPod**. Simply click on either of the links below to get started.
 
-[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&repo=477928779&ref=main&skip_quickstart=true&devcontainer_path=.devcontainer%2Fnightly%2Fdevcontainer.json)
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&repo=477928779&ref=main&skip_quickstart=true&devcontainer_path=.devcontainer%2Fnightly%2Fdevcontainer.json) (NOTE: This can be quite slow to start.)
 
 [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/new#https://github.com/lf-lang/playground-lingua-franca/tree/main)
 
@@ -32,9 +43,3 @@ bash ./utils/scripts/setup-lf.bash dev
 
 Please note that running these commands will remove the current lingua-franca directory.
 
-## 💻 Local dev environment
-1. Clone this repo (`git clone git@github.com:lf-lang/playground-lingua-franca.git`)
-2. Open with VS Code (`code playground-lingua-franca`)
-3. Install the [Lingua Franca extension](https://github.com/lf-lang/vscode-lingua-franca) (<kbd>Ctrl</kbd>+<kbd>P</kbd> and enter `ext install lf-lang.vscode-lingua-franca`).
-
-Once in VSCode, navigate to [./examples](./examples) and click on any of the `.lf` files to open them into your editor. To build and run, use <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> and select `Lingua Franca: Build and Run`. Note: You might need not install additional dependencies in order to successfully build some of the code you find in this repository. For more information, see the [setup-env.bash](./utils/scripts/setup-env.bash) script that we use to configure our Docker-based environments.

examples/C/README.md

@@ -1,16 +1,19 @@
 # C Examples
-* [Patterns](src/patterns/README.md): Common communication patterns.
-* [Deadlines](src/deadlines/README.md): Uses of deadlines in Lingua Franca.
+
+(in alphabetical order)
+
 * [Car Brake](src/car-brake/README.md): Sketch of ADAS system illustrating the CAL theorem.
-* [Rosace](src/rosace/README.md): Aircraft controller illustrating periodic systems with multiple periods.
-* [Simulation](src/simulation/README.md): Using Lingua Franca for simulation.
+* [Deadlines](src/deadlines/README.md): Uses of deadlines in Lingua Franca.
+* [Distributed](src/distributed/README.md): Basic federated hello-world examples.
+* [Furuta Pendulum](src/modal_models/FurutaPendulum/README.md): A controller and simulation illustrating a modal reactor.
 * [Keyboard](src/keyboard/README.md): Responding to keyboard input using ncurses.
+* [Leader Election](src/leader-election/README.md): Federated fault-tolerant system with leader election.
 * [MQTT](src/mqtt/README.md): Interacting with MQTT-based services.
-* [Furuta Pendulum](src/modal_models/FurutaPendulum/README.md): A controller and simulation illustrating a modal reactor.
+* [Patterns](src/patterns/README.md): Common communication patterns.
 * [Rhythm](src/rhythm/README.md): Sound generation and terminal user interface demos.
+* [Rosace](src/rosace/README.md): Aircraft controller illustrating periodic systems with multiple periods.
 * [SDV](src/sdv/README.md): Software defined vehicle sketch integrating user input, a web display, and sound.
 * [Shared Memory](src/shared-memory/README.md): Using shared memory to exchange large data objects between federates. 
+* [Simulation](src/simulation/README.md): Using Lingua Franca for simulation.
 * [Train Door](src/train-door/README.md): Train door controller from a verification paper.
-* [Distributed](src/distributed/README.md): Basic federated hello-world examples.
 * [Watchdog](src/watchdog/README.md): Federated illustration of watchdogs.
-* [Leader Election](src/leader-election/README.md): Federated fault-tolerant system with leader election.

examples/Cpp/AlarmClock/src/AlarmClock.lf

@@ -1,29 +1,26 @@
 /**
- * This is a minimal example of an alarmclock implemeted using the features lingua franca supplies.
+ * This is a minimal example of an alarm clock implemeted using the features Lingua Franca supplies.
  *
  * This is just an extract and simplification from the main project which you can find here:
  * https://github.com/revol-xut/lf-alarm-clock
  *
  * This file contains the networking implementation it is really just an simple socket application
- * which parses simple http headers and respondes in text/plain
+ * which parses simple HTTP headers and responds in text/plain
  *
  * @author Tassilo Tanneberer <tassilo.tanneberger@tu-dresden.de>
  */
 target Cpp {
-  cmake-include: "AlarmClock.cmake",
-  keepalive: true
+  cmake-include: "AlarmClock.cmake"
 }
 
 import Network from "./Network.lf"
 import Clock from "./Clock.lf"
 
-// import Network.lf;
-// import Clock.lf;
 main reactor AlarmClock {
   clock = new Clock()
   network = new Network()
 
-  network.event -> clock.event  // additon of a new event
+  network.event -> clock.event  // addition of a new event
   network.delete_index -> clock.cancel_by_index
   clock.event_dump -> network.updated_events
 

examples/Cpp/AlarmClock/src/Clock.lf

@@ -7,8 +7,7 @@
  * Author: Tassilo Tanneberer <tassilo.tanneberger@tu-dresden.de>
  */
 target Cpp {
-  cmake-include: "AlarmClock.cmake",
-  keepalive: true
+  cmake-include: "AlarmClock.cmake"
 }
 
 public preamble {=

examples/Cpp/AlarmClock/src/Network.lf

@@ -1,17 +1,19 @@
 /**
- * This is a minimal example of an alarmclock implemeted using the features lingua franca supplies.
+ * This is a minimal example of an alarm clock implemeted using the features Lingua Franca supplies.
  *
  * This is just an extract and simplification from the main project which you can find here:
  * https://github.com/revol-xut/lf-alarm-clock
  *
  * This file contains the networking implementation it is really just an simple socket application
- * which parses simple http headers and respondes in text/plain
+ * which parses simple HTTP headers and responds in text/plain.
+ *
+ * This requires [installing Crow](https://crowcpp.org/master/getting_started/setup), which provides
+ * the HTTP server implementation.
  *
  * @author Tassilo Tanneberer <tassilo.tanneberger@tu-dresden.de>
  */
 target Cpp {
-  cmake-include: "AlarmClock.cmake",
-  keepalive: true
+  cmake-include: "AlarmClock.cmake"
 }
 
 public preamble {=

examples/Cpp/AlarmClock/src/README.md

@@ -1,63 +1,29 @@
 Lingua Franca Alarm Clock
 ----------------------------
 
-**Contact:** <revol-xut@protonmail.com>
+**Author:** <revol-xut@protonmail.com>
 
-**Main Repository:** [](https://github.com/revol-xut/lf-alarm-clock)
-
-A small and tiny alarmclock which is written using the scheduling and time features from lingua franca. 
-
-## What you will learn
-
-- sharing state between reactors
-- stopping scheduled events
-
-## Project
+A small alarm clock which is written using the scheduling and time features from Lingua Franca.
+This requires [installing Crow](https://crowcpp.org/master/getting_started/setup), which provides the HTTP server implementation.
 
 ![Programm Structure](./images/entire_program.png)
 
-
-## Building
-
-**Dependencies:** jdk11, boost, mpg321, Crow
-
-
-```bash
-    $ lfc ./AlarmClock.lf
-```
-
-**Building with nix**
-
-This cross compiles for aarch64.
-```
-    nix build .#packages.aarch64-linux.lf-alarm-clock
-```
-
 ## Installation
 
 By default the AlarmClock expects the sound files to be placed in `~/music/AlarmClock/` you can change this
 path by editing the `shared_header.cpp` file. Furthermore is it possible to configure paths to other binaries
 in this file e.g. kill, mpg321 -commands. 
 
-### Installing Crow from source
-
-On most distros, Crow needs to be build and installed from source:
+This program requires that you first [install Crow](https://crowcpp.org/master/getting_started/setup).
+If you have installed Crow in a location where CMake does not automatically find it, then you can manually specify the location when compiling the LF program as follows:
 
-```bash
-    $ git clone git@github.com:CrowCpp/Crow.git
-    $ mkdir Crow/build
-    $ cd Crow/build
-    $ cmake -DCMAKE_INSTALL_PREFIX=<install-location>
-    $ make install
-```
-Note that you can adjust the preferred install location by replacing `<install-location>`.
-
-To build the alarm clock using this manually installed version of Crow, simply run:
 ```bash
     $ CMAKE_PREFIX_PATH=<install-location> lfc ./AlarmClock.lf
 ```
 
-## Endpoints & Usage
+## Usage
+
+Running the program starts a web server on localhost at port 8680. The commands it understands are:
 
 ### /list **GET**
 Returns a list of upcoming events.
@@ -90,7 +56,7 @@ Stops the currently playing alarm sound.
 $ curl http://0.0.0.0:8680/stop 
 ```
 
-### /add_event_timestamp **POST**
+### /add\_event\_timestamp **POST**
 Will schedule your alarmclock for the given timestamp
 
 Request:
@@ -115,7 +81,7 @@ $ curl http://0.0.0.0:8680/add_event_timestamp -X POST -H "Content-Type: text/js
 
 Schedules event for given timestamp.
 
-### /add_event_relative **POST**
+### /add\_event\_relative **POST**
 Will schedule a event relative to the current time.
 
 Request

examples/Cpp/CarBrake/src/README.md

@@ -14,7 +14,7 @@ The second version forsakes consistency altogether using a Lingua Franca physica
 
 ## Variant that fixes this
 
-The CarBrake2.lf variant, if made federated, decouples the vision system from the handling of brake pedal actions
+The CarBrake2.lf variant decouples the vision system from the handling of brake pedal actions
 in a way that makes it impossible for the vision system to have any effect on the ability of the other component
 to make deadlines. The price for this decoupling is added nondeterminacy because the physical connection
 reassigns time stamps based on the current physical clock.
@@ -24,4 +24,8 @@ reassigns time stamps based on the current physical clock.
 <td> <img src="img/CarBrake.png" alt="CarBrake" width="400">
 <td> <a href="CarBrake.lf">CarBrake.lf</a>: Sketch of an ADAS implementation that emphasizes strong consistency at the expense of availability and therefore will miss deadlines when the brake pedal is pushed while image analysis is being performed.</td>
 </tr>
+<tr>
+<td> <img src="img/CarBrake2.png" alt="CarBrake2" width="400">
+<td> <a href="CarBrake2.lf">CarBrake.lf</a>: Variant that decouples the vision system from the handling of the brake pedal using a physical connection.</td>
+</tr>
 </table>

examples/Cpp/Patterns/README.md

@@ -0,0 +1,6 @@
+# C++ Patterns
+A few common design patterns:
+
+* [Fully Connected Broadcast](src/FullyConnected_00_Broadcast.lf)
+* [Fully Connected Addressable](src/FullyConnected_00_Addressable.lf)
+* [MatrixConnectedRowsAndColumns](src/MatrixConnectedRowsAndColumns.lf)

examples/Cpp/Patterns/src/MatrixConnectedRowsAndColumns.lf

@@ -1,6 +1,6 @@
 // This pattern creates a matrix of nodes, where each of the nodes can send
 // messages to all other nodes in the same row or in the same column. Since
-// banks in LF are one dimensional, we use hierachy to implement the second
+// banks in LF are one dimensional, we use hierarchy to implement the second
 // dimension. Nodes are organized in Rows which are grouped to form the matrix.
 target Cpp
 

examples/Cpp/README.md

@@ -0,0 +1,7 @@
+# C++ Examples
+* [Alarm Clock](AlarmClock/src/README.md)
+* [Car Brake](CarBrake/src/README.md)
+* [Patterns](Patterns/src/README.md)
+* [Reflex Game](ReflexGame/src/ReflexGame.lf)
+* [Add](RequestResponse/src/Add.lf) and [AddWithContext](RequestResponse/src/AddWithContext.lf) request-response patterns
+* [ROS2](ROS2/src/README.md)

examples/Cpp/ROS2/src/README.md

@@ -1,5 +1,5 @@
-This is an LF reimplementation of the ROS 2 minimal publisher and sunscriber
+This is an LF reimplementation of the ROS 2 minimal publisher and subscriber
 [example](https://docs.ros.org/en/galactic/Tutorials/Writing-A-Simple-Cpp-Publisher-And-Subscriber.html).
 
-It consists of two LF files, MinimalPublisher and MinimalSubscriber, each
+It consists of two LF files, [MinimalPublisher.lf](MinimalPublisher.lf) and [MinimalSubscriber.lf](MinimalSubscriber.lf), each
 implementing the corresponding nodes from the original example.

examples/Cpp/ReflexGame/src/ReflexGame.lf

@@ -7,7 +7,6 @@
  * @author Marten Lohstroh
  */
 target Cpp {
-  keepalive: true,
   cmake-include: "ReflexGame.cmake"
 }
 

examples/README.md

@@ -1,2 +1,5 @@
 # Examples
-Our examples are organized by __target__.
+Our examples are organized by __target__ language:
+
+* [C examples](C/README.md)
+* [C++ examples](Cpp/README.md)