-[Running batch simulations with Built-in daemons](#org9015d05)
-[Running batch simulations with manual (a.k.a. custom) daemons](#org7eec4f0)
-[Running batch simulations with `lurette`](#orgc770ce0)
-[Viewing Results](#org77bb70c)
-[The `sasa` CLI](#org13e9147)
-[Interactive mode](#org64cd5de)
-[Example: use `rdbg` from the `test/alea-coloring/` directory](#org77bfd02)
-[The examples of test directory](#orgccecf21)
-[Running interactive sessions with `rdbg`](#org1d73d68)
-[Getting `rdbg` on-line help](#org6e2b752)
-[A `rdbg` `sasa` GUI](#orgaeb9370)
-[Useful Modules](#org1b0d22c)
-[Install](#orga6e17e7)
-[TL;DR](#org773be47)
-[Not strictly mandatory, but useful, third-party software](#orge1cefb0)
-[Install `sasa` via opam (version >= 2.\*)](#org799f08b)
-[Install `sasa` via `git`](#orgc6832ab)
-[Use `sasa` via docker](#org8fc4b64)
-[Use `sasa` via a Virtual Machine](#org0c0d7c2)
-[Screencasts](#org682fc05)
-[More](#org11d9306)
-[FAQ](#orgfc8c2b2)
-[Is there a FAQ?](#org72c0095)
-[I have a compilation error that I don't understand](#orge57b20e)
-[I have the error `Invalid_argument("compare: functional value")`](#orgcbfe32e)
<aid="org8fa27cc"></a>
-[TL;DR](#org1026a8e)
-[Topology](#orgb4df5b3)
-[Algorithms](#org6ade26f)
-[Examples](#org8d79f98)
-[Batch mode](#org056ba86)
-[Running batch simulations](#orgfab12e1)
-[Running batch simulations with Built-in daemons](#orgd805172)
-[Running batch simulations with manual (a.k.a. custom) daemons](#orgc83fe4f)
-[Running batch simulations with `lurette`](#orgae795ee)
-[Viewing Results](#orgb583f0d)
-[The `sasa` CLI](#org5680d70)
-[Interactive mode](#orgc9bd367)
-[Example: use `rdbg` from the `test/alea-coloring/` directory](#orgc697f02)
-[The examples of test directory](#orgf518876)
-[Running interactive sessions with `rdbg`](#orgf412858)
-[Getting `rdbg` on-line help](#org0106b12)
-[A `rdbg` `sasa` GUI](#org67d414e)
-[Useful Modules](#org3eee2b0)
-[Install](#org40175a6)
-[TL;DR](#org376c26e)
-[Not strictly mandatory, but useful, third-party software](#org85b4f8f)
-[Install `sasa` via opam (version >= 2.\*)](#org43104bf)
-[Install `sasa` via `git`](#org3d3734e)
-[Use `sasa` via docker](#org19e54d0)
-[Use `sasa` via a Virtual Machine](#orga15adfe)
-[Screencasts](#org137a3ee)
-[More](#orgb2b8f50)
-[FAQ](#org441d3ab)
-[Is there a FAQ?](#orgc933a8d)
-[I have a compilation error that I don't understand](#org51d450b)
-[I have the error `Invalid_argument("compare: functional value")`](#org823c711)
<aid="org1026a8e"></a>
# TL;DR
<aid="org46147ce"></a> SASA is a **Self-stabilizing Algorithms SimulAtor**, based on the so-called **Atomic State model** (ASM) introduced by <spanclass="underline">Dijkstra</span> in its seminal article on [Self-stabilizing distributed algorithms](http://www.cs.utexas.edu/~EWD/ewd04xx/EWD426.PDF). This model is also sometimes named "locally shared memory model with composite atomicity"
<aid="org0606401"></a> SASA is a **Self-stabilizing Algorithms SimulAtor**, based on the so-called **Atomic State model** (ASM) introduced by <spanclass="underline">Dijkstra</span> in its seminal article on [Self-stabilizing distributed algorithms](http://www.cs.utexas.edu/~EWD/ewd04xx/EWD426.PDF). This model is also sometimes named "locally shared memory model with composite atomicity"
Basically, one needs to provide:
...
...
@@ -61,11 +61,11 @@ sasa ring.dot -l 4 # run a batch simulation for 4 steps
<aid="org12b1a12"></a><aid="orgbb48953"></a> The topology is given via `.dot` files, that should
<aid="org57040cd"></a><aid="org3c6291f"></a> The topology is given via `.dot` files, that should
1. follow the [graphviz/dot format](https://en.wikipedia.org/wiki/DOT_(graph_description_language))
2. have nodes **labeled** by the `algo` field
...
...
@@ -121,14 +121,14 @@ graph ring {
Such parameters can be retrieved in algorithms using the `Algo.get_graph_attribute : string -> string` function. For example, if you know the graph diameter, you can define it as a graph attribute (a `Algo.diameter: unit -> int` function is provided, but it can be expensive to use for large graphs).
Some tools are provided in the `sasa`[distributions](#org8f315c0) to generate such kinds of `dot` graphs: <https://verimag.gricad-pages.univ-grenoble-alpes.fr/vtt/articles/sasa-gg/>
Some tools are provided in the `sasa`[distributions](#org18f93ef) to generate such kinds of `dot` graphs: <https://verimag.gricad-pages.univ-grenoble-alpes.fr/vtt/articles/sasa-gg/>
<aid="orgf2ed7c2"></a>
<aid="org6ade26f"></a>
# Algorithms
<aid="org6eaf8cc"></a>
<aid="org1d03ff2"></a>
The following has been generated from [algo.mli](https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/blob/master/lib/algo/algo.mli)
...
...
@@ -140,7 +140,7 @@ The following has been generated from [algo.mli](https://gricad-gitlab.univ-gren
</iframe>
<aid="org36e35df"></a>
<aid="org8d79f98"></a>
# Examples
...
...
@@ -180,14 +180,14 @@ The `test` directory also contains sub-directories which gathers programs shared
-`test/*/my-rdbg-tuning.ml`: includes `test/my-rdbg-tuning.ml` and defines commands specific to the example of the directory. Indeed, `rdbg`, once launched, first tries to read the content of the file name `my-rdbg-tuning.ml` (if it exists).
<aid="orgfbdc4f5"></a>
<aid="org056ba86"></a>
# Batch mode
<aid="orgb148cef"></a>
<aid="orgfab12e1"></a>
## Running batch simulations
...
...
@@ -231,7 +231,7 @@ All the CLI commands above can be run automatically using a `make` rule containe
nb: the simulation output (in the green frame) follows the [RIF](http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/lustre-v6/#outline-container-orga43b00b) conventions.
<aid="org9015d05"></a>
<aid="orgd805172"></a>
## Running batch simulations with Built-in daemons
...
...
@@ -250,7 +250,7 @@ sasa -h | grep "\-daemon"
--greedy-daemon, -gd
<aid="org7eec4f0"></a>
<aid="orgc83fe4f"></a>
## Running batch simulations with manual (a.k.a. custom) daemons
...
...
@@ -288,7 +288,7 @@ In order to enter such input more easily, one can use (requires [the lustre V4 t
Daemons can also by simulated by [`lutin`](http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/lustre-v6/#outline-container-sec-4) programs via the use of [`lurette`](http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/lustre-v6/#outline-container-sec-9)(for batch executions) or [`rdbg`](http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/lustre-v6/#outline-container-sec-10)(for interactive sessions).
<aid="orgc770ce0"></a>
<aid="orgae795ee"></a>
## Running batch simulations with `lurette`
...
...
@@ -313,14 +313,14 @@ Note that for `lurette`, the role of the SUT (System Under Test) and the one of
For more information on this topic: <https://verimag.gricad-pages.univ-grenoble-alpes.fr/vtt/articles/sasa-daemons/>
<aid="org77bb70c"></a>
<aid="orgb583f0d"></a>
## Viewing Results
`sasa -rif` and `lurette` generates `.rif` files that can be viewed with `gnuplot-rif` or `sim2chro`; cf <http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/reactive-toolbox/>
<aid="org13e9147"></a>
<aid="org5680d70"></a>
## The `sasa` CLI
...
...
@@ -389,11 +389,11 @@ More `sasa` options:
Display the version ocaml version sasa was compiled with and exit.
<aid="org64cd5de"></a>
<aid="orgc9bd367"></a>
# Interactive mode
<aid="org01b2fe8"></a> If you want to perform step-by-step simulations, you can use the `-custd` option. But if you want to perform step-by-step simulations without the burden of playing the role of the daemon, you can launch `sasa` under the control of [rdbg](http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/rdbg/).
<aid="org9cddde9"></a> If you want to perform step-by-step simulations, you can use the `-custd` option. But if you want to perform step-by-step simulations without the burden of playing the role of the daemon, you can launch `sasa` under the control of [rdbg](http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/rdbg/).
Another advantage of [rdbg](http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/rdbg/) is its ability to display a graphical view of the current configuration during the simulation, to move step by step, or round by round, forward or backwards.
Before reading this section, please read at least the [Basic usage Section if the rdbg documentation](http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/rdbg/README.html#outline-container-sec-3).
<aid="org77bfd02"></a>
<aid="orgc697f02"></a>
## Example: use `rdbg` from the `test/alea-coloring/` directory
...
...
@@ -423,7 +423,7 @@ make rdbg
This make rule (defined in `Makefile` and `../Makefile.inc`)
1. generates the `ring.ml` file, that contains the registration code (that can indeed be generated by sasa, as explained in `algo.mli`).
2. launches `rdbg` with some arguments (`rdbg -o ring.rif -sut "sasa ring.dot --locally-central-daemon"`). `rdbg` then prompts the user to enter one of the following commands:
2. launches `rdbg` with some arguments (`rdbg --sasa -o ring.rif -sut "sasa ring.dot --locally-central-daemon"`). `rdbg` then prompts the user to enter one of the following commands:
Enter one of the following key (the first is the default one):
[] create a fresh session
...
...
@@ -445,7 +445,7 @@ rdbg
[q] quit
<aid="orgccecf21"></a>
<aid="orgf518876"></a>
## The examples of test directory
...
...
@@ -456,13 +456,13 @@ The [test](https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/t
-`test/*/my-rdbg-tuning.ml`: includes `test/my-rdbg-tuning.ml` and defines commands specific to the example of the directory. Indeed, `rdbg`, once launched, first tries to read the content of the file name `my-rdbg-tuning.ml` (it it exists).
<aid="org1d73d68"></a>
<aid="orgf412858"></a>
## Running interactive sessions with `rdbg`
1. type `rdbg`
2. press enter to load the defaut session (`rdbg-session.ml`). Then you can type:
3.`d` for displaying a (dynamic) dot graph with `dot`
3.`gv` (graph view) for displaying a (dynamic) dot graph with `dot`
4. or ALTERNATIVELY `ne` to use the `neato` layout engine (`tw`, `ci`, `fd`, `sf`, `pa`, `os` to use the `twopi`, `circo`, `fdp`, `sfd`, `patchwork`, `osage` layout engines respectively)
5.`s` to move one step forward
6.`sd` to move one step forward and call `d` (to update the graph display [])
...
...
@@ -473,7 +473,7 @@ The [test](https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/t
All those commands are defined in (the common) [test/my-rdbg-tuning.ml](https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/tree/master/test/my-rdbg-tuning.ml) that is included in (locals) `test/*/my-rdbg-tuning.ml` that are included in (generated) `test/*/rdbg-session.ml` files. `my-rdbg-tuning.ml` contains straigthforward `ocaml` code that defines various `rdbg` shortcuts to ease the simulation of `sasa` systems. Feel free to tailor those command to yours needs by modyfying the local `my-rdbg-tuning.ml`!
<aid="org6e2b752"></a>
<aid="org0106b12"></a>
## Getting `rdbg` on-line help
...
...
@@ -569,21 +569,21 @@ Here are 2 useful entry-points to rdbg on-line help:
(rdbg)
<aid="orgaeb9370"></a>
<aid="org67d414e"></a>
## A `rdbg` `sasa` GUI
To install it:
```sh
opam depext -y rdbgui4ocaml
opam depext -y rdbgui4ocaml-- useless with opam >= 2.1
opam install-y rdbgui4ocaml
```
To use it: <https://verimag.gricad-pages.univ-grenoble-alpes.fr/vtt/articles/rdbgui4sasa/>
<aid="org1b0d22c"></a>
<aid="org3eee2b0"></a>
## Useful Modules
...
...
@@ -618,14 +618,14 @@ Some modules, used by the sasa core engine, can be useful from `rdbg`.
</iframe>
<aid="orga6e17e7"></a>
<aid="org40175a6"></a>
# Install
<aid="org8f315c0"></a><aid="org43a1957"></a>
<aid="org18f93ef"></a><aid="org9e48bc2"></a>
<aid="org773be47"></a>
<aid="org376c26e"></a>
## TL;DR
...
...
@@ -656,7 +656,7 @@ opam install -y sasa
And optionally (to define test oracles in Lustre or daemons in Lutin):
```sh
opam depext -y rdbgui4sasa lutin
opam depext -y rdbgui4sasa lutin-- useless with opam >= 2.1
One can also mimic the content of the `test` job in the project [.gitlab-ci.yml Gitlab CI script](https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/tree/master/.gitlab-ci.yml).
<aid="org8fc4b64"></a>
<aid="org19e54d0"></a>
## Use `sasa` via docker
cf the Docker Install section of the [Synchrone Reactive Tool Box](http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/lustre-v6/#docker). This docker image contains all the tools mentioned in this section (`sasa`, `lustre`, `opam`, `ocaml`, emacs, graphviz, etc.).
<aid="org0c0d7c2"></a>
<aid="orga15adfe"></a>
## Use `sasa` via a Virtual Machine
...
...
@@ -817,7 +817,7 @@ cf the Docker Install section of the [Synchrone Reactive Tool Box](http://www-ve
- passwd:sasa
<aid="org682fc05"></a>
<aid="org137a3ee"></a>
# Screencasts
...
...
@@ -833,7 +833,7 @@ cf the Docker Install section of the [Synchrone Reactive Tool Box](http://www-ve
Beside, some tutorials are also available here: <https://verimag.gricad-pages.univ-grenoble-alpes.fr/vtt/tags/sasa/>
<aid="orge57b20e"></a>
<aid="org51d450b"></a>
## I have a compilation error that I don't understand
...
...
@@ -866,8 +866,8 @@ Beside, some tutorials are also available here: <https://verimag.gricad-pages.un
- If the message is totally useless, please feel free to add an issue here <https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/issues>
<aid="orgcbfe32e"></a>
<aid="org823c711"></a>
## I have the error `Invalid_argument("compare: functional value")`
Most probably you a try to compare 2 `'s Algo.neighbor`. It's an abstract type, hence you cannot compare them, i.e., you cannot use `Stdlib.compare`, nor its twins (`<>`, `>`, `<`, etc.), nor functions that use them (`min`, `max`, `List.sort`, etc.). You should compare their `pid` instead (if the network is not anonymous).
Most probably you a try to compare 2 `'s Algo.neighbor`. It's an abstract type, hence you cannot compare them, i.e., you cannot use `Stdlib.compare`, nor its twins (`<>`, `>`, `<`, etc.), nor functions that use them (`min`, `max`, `List.sort`, etc.). You should compare their `pid` instead (if the network is not anonymous).
