Commit a40287f0 authored by erwan's avatar erwan
Browse files

Breaking: use .ml files instead of .cmxs in algo fields of dot files.

The rationale is that
 - it is not always the cmxs that is necessary .e.g., rdbg uses .cma or .ml
 - it makes more sense to refer to the source code
parent d9d1abfd
Pipeline #23879 failed with stages
in 8 minutes and 24 seconds
......@@ -12,9 +12,9 @@ lib/sasacore/sasaVersion.ml
*.log
*.save
rdbg-session*.ml
my-rdbg-tuning.ml
*.lut
*.org_archive
Makefile.local
notes.org
sasa-*.dot
\ No newline at end of file
sasa-*.dot
*.html
\ No newline at end of file
......@@ -9,6 +9,8 @@ install:
dune install sasalib
dune install sasacore
reinstall:install
.PHONY:test
test:
make
......
- [Releases Notes](#orgc2b7d30)
- [Compiling sasa sources](#orgc27ced7)
- [Parsing dot files](#org7e14df4)
- [The Algo API](#org335f114)
- [Demons](#org63372b4)
- [Dealing with Algorithm values](#orgb08bc57)
- [Processes](#orgd866b14)
- [CLI arguments (sasa options)](#orga3cba4d)
- [The Main Simulation](#org1478484)
- [The sasa rdbg plugin](#org18b1950)
- [Generating Version Numbers](#orgf807ba5)
- [Pluging `sasa` on Synchronous tools](#orgc8030da)
- [RIF](#org325acbc)
- [The rdbg plugin](#org8217566)
- [Releases Notes](#orgc258f2f)
- [Compiling sasa sources](#orgf0202c6)
- [Parsing dot files](#orgac76d9a)
- [The Algo API](#org9a3aaee)
- [Demons](#orgb528205)
- [Dealing with Algorithm values](#org38fa2cc)
- [Processes](#org71c6dca)
- [CLI arguments (sasa options)](#org27ce8af)
- [The Main Simulation](#orgb196df4)
- [The sasa rdbg plugin](#org72bd883)
- [Generating Version Numbers](#org6deee97)
- [Pluging `sasa` on Synchronous tools](#orgf7dae34)
- [RIF](#orga7e4647)
- [The rdbg plugin](#orgc135b8f)
Self-stabilizing Algorithms SimulAtor (Simulation d'Algorithmes autoStAbilisants)
Contributors Guide
<a id="orgc2b7d30"></a>
<a id="orgc258f2f"></a>
# Releases Notes
<https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/releases>
<a id="orgc27ced7"></a>
<a id="orgf0202c6"></a>
# Compiling sasa sources
......@@ -40,7 +40,7 @@ You will need:
cf the test job in the Gitlab CI script: [../../.gitlab-ci.yml](../../.gitlab-ci.yml) for a working installation process.
<a id="org7e14df4"></a>
<a id="orgac76d9a"></a>
# Parsing dot files
......@@ -74,14 +74,14 @@ val read: string -> t
This module is also used from `rdbg` ([../../test/rdbg-utils/dot.ml](../../test/rdbg-utils/dot.ml)) to display dynamic graphs, where local variable values, as well as enabled and triggered actions, are made visible at each step.
<a id="org335f114"></a>
<a id="org9a3aaee"></a>
# The Algo API
Users only need to see the [../../lib/algo/algo.mli](../../lib/algo/algo.mli) file.
```ocaml
(* Time-stamp: <modified the 26/03/2019 (at 16:25) by Erwan Jahier> *)
(* Time-stamp: <modified the 03/04/2019 (at 23:12) by Erwan Jahier> *)
(** Process programmer API *)
type varT = It | Ft | Bt | Et of int | St | Nt | At of varT * int
......@@ -125,6 +125,7 @@ val value_to_string : value -> string
(**/**)
(** functions below are not part of the API *)
val vart_to_rif_decl: varT -> string -> (string * string) list
val vart_to_rif_string: varT -> string -> string
val verbose_level: int ref
......@@ -143,7 +144,7 @@ val get_actions : algo_id -> action list
Functions registration is based on the `Dynlink` module (in the ocaml standard library) and (Hash)tables.
<a id="org63372b4"></a>
<a id="orgb528205"></a>
# Demons
......@@ -210,7 +211,7 @@ val f: Process.t list -> string
- [../../lib/sasacore/genLutin.ml](../../lib/sasacore/genLutin.ml )
<a id="orgb08bc57"></a>
<a id="org38fa2cc"></a>
# Dealing with Algorithm values
......@@ -235,12 +236,12 @@ The current implementation is based on
[../../lib/sasacore/env.ml](../../lib/sasacore/env.ml)
<a id="orgd866b14"></a>
<a id="org71c6dca"></a>
# Processes
```ocaml
(* Time-stamp: <modified the 02/04/2019 (at 14:39) by Erwan Jahier> *)
(* Time-stamp: <modified the 30/04/2019 (at 16:02) by Erwan Jahier> *)
(** There is such a Process.t per node in the dot file. *)
type t = {
......@@ -252,21 +253,23 @@ type t = {
step : Algo.step_fun;
}
(** [make custom_mode_flag node] builds a process out of a dot
(** [make dynlink_flag custom_mode_flag node] builds a process out of a dot
node. To do that, it retreives the registered functions by Dynamic
linking of the cmxs file specified in the "algo" field of the dot
node.
dynlink_flag: link the algo.cmxs files (not possible from rdbg)
nb: it provides variable initial values if not done in the dot
(via the init field) nor in the Algo (via Algo.reg_init_vars) *)
val make: bool -> Topology.node -> t
val make: bool -> bool -> Topology.node -> t
```
- [../../lib/sasacore/process.mli](../../lib/sasacore/process.mli)
- [../../lib/sasacore/process.ml](../../lib/sasacore/process.ml)
<a id="orga3cba4d"></a>
<a id="org27ce8af"></a>
# CLI arguments (sasa options)
......@@ -274,7 +277,7 @@ val make: bool -> Topology.node -> t
- [../../lib/sasacore/sasArg.ml](../../lib/sasacore/sasArg.ml)
<a id="org1478484"></a>
<a id="orgb196df4"></a>
# The Main Simulation
......@@ -284,14 +287,14 @@ It is splitted into 2 modules, so that the sasa rdbg plugin can reuse the step f
2. [../../src/sasaMain.ml](../../src/sasaMain.ml)
<a id="org18b1950"></a>
<a id="org72bd883"></a>
# TODO The sasa rdbg plugin
# The sasa rdbg plugin
In order to be able to use `sasa` from `rdbg`, we needed to implement an `rdbg` plugin. `rdbg` plugin must implement this interface:
```ocaml
(* Time-stamp: <modified the 05/07/2018 (at 14:01) by Erwan Jahier> *)
(* Time-stamp: <modified the 05/04/2019 (at 11:23) by Erwan Jahier> *)
(* This module defines the data structure required by RDBG to run a Reactive Program. *)
......@@ -303,6 +306,8 @@ type t = {
outputs : (Data.ident * Data.t) list; (* ditto *)
reset: unit -> unit;
kill: string -> unit;
save_state: int -> unit;
restore_state: int -> unit;
init_inputs : sl;
init_outputs : sl;
step : (sl -> sl); (* Lurette step *)
......@@ -317,13 +322,15 @@ cf <https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/rdbg/blob/mas
This is done the SasaRun module:
```ocaml
(* Time-stamp: <modified the 02/04/2019 (at 15:50) by Erwan Jahier> *)
(* XXX finishme!
Actually, the I/O mode of rdbg already makes it possible to use sasa
from rdbg and see all of its variable values after each step (exit
event). This plugin would only be necessary when we would need a
finer-grained intrumentation, e.g., to stop at enable step, or to
at each process call/exit.
event). This plugin is necessary when one need a finer-grained
intrumentation, e.g., to stop at enable step, or to at each process
call/exit.
*)
val make: string array -> RdbgPlugin.t
......@@ -334,8 +341,13 @@ val make: string array -> RdbgPlugin.t
using [../../lib/sasacore/sasa.ml](../../lib/sasacore/sasa.ml)
Examples of use can be found in:
- <../../test/rdbg-utils/dot.ml>
- <../../test/my-rdbg-tuning.ml>
<a id="orgf807ba5"></a>
<a id="org6deee97"></a>
# Generating Version Numbers
......@@ -349,12 +361,12 @@ In order to generate sensible version numbers, please follow in your commit mess
This also permits to generate some Releases Notes: <https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/releases>
<a id="orgc8030da"></a>
<a id="orgf7dae34"></a>
# Pluging `sasa` on Synchronous tools
<a id="org325acbc"></a>
<a id="orga7e4647"></a>
## RIF
......@@ -371,10 +383,12 @@ val bool: bool -> Process.t -> string -> bool
[../../lib/sasacore/rifRead.mli](../../lib/sasacore/rifRead.mli) [../../lib/sasacore/rifRead.ml](../../lib/sasacore/rifRead.ml)
<a id="org8217566"></a>
<a id="orgc135b8f"></a>
## The rdbg plugin
<https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/rdbg/blob/master/src/rdbgPlugin.mli> <https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/lutils/blob/master/src/data.mli>
[../../test/rdbg-utils/dot.ml](../../test/rdbg-utils/dot.ml)
<../../test/rdbg-utils/dot.ml>
<../../test/my-rdbg-tuning.ml>
......@@ -100,7 +100,7 @@ the step functions:
1. [[file:../../lib/sasacore/sasa.ml][../../lib/sasacore/sasa.ml]]
2. [[file:../../src/sasaMain.ml][../../src/sasaMain.ml]]
* TODO The sasa rdbg plugin
* The sasa rdbg plugin
In order to be able to use =sasa= from =rdbg=, we needed to implement
an =rdbg= plugin. =rdbg= plugin must implement this interface:
......@@ -114,10 +114,15 @@ This is done the SasaRun module:
- [[file:../../lib/sasalib/sasaRun.mli][../../lib/sasalib/sasaRun.mli]]
- [[file:../../lib/sasalib/sasaRun.ml][../../lib/sasalib/sasaRun.ml]]
using [[file:../../lib/sasacore/sasa.ml][../../lib/sasacore/sasa.ml]]
Examples of use can be found in:
- [[file:../../test/rdbg-utils/dot.ml]]
- [[file:../../test/my-rdbg-tuning.ml]]
* Generating Version Numbers
The [[file:../../lib/sasacore/sasaVersion.ml][../../lib/sasacore/sasaVersion.ml]] is automatically generated
......@@ -149,4 +154,7 @@ http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/lustre-v6/#outline-container-sec
https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/rdbg/blob/master/src/rdbgPlugin.mli
https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/lutils/blob/master/src/data.mli
[[file:../../test/rdbg-utils/dot.ml][../../test/rdbg-utils/dot.ml]]
[[file:../../test/rdbg-utils/dot.ml]]
[[file:../../test/my-rdbg-tuning.ml]]
- [Dot files](#org6e13edb)
- [Algorithms](#org5472073)
- [Demons](#orgd84484b)
- [Built-in demons](#org772ca23)
- [Custom demons](#org6740745)
- [CLI](#org8becf3b)
- [Lutin, `lurette`, and `rdbg`](#org5638eae)
- [Releases Notes](#orgc326780)
- [Installation](#org4f42e09)
- [From source](#org394c459)
- [Via opam (not yet working)](#orgeefe583)
- [Dot files](#org9b6cc20)
- [Algorithms](#org29f2947)
- [Demons](#org694cfde)
- [Built-in demons](#org8d16af4)
- [Custom demons](#orgd5cd96c)
- [CLI](#org998ad93)
- [Lutin, `lurette`, and `rdbg`](#org001ae14)
- [Running interactive sessions with `rdbg`](#org2a5d735)
- [Running batch sessions with `lurette`](#orga6eb316)
- [Releases Notes](#org003b79a)
- [Installation](#orge3b3c64)
- [From source](#org76bf580)
- [Via opam (not yet working)](#org618e858)
Basically, one needs to provide
......@@ -16,31 +18,33 @@ Basically, one needs to provide
2. the algorithms mentionned in the dot file
<a id="org6e13edb"></a>
<a id="org9b6cc20"></a>
# Dot files
Dot files should
1. follow the [graphviz/dot format](https://en.wikipedia.org/wiki/DOT_(graph_description_language)).
2. contain nodes labelled by the `algo` field
2. all nodes **must be labelled** by the `algo` field
```dot
graph ring {
p1 [algo="some_algo.cmxs"]
p2 [algo="some_algo.cmxs"]
p3 [algo="some_algo.cmxs"]
p4 [algo="some_algo.cmxs"]
p5 [algo="some_algo.cmxs"]
p6 [algo="some_algo.cmxs"]
p7 [algo="some_algo.cmxs"]
p1 [algo="some_algo.ml"]
p2 [algo="some_algo.ml"]
p3 [algo="some_algo.ml"]
p4 [algo="some_algo.ml"]
p5 [algo="some_algo.ml"]
p6 [algo="some_algo.ml"]
p7 [algo="some_algo.ml"]
p1 -- p2 -- p3 -- p4 -- p5 -- p6 -- p7 -- p1
}
```
Of course the `some_algo.ml` file must exist.
<a id="org5472073"></a>
<a id="org29f2947"></a>
# Algorithms
......@@ -59,7 +63,7 @@ More precisely, each algorithm should provide 3 functions that must be registred
which profiles is defined in [algo.mli](https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/blob/master/lib/algo/algo.mli)
```ocaml
(* Time-stamp: <modified the 26/03/2019 (at 16:25) by Erwan Jahier> *)
(* Time-stamp: <modified the 03/04/2019 (at 23:12) by Erwan Jahier> *)
(** Process programmer API *)
type varT = It | Ft | Bt | Et of int | St | Nt | At of varT * int
......@@ -103,6 +107,7 @@ val value_to_string : value -> string
(**/**)
(** functions below are not part of the API *)
val vart_to_rif_decl: varT -> string -> (string * string) list
val vart_to_rif_string: varT -> string -> string
val verbose_level: int ref
......@@ -119,19 +124,19 @@ Optionnaly, one can register a function that provides initial values to local va
```dot
graph ring {
p1 [algo="some_algo.cmxs" init="v=1" init="x=3"]
p2 [algo="some_algo.cmxs"]
p3 [algo="some_algo.cmxs"]
p4 [algo="some_algo.cmxs"]
p5 [algo="some_algo.cmxs"]
p6 [algo="some_algo.cmxs"]
p7 [algo="some_algo.cmxs"]
p1 [algo="some_algo.ml" init="v=1" init="x=3"]
p2 [algo="some_algo.ml"]
p3 [algo="some_algo.ml"]
p4 [algo="some_algo.ml"]
p5 [algo="some_algo.ml"]
p6 [algo="some_algo.ml"]
p7 [algo="some_algo.ml"]
p1 -- p2 -- p3 -- p4 -- p5 -- p6 -- p7 -- p1
}
```
Algorithms must then be compiled with `ocamlopt -shared` to produce the cmxs files mentionned in the dot file algo fields.
Algorithms must then be compiled with `ocamlopt -shared` to produce the `.cmxs` files corresponding to the `.ml` mentionned in the dot file algo fields.
```sh
ocamlopt -shared -I +sasa some_algo.ml -o some_algo.cmxs
......@@ -142,12 +147,12 @@ Actions names (`string`) must be registered if one wants to use `sasa` with cust
Some examples can be found in the [test](https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/tree/master/test) directory.
<a id="orgd84484b"></a>
<a id="org694cfde"></a>
# Demons
<a id="org772ca23"></a>
<a id="org8d16af4"></a>
## Built-in demons
......@@ -160,7 +165,7 @@ Built-in demons are usable via one of the following options:
--custom-demon, -custd
<a id="org6740745"></a>
<a id="orgd5cd96c"></a>
## Custom demons
......@@ -177,10 +182,10 @@ It can also by simulated by `lutin` programs via the use of `lurette` (for batch
Built-in demons can of course be programmed in Lutin. One can generate such demons using the `--gen-lutin-demon` option: `sasa --gen-lutin-demon a_graph.dot`. It can be handy at least to get the demons variables names in the good order if one to write its own demon.
For using the custom mode, it is mandatory to register actions (via `Algo.reg_actions`).
Moreover, for using the custom mode, it is mandatory to register actions (via `Algo.reg_actions`).
<a id="org8becf3b"></a>
<a id="org998ad93"></a>
# CLI
......@@ -208,6 +213,8 @@ sasa --help
--length, -l <int>
Maximum number of steps to be done (10000 by default).
--version, -version, -v
Display the sasa version and exit.
--verbose, -vl <int>
Set the verbose level
--help, -help, -h
......@@ -222,25 +229,29 @@ sasa --more
--gen-lutin-demon, -gld
Generate Lutin demons and exit
--list-algos, -algo
Output the algo names used in the dot file and exit.
--dummy-input
Add a dummy input to sasa so that built-in demon can be used from rdbg
--ignore-first-inputs, -ifi
Ignore first inputs (necessary to use luciole via lurette/rdbg/luciole-rif)
--version, -version, -v
Display the sasa version and exit.
Ignore first inputs (necessary to use luciole via
lurette/rdbg/luciole-rif)
--ocaml-version
Display the version ocaml version sasa was compiled with and exit.
<a id="org5638eae"></a>
<a id="org001ae14"></a>
# TODO Lutin, `lurette`, and `rdbg`
# Lutin, `lurette`, and `rdbg`
cf `Makefile` in the [test](https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/tree/master/test) directory.
In each sub-directory of [../../test/](../../test/), there is a `rdbg-session.ml` file that takes care of the red-tape for using `rdbg` with the corresponding examples.
If you:
<a id="org2a5d735"></a>
## Running interactive sessions with `rdbg`
1. type `rdbg`
2. press enter to load the defaut session (`rdbg-session.ml`). Then you can type:
......@@ -249,24 +260,80 @@ If you:
5. `s` to move one step forward
6. `sd` to move one step forward and call `d` (to update the graph display [])
7. `nr` to move one round forward
8. `go` to move forward until convergence
8. `pr` to move one round backward
9. `go` to move forward until convergence
All those commands are defined in [../../test/my-rdbg-tuning.ml](../../test/my-rdbg-tuning.ml) that is included in `test/*/rdbg-session.ml` files. This file contain straigthforward `ocaml` code that defines various `rdbg` shortcuts to ease the simulation of `sasa` systems. Feel free to tailor those command to yours needs!
For instance, go to the `test/alea-coloring/` directory. It contains the following files:
- `my-rdbg-tuning.ml` that is actually a symbolic link to the [../../test/my-rdbg-tuning.ml](../../test/my-rdbg-tuning.ml) file
- `ring.dot`: the topology
- `p.ml`: the algo used in `ring.dot`
- `Makefile`: demonstrate various ways of using `sasa`
```sh
make rdbg
```
This rule
- generates the `p.cmxs` and `p.cma` files, resulting from the compilation of `p.ml` (the makefile rules are in `../Makefile.inc`).
- generates a `ring.lut` file (out of `ring.dot` and `p.cmxs`) that defines various Lutin demons
- launch `rdbg` with some arguments. `rdbg` then prompts the user to enter some commands.
```sh
rdbg -o ring.rif \
-env "sasa -seed 42 -l 100 ring.dot -custd -rif" \
-sut-nd "lutin ring.lut -n distributed"
[c] create a fresh session
[q] quit
[s] do nothing
[0/s/q/c/1/2/...]:
```
hence let's create a fresh session by typing 'c' and then 'return'. This will result in the creation of the `rdbg_session.ml` file, that load all the necessary modules to run an interactive session with `rdbg`, where `rdbg` simulates ring.dot with `sasa` using a distributed demon.
For instance, you can type `nr [return]`, a rdbg command defined in [../../test/my-rdbg-tuning.ml](../../test/my-rdbg-tuning.ml) that steps until the next round is reached. Then, by typing `[return]`; `rdbg` will run the lastly used command, which is `nr`, which allow you to move forward in the execution from rounds to rounds. If you want to go backwards to the previous round, you can use the `br` command=, also defined in [../../test/my-rdbg-tuning.ml](../../test/my-rdbg-tuning.ml).
nb: the next time rdbg is launched (even without argument), you will be prompted with the possibility to reuse this session.
```sh
rdbg
[0] #use "rdbg-session.ml"
[c] create a fresh session
[q] quit
[s] do nothing
[0/s/q/c/1/2/...]:
```
Typing '0' will therefore also load the `rdbg_session.ml` file we have just been using.
<a id="orga6eb316"></a>
## Running batch sessions with `lurette`
XXX TODO
<a id="orgc326780"></a>
<a id="org003b79a"></a>
# Releases Notes
<https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/releases>
<a id="org4f42e09"></a>
<a id="orge3b3c64"></a>
# Installation
<a id="org394c459"></a>
<a id="org76bf580"></a>
## From source
......@@ -281,7 +348,7 @@ You will need:
One can mimick the content of the `test` job in the project [Gitlab CI script](https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/blob/master/.gitlab-ci.yml).
<a id="orgeefe583"></a>
<a id="org618e858"></a>
## Via opam (not yet working)
......
......@@ -9,22 +9,24 @@ Basically, one needs to provide
Dot files should
1. follow the [[https://en.wikipedia.org/wiki/DOT_(graph_description_language)][graphviz/dot format]].
2. contain nodes labelled by the =algo= field
2. all nodes *must be labelled* by the =algo= field
#+BEGIN_SRC dot
graph ring {
p1 [algo="some_algo.cmxs"]
p2 [algo="some_algo.cmxs"]
p3 [algo="some_algo.cmxs"]
p4 [algo="some_algo.cmxs"]
p5 [algo="some_algo.cmxs"]
p6 [algo="some_algo.cmxs"]
p7 [algo="some_algo.cmxs"]
p1 [algo="some_algo.ml"]
p2 [algo="some_algo.ml"]
p3 [algo="some_algo.ml"]
p4 [algo="some_algo.ml"]
p5 [algo="some_algo.ml"]
p6 [algo="some_algo.ml"]
p7 [algo="some_algo.ml"]
p1 -- p2 -- p3 -- p4 -- p5 -- p6 -- p7 -- p1
}
#+END_SRC
Of course the =some_algo.ml= file must exist.
* Algorithms
Those algorithms, implemented in =ocaml=, must provide:
......@@ -50,20 +52,21 @@ random.
#+BEGIN_SRC dot
graph ring {
p1 [algo="some_algo.cmxs" init="v=1" init="x=3"]
p2 [algo="some_algo.cmxs"]
p3 [algo="some_algo.cmxs"]
p4 [algo="some_algo.cmxs"]
p5 [algo="some_algo.cmxs"]
p6 [algo="some_algo.cmxs"]
p7 [algo="some_algo.cmxs"]
p1 [algo="some_algo.ml" init="v=1" init="x=3"]
p2 [algo="some_algo.ml"]
p3 [algo="some_algo.ml"]
p4 [algo="some_algo.ml"]
p5 [algo="some_algo.ml"]
p6 [algo="some_algo.ml"]
p7 [algo="some_algo.ml"]
p1 -- p2 -- p3 -- p4 -- p5 -- p6 -- p7 -- p1
}
#+END_SRC