-[Running batch simulations with Built-in daemons](#org954c5e6)
-[Running batch simulations with Built-in daemons](#org40c965c)
-[Running batch simulations with manual (a.k.a. custom) daemons](#org38d5de5)
-[Running batch simulations with manual (a.k.a. custom) daemons](#orgdd8c074)
-[Running batch simulations with `lurette`](#org640b2e9)
-[Running batch simulations with `lurette`](#orgf12417b)
-[Viewing Results](#org3d147ea)
-[Viewing Results](#org787fcde)
-[The `sasa` CLI](#orgdf60ab4)
-[The `sasa` CLI](#orge7a4389)
-[Interactive mode](#org5baaeee)
-[Interactive mode](#orga4286ee)
-[Example: use `rdbg` from the `test/alea-coloring/` directory](#org5b2cfb9)
-[Example: use `rdbg` from the `test/alea-coloring/` directory](#orgfd167f3)
-[The examples of test directory](#org2652e6e)
-[The examples of test directory](#org54614c9)
-[Running interactive sessions with `rdbg`](#org1dab3bd)
-[Running interactive sessions with `rdbg`](#org8389710)
-[Getting `rdbg` on-line help](#org262e448)
-[Getting `rdbg` on-line help](#org06a1ac5)
-[A `rdbg` `sasa` GUI](#org4285bff)
-[A `rdbg` `sasa` GUI](#orgdce894e)
-[Useful Modules](#org8d90a8b)
-[Useful Modules](#orge82a14e)
-[Install](#orgee0d8a4)
-[Install](#org0021508)
-[TL;DR](#org106f46f)
-[TL;DR](#org377dcfe)
-[Not strictly mandatory, but useful, third-party software](#orgc700b1f)
-[Not strictly mandatory, but useful, third-party software](#orgb7c9381)
-[Install `sasa` via opam (version >= 2.\*)](#org32e5593)
-[Install `sasa` via opam (version >= 2.\*)](#orgb86401e)
-[Install `sasa` via `git`](#orgaaeaaee)
-[Install `sasa` via `git`](#orgcbf1681)
-[Use `sasa` via docker](#org0cca00b)
-[Use `sasa` via docker](#orgc610ed3)
-[Use `sasa` via a Virtual Machine](#org30a0cfb)
-[Use `sasa` via a Virtual Machine](#orgee4ae29)
-[Screencasts](#orgcaa736c)
-[Screencasts](#orgef0e2a0)
-[More](#org0558eb8)
-[More](#org12cda47)
-[FAQ](#org6abdd10)
-[FAQ](#org3719ee5)
-[Is there a FAQ?](#orgc6dc2c8)
-[Is there a FAQ?](#org5f6beac)
-[I have a compilation error that I don't understand](#org169d469)
-[I have a compilation error that I don't understand](#org9d35258)
-[I have the error `Invalid_argument("compare: functional value")`](#orga5fc6a4)
-[I have the error `Invalid_argument("compare: functional value")`](#org63b0ec3)
<aid="org5ad0e66"></a>
<aid="org4613395"></a>
# TL;DR
# TL;DR
<aid="org9bed122"></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="org061f39e"></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:
Basically, one needs to provide:
...
@@ -57,16 +57,16 @@ sasa ring.dot -l 4 # run a batch simulation for 4 steps
...
@@ -57,16 +57,16 @@ sasa ring.dot -l 4 # run a batch simulation for 4 steps
<aid="orge3bca28"></a><aid="orgdeb8329"></a> The topology is given via `.dot` files, that should
<aid="org3fa8e55"></a><aid="orga56589a"></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))
1. follow the [graphviz/dot format](https://en.wikipedia.org/wiki/DOT_(graph_description_language))
2. have nodes **labeled** by the `algo` field
2. have nodes **labeled** by the `algo` field
...
@@ -124,14 +124,14 @@ graph ring {
...
@@ -124,14 +124,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).
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](#org90b15f9) 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](#org49e7a9a) to generate such kinds of `dot` graphs: <https://verimag.gricad-pages.univ-grenoble-alpes.fr/vtt/articles/sasa-gg/>
<aid="orge32cab3"></a>
<aid="org046b3be"></a>
# Algorithms
# Algorithms
<aid="org2f3c3e8"></a>
<aid="org9930119"></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)
The following has been generated from [algo.mli](https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/blob/master/lib/algo/algo.mli)
...
@@ -143,7 +143,7 @@ The following has been generated from [algo.mli](https://gricad-gitlab.univ-gren
...
@@ -143,7 +143,7 @@ The following has been generated from [algo.mli](https://gricad-gitlab.univ-gren
</iframe>
</iframe>
<aid="orgcfde991"></a>
<aid="org28013a7"></a>
# Examples
# Examples
...
@@ -183,14 +183,14 @@ The `test` directory also contains sub-directories which gathers programs shared
...
@@ -183,14 +183,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).
-`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="org80aeb83"></a>
<aid="org5e9fb35"></a>
# Batch mode
# Batch mode


<aid="org9f35d61"></a>
<aid="org88f9350"></a>
## Running batch simulations
## Running batch simulations
...
@@ -233,28 +233,31 @@ All the CLI commands above can be run automatically using a `make` rule containe
...
@@ -233,28 +233,31 @@ All the CLI commands above can be run automatically using a `make` rule containe
make: 'ring.cmxs' is up to date.
make: 'ring.cmxs' is up to date.
# Automatically generated by /home/jahier/.opam/4.14.0/bin/sasa version "v4.8.0" ("65d9837")
# Automatically generated by /home/jahier/.opam/4.14.0/bin/sasa version "v4.8.0" ("65d9837")
#outs 0 1 0 0 1 0 0 t f t t f t t f f t f f t t f 6. f 0
#outs 0 1 0 0 1 1 0 t f t t t t t t f f t t f t f 6. f 0
#step 1
#step 1
#outs 0 1 2 0 1 2 1 f f f f f f f f f f f f f f t 0. t 1
#outs 2 1 0 2 2 1 2 t f f t t f t f f f t f f t f 4. t 2
This algo is silent after 3 moves, 1 step, 1 round.
#step 2
#outs 2 1 0 1 2 1 0 f f f f f f f f f f f f f f t 0. t 2
This algo is silent after 6 moves, 2 steps, 2 rounds.
#quit
#quit
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.
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="org954c5e6"></a>
<aid="org40c965c"></a>
## Running batch simulations with Built-in daemons
## Running batch simulations with Built-in daemons
...
@@ -273,7 +276,7 @@ sasa -h | grep "\-daemon"
...
@@ -273,7 +276,7 @@ sasa -h | grep "\-daemon"
--greedy-daemon, -gd
--greedy-daemon, -gd
<aid="org38d5de5"></a>
<aid="orgdd8c074"></a>
## Running batch simulations with manual (a.k.a. custom) daemons
## Running batch simulations with manual (a.k.a. custom) daemons
...
@@ -311,7 +314,7 @@ In order to enter such input more easily, one can use (requires [the lustre V4 t
...
@@ -311,7 +314,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).
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="org640b2e9"></a>
<aid="orgf12417b"></a>
## Running batch simulations with `lurette`
## Running batch simulations with `lurette`
...
@@ -336,14 +339,14 @@ Note that for `lurette`, the role of the SUT (System Under Test) and the one of
...
@@ -336,14 +339,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/>
For more information on this topic: <https://verimag.gricad-pages.univ-grenoble-alpes.fr/vtt/articles/sasa-daemons/>
<aid="org3d147ea"></a>
<aid="org787fcde"></a>
## Viewing Results
## 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/>
`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="orgdf60ab4"></a>
<aid="orge7a4389"></a>
## The `sasa` CLI
## The `sasa` CLI
...
@@ -430,11 +433,11 @@ More `sasa` options:
...
@@ -430,11 +433,11 @@ More `sasa` options:
Display the version ocaml version sasa was compiled with and exit.
Display the version ocaml version sasa was compiled with and exit.
<aid="org5baaeee"></a>
<aid="orga4286ee"></a>
# Interactive mode
# Interactive mode
<aid="org3d0da66"></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="org9e8abf6"></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.
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).
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="org5b2cfb9"></a>
<aid="orgfd167f3"></a>
## Example: use `rdbg` from the `test/alea-coloring/` directory
## Example: use `rdbg` from the `test/alea-coloring/` directory
...
@@ -486,7 +489,7 @@ rdbg
...
@@ -486,7 +489,7 @@ rdbg
[q] quit
[q] quit
<aid="org2652e6e"></a>
<aid="org54614c9"></a>
## The examples of test directory
## The examples of test directory
...
@@ -497,7 +500,7 @@ The [test](https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/t
...
@@ -497,7 +500,7 @@ 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).
-`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="org1dab3bd"></a>
<aid="org8389710"></a>
## Running interactive sessions with `rdbg`
## Running interactive sessions with `rdbg`
...
@@ -514,7 +517,7 @@ The [test](https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/t
...
@@ -514,7 +517,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`!
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="org262e448"></a>
<aid="org06a1ac5"></a>
## Getting `rdbg` on-line help
## Getting `rdbg` on-line help
...
@@ -610,7 +613,7 @@ Here are 2 useful entry-points to rdbg on-line help:
...
@@ -610,7 +613,7 @@ Here are 2 useful entry-points to rdbg on-line help:
(rdbg)
(rdbg)
<aid="org4285bff"></a>
<aid="orgdce894e"></a>
## A `rdbg` `sasa` GUI
## A `rdbg` `sasa` GUI
...
@@ -624,7 +627,7 @@ opam install -y rdbgui4ocaml
...
@@ -624,7 +627,7 @@ opam install -y rdbgui4ocaml
To use it: <https://verimag.gricad-pages.univ-grenoble-alpes.fr/vtt/articles/rdbgui4sasa/>
To use it: <https://verimag.gricad-pages.univ-grenoble-alpes.fr/vtt/articles/rdbgui4sasa/>
<aid="org8d90a8b"></a>
<aid="orge82a14e"></a>
## Useful Modules
## Useful Modules
...
@@ -659,14 +662,14 @@ Some modules, used by the sasa core engine, can be useful from `rdbg`.
...
@@ -659,14 +662,14 @@ Some modules, used by the sasa core engine, can be useful from `rdbg`.
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).
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="org0cca00b"></a>
<aid="orgc610ed3"></a>
## Use `sasa` via docker
## 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.).
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="org30a0cfb"></a>
<aid="orgee4ae29"></a>
## Use `sasa` via a Virtual Machine
## Use `sasa` via a Virtual Machine
...
@@ -858,7 +861,7 @@ cf the Docker Install section of the [Synchrone Reactive Tool Box](http://www-ve
...
@@ -858,7 +861,7 @@ cf the Docker Install section of the [Synchrone Reactive Tool Box](http://www-ve
- passwd:sasa
- passwd:sasa
<aid="orgcaa736c"></a>
<aid="orgef0e2a0"></a>
# Screencasts
# Screencasts
...
@@ -874,7 +877,7 @@ cf the Docker Install section of the [Synchrone Reactive Tool Box](http://www-ve
...
@@ -874,7 +877,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/>
Beside, some tutorials are also available here: <https://verimag.gricad-pages.univ-grenoble-alpes.fr/vtt/tags/sasa/>
<aid="org169d469"></a>
<aid="org9d35258"></a>
## I have a compilation error that I don't understand
## I have a compilation error that I don't understand
...
@@ -907,7 +910,7 @@ Beside, some tutorials are also available here: <https://verimag.gricad-pages.un
...
@@ -907,7 +910,7 @@ 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>
- 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="orga5fc6a4"></a>
<aid="org63b0ec3"></a>
## I have the error `Invalid_argument("compare: functional value")`
## I have the error `Invalid_argument("compare: functional value")`