From 5cda998afbc44eec777a20403d0f97cfd83fa1f7 Mon Sep 17 00:00:00 2001
From: Erwan Jahier <erwan.jahier@univ-grenoble-alpes.fr>
Date: Tue, 2 Apr 2019 15:31:29 +0200
Subject: [PATCH] Doc: some documentation work (users guide, contributors
guide, code interface, etc.)
---
guides/contributors/README.md | 343 ++++++++++++++++++++++++++++-----
guides/contributors/README.org | 127 ++++++++----
guides/users/README.md | 221 ++++++++++++++++++---
guides/users/README.org | 169 ++++++++++++++--
lib/sasacore/demon.ml | 12 +-
lib/sasacore/demon.mli | 35 +++-
lib/sasacore/env.mli | 7 +-
lib/sasacore/genLutin.mli | 4 +-
lib/sasacore/process.ml | 5 +-
lib/sasacore/process.mli | 15 +-
lib/sasacore/sasArg.ml | 14 +-
lib/sasacore/sasArg.mli | 4 +-
lib/sasacore/topology.mli | 11 +-
test/README.md | 15 ++
test/README.org | 22 +++
test/my-rdbg-tuning.ml | 1 +
test/rdbg-utils/dot.ml | 2 +-
17 files changed, 831 insertions(+), 176 deletions(-)
create mode 100644 test/README.md
create mode 100644 test/README.org
diff --git a/guides/contributors/README.md b/guides/contributors/README.md
index 9d254ef7..ca45ad95 100644
--- a/guides/contributors/README.md
+++ b/guides/contributors/README.md
@@ -1,106 +1,347 @@
-- [Compiling sasa sources](#org30c5984)
-- [Graph editor](#org350e6d3)
-- [The Algo API](#orgf0dab07)
-- [Demons](#org009ddc4)
-- [Dealing with Algorithm values](#org02f3ab5)
-- [Representing Processes](#org889a969)
-- [CLI arguments (sasa options)](#org83b3139)
-- [The Main Simulation](#orge4efe80)
-- [Generating Version Numbers](#orgd3a1891)
-- [Pluging `sasa` on Synchronous tools](#org20e7801)
- - [RIF](#org286d056)
- - [The rdbg plugin](#org769e7a6)
+- [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)
Self-stabilizing Algorithms SimulAtor (Simulation d'Algorithmes autoStAbilisants)
Contributors Guide
-<a id="org30c5984"></a>
+<a id="orgc2b7d30"></a>
+
+# Releases Notes
+
+<https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/releases>
+
+
+<a id="orgc27ced7"></a>
# Compiling sasa sources
You will need:
-- make
-- a set of tools installable via opam
- - dune
- - ocamlgraph
- - lutin (not for compiling actually, but for using sasa with custom demons)
+- `make`
+- a set of tools installable via [opam](https://opam.ocaml.org/)
+ - `dune`
+ - `ocamlgraph`
+ - `lutin` (not for compiling actually, but for using sasa with custom demons)
+
+cf the test job in the Gitlab CI script: [../../.gitlab-ci.yml](../../.gitlab-ci.yml) for a working installation process.
-cf the test job in the Gitlab CI script: <../../.gitlab-ci.yml> for a working installation process.
+<a id="org7e14df4"></a>
-<a id="org350e6d3"></a>
+# Parsing dot files
-# Graph editor
+The `dot` file parsing is based on the `ocamlgraph` library. It is done by the Topology module:
-Based on dot + custom fields (algo, init) <../../lib/sasacore/topology.mli> <../../lib/sasacore/topology.ml>
+```ocaml
+(* Time-stamp: <modified the 02/04/2019 (at 13:42) by Erwan Jahier> *)
+
+type node_id = string
+type node = {
+ id: node_id; (* The id of the node as stated in the dot file *)
+ file: string; (* the content of the algo field (a cxms file) *)
+ init: (string * string) list; (* store the content of the init field *)
+}
+
+type edge = node_id * node_id list
-This module is also used from `rdbg` (<../../test/rdbg-utils/dot.ml>)
+type t = {
+ nodes: node list;
+ succ: node_id -> node_id list;
+ of_id: node_id -> node;
+}
+
+(** Parse a sasa dot file *)
+val read: string -> t
+```
+- [../../lib/sasacore/topology.mli](../../lib/sasacore/topology.mli)
+- [../../lib/sasacore/topology.ml](../../lib/sasacore/topology.ml)
-<a id="orgf0dab07"></a>
+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>
# The Algo API
-<../../lib/algo/algo.mli> <../../lib/algo/algo.ml>
+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> *)
+
+(** Process programmer API *)
+type varT = It | Ft | Bt | Et of int | St | Nt | At of varT * int
+type vars = (string * varT) list
+
+type value = I of int | F of float | B of bool | E of int | S of string
+ | N of int (* neighbor canal number *)
+ | A of value array
+type local_env = string -> value
+type action = string (* label *)
+
+type neighbor = {
+ lenv: local_env;
+ n_vars: vars;
+ pid: unit -> string; (* this info is not available in all modes (e.g., anonymous) *)
+ reply: unit -> int; (* ditto *)
+}
+
+type enable_fun = neighbor list -> local_env -> action list
+type step_fun = neighbor list -> local_env -> action -> local_env
+
+(** Those 3 registering functions must be called! *)
+type algo_id = string
+val reg_vars : algo_id -> vars -> unit
+val reg_enable : algo_id -> enable_fun -> unit
+val reg_step : algo_id -> step_fun -> unit
-Functions registration is based on Dynlink + (Hash)tables
+(** raised by sasa if one of the function above is not called *)
+exception Unregistred of string * string
-Users only need to see the [mli](../../lib/algo/algo.mli) file.
+(** This one is not mandatory. The initialisation done in the dot
+ file have priority over this one. *)
+val reg_init_vars : algo_id -> (neighbor list -> local_env) -> unit
+(** Mandatory in custom mode only. *)
+val reg_actions : algo_id -> action list -> unit
-<a id="org009ddc4"></a>
+(** util(s) *)
+val value_to_string : value -> string
+
+
+(**/**)
+(** functions below are not part of the API *)
+val vart_to_rif_string: varT -> string -> string
+val verbose_level: int ref
+
+
+(** the following functions are used by sasa *)
+val get_vars : algo_id -> vars
+val get_enable : algo_id -> enable_fun
+val get_step : algo_id -> step_fun
+val get_init_vars : algo_id -> (string * varT) list -> (neighbor list -> local_env)
+val get_actions : algo_id -> action list
+```
+
+- [../../lib/algo/algo.mli](../../lib/algo/algo.mli)
+- [../../lib/algo/algo.ml](../../lib/algo/algo.ml)
+
+Functions registration is based on the `Dynlink` module (in the ocaml standard library) and (Hash)tables.
+
+
+<a id="org63372b4"></a>
# Demons
-built-in + custom
+In the custom demon mode, the demon is executed outside `sasa`, by a process that communicates via the standard input/output. More precisely, `sasa` writes on `stdout` a Boolean for each action and each process, that states if the corresponding action is enabled for the current step. Then it reads on `stdin` a Boolean for each action and each process that tells which actions (among the enabled ones) should be activated.
-<../../lib/sasacore/demon.mli> <../../lib/sasacore/demon.ml>
+The demon can thus be played by users that read and enter Boolean values. It can also by simulated by `lutin` programs via the use of `lurette` (for batch executions) or `rdbg` (for interactive sessions).
+
+```ocaml
+(* Time-stamp: <modified the 02/04/2019 (at 14:03) by Erwan Jahier> *)
+
+type t =
+ | Synchronous (* select all actions *)
+ | Central (* select 1 action *)
+ | LocallyCentral (* never activates two neighbors actions in the same step *)
+ | Distributed (* select at least one action *)
+ | Custom (* enable/actions are communicated via stdin/stdout in RIF *)
-custom in Lutin that can generated by:
-<../../lib/sasacore/genLutin.mli> <../../lib/sasacore/genLutin.ml>
+type pna = Process.t * Algo.neighbor list * Algo.action
+(** f dummy_input_flag verbose_mode demon pl actions_ll enab
-<a id="org02f3ab5"></a>
+inputs:
+- dummy_input_flag: true when used with --ignore-first-inputs
+- verbose_mode: true when the verbose level is > 0
+- demon:
+- pl:
+- actions_ll: list of list of existing actions
+- enab_ll: list of list of enabled actions
-# Dealing with Algorithm values
+ At the inner list level, exactly one action ougth to be chosen. At the
+ outter list level, the number of chosen actions depends on the kind
+ of demons.
-<../../lib/sasacore/env.mli> <../../lib/sasacore/env.ml>
+ In custom mode, as a side-effect, read on stdin which actions should be activated.
+returns:
+ - a string containing the values (in RIF) of activating variables
+ - the list of activated actions
-<a id="org889a969"></a>
+nb: it is possible that we read on stdin that an action should be
+ activated even if it is not enabled (which would be a demon
+ "error"). For the time being, we ignore the demon "error" and
+ inhibit the activation.
+*)
+
+val f : bool -> bool -> t -> Process.t list -> pna list list -> bool list list ->
+ string * pna list
+```
-# Representing Processes
+- [../../lib/sasacore/demon.mli](../../lib/sasacore/demon.mli)
+- [../../lib/sasacore/demon.ml](../../lib/sasacore/demon.ml)
-<../../lib/sasacore/process.mli>
+custom Lutin programs that mimick the built-in modes can be generated by:
+
+```ocaml
+(* Time-stamp: <modified the 01/04/2019 (at 17:21) by Erwan Jahier> *)
+
+(** generated various Lutin demons (distributed, synchronous, etc.) *)
+val f: Process.t list -> string
+```
+- [../../lib/sasacore/genLutin.mli](../../lib/sasacore/genLutin.mli)
+- [../../lib/sasacore/genLutin.ml](../../lib/sasacore/genLutin.ml )
-<a id="org83b3139"></a>
+
+<a id="orgb08bc57"></a>
+
+# Dealing with Algorithm values
+
+```ocaml
+(* Storing process variables values *)
+type t
+
+val init: unit -> t
+
+(** [set env process_id var_name var_value] *)
+val set: t -> string -> string -> Algo.value -> t
+
+(** [get env process_id var_name] *)
+val get: t -> string -> string -> Algo.value
+```
+
+The current implementation is based on
+
+- [map](https://caml.inria.fr/pub/docs/manual-ocaml/libref/Map.html) for the process level,
+- function for the variable level
+
+[../../lib/sasacore/env.ml](../../lib/sasacore/env.ml)
+
+
+<a id="orgd866b14"></a>
+
+# Processes
+
+```ocaml
+(* Time-stamp: <modified the 02/04/2019 (at 14:39) by Erwan Jahier> *)
+
+(** There is such a Process.t per node in the dot file. *)
+type t = {
+ pid : string; (* unique *)
+ variables : Algo.vars;
+ actions: Algo.action list;
+ init : Algo.neighbor list -> Algo.local_env;
+ enable : Algo.enable_fun;
+ step : Algo.step_fun;
+}
+
+(** [make 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.
+
+ 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
+```
+
+- [../../lib/sasacore/process.mli](../../lib/sasacore/process.mli)
+- [../../lib/sasacore/process.ml](../../lib/sasacore/process.ml)
+
+
+<a id="orga3cba4d"></a>
# CLI arguments (sasa options)
-<../../lib/sasacore/sasArg.mli> <../../lib/sasacore/sasArg.ml>
+- [../../lib/sasacore/sasArg.mli](../../lib/sasacore/sasArg.mli)
+- [../../lib/sasacore/sasArg.ml](../../lib/sasacore/sasArg.ml)
-<a id="orge4efe80"></a>
+<a id="org1478484"></a>
# The Main Simulation
-Splitted into 2 modules, so that the sasa rdbg plugin can reuse the step functions <../../lib/sasacore/sasa.ml>
+It is splitted into 2 modules, so that the sasa rdbg plugin can reuse the step functions:
+
+1. [../../lib/sasacore/sasa.ml](../../lib/sasacore/sasa.ml)
+2. [../../src/sasaMain.ml](../../src/sasaMain.ml)
+
+
+<a id="org18b1950"></a>
+
+# TODO 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> *)
+
+(* This module defines the data structure required by RDBG to run a Reactive Program. *)
+
+type sl = ( string * Data .v) list (* substitutions *)
+type e = Event .t
+type t = {
+ id: string;
+ inputs : (Data.ident * Data.t) list; (* name and type *)
+ outputs : (Data.ident * Data.t) list; (* ditto *)
+ reset: unit -> unit;
+ kill: string -> unit;
+ init_inputs : sl;
+ init_outputs : sl;
+ step : (sl -> sl); (* Lurette step *)
+ step_dbg : (sl -> e -> ( sl -> e -> e) -> e); (* RDBG step *)
+}
+
+val dummy:t
+```
+
+cf <https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/rdbg/blob/master/src/rdbgPlugin.mli>
+
+This is done the SasaRun module:
+
+```ocaml
+(* 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.
+
+*)
+val make: string array -> RdbgPlugin.t
+```
+
+- [../../lib/sasalib/sasaRun.mli](../../lib/sasalib/sasaRun.mli)
+- [../../lib/sasalib/sasaRun.ml](../../lib/sasalib/sasaRun.ml)
-<../../src/sasaMain.ml>
+using [../../lib/sasacore/sasa.ml](../../lib/sasacore/sasa.ml)
-<a id="orgd3a1891"></a>
+<a id="orgf807ba5"></a>
# Generating Version Numbers
-The <../../lib/sasacore/sasaVersion.ml> is automatically generated
+The [../../lib/sasacore/sasaVersion.ml](../../lib/sasacore/sasaVersion.ml) is automatically generated
-- by <../../Makefile.version>
+- by [../../Makefile.version](../../Makefile.version)
- using git tags that are automatically generated using the `release` job of the CI script, which is based on [semantic-release-gitlab](https://www.npmjs.com/package/semantic-release-gitlab)
In order to generate sensible version numbers, please follow in your commit messages the conventions described here: <https://www.npmjs.com/package/conventional-changelog-eslint>
@@ -108,12 +349,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="org20e7801"></a>
+<a id="orgc8030da"></a>
# Pluging `sasa` on Synchronous tools
-<a id="org286d056"></a>
+<a id="org325acbc"></a>
## RIF
@@ -127,13 +368,13 @@ This also permits to generate some Releases Notes: <https://gricad-gitlab.univ-g
val bool: bool -> Process.t -> string -> bool
```
-<../../lib/sasacore/rifRead.mli> <../../lib/sasacore/rifRead.ml>
+[../../lib/sasacore/rifRead.mli](../../lib/sasacore/rifRead.mli) [../../lib/sasacore/rifRead.ml](../../lib/sasacore/rifRead.ml)
-<a id="org769e7a6"></a>
+<a id="org8217566"></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)
diff --git a/guides/contributors/README.org b/guides/contributors/README.org
index fd4210e0..d39a4370 100644
--- a/guides/contributors/README.org
+++ b/guides/contributors/README.org
@@ -4,77 +4,126 @@ Self-stabilizing Algorithms SimulAtor
Contributors Guide
+* Releases Notes
+
+https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/releases
* Compiling sasa sources
You will need:
-- make
-- a set of tools installable via opam
- - dune
- - ocamlgraph
- - lutin (not for compiling actually, but for using sasa with custom demons)
+- =make=
+- a set of tools installable via [[https://opam.ocaml.org/][opam]]
+ - =dune=
+ - =ocamlgraph=
+ - =lutin= (not for compiling actually, but for using sasa with custom demons)
-cf the test job in the Gitlab CI script: file:../../.gitlab-ci.yml
+cf the test job in the Gitlab CI script: [[file:../../.gitlab-ci.yml][../../.gitlab-ci.yml]]
for a working installation process.
-* Graph editor
+* Parsing dot files
+
+The =dot= file parsing is based on the =ocamlgraph= library. It is
+done by the Topology module:
+
+#+INCLUDE: "../../lib/sasacore/topology.mli" src ocaml
-Based on dot + custom fields (algo, init)
-file:../../lib/sasacore/topology.mli
-file:../../lib/sasacore/topology.ml
+- [[file:../../lib/sasacore/topology.mli][../../lib/sasacore/topology.mli]]
+- [[file:../../lib/sasacore/topology.ml][../../lib/sasacore/topology.ml]]
-This module is also used from =rdbg= (file:../../test/rdbg-utils/dot.ml)
+This module is also used from =rdbg= ([[file:../../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.
* The Algo API
-file:../../lib/algo/algo.mli
-file:../../lib/algo/algo.ml
-Functions registration is based on Dynlink + (Hash)tables
+Users only need to see the [[file:../../lib/algo/algo.mli][../../lib/algo/algo.mli]] file.
-Users only need to see the [[file:../../lib/algo/algo.mli][mli]] file.
+#+INCLUDE: "../../lib/algo/algo.mli" src ocaml
+
+- [[file:../../lib/algo/algo.mli][../../lib/algo/algo.mli]]
+- [[file:../../lib/algo/algo.ml][../../lib/algo/algo.ml]]
+
+Functions registration is based on the =Dynlink= module (in the ocaml
+standard library) and (Hash)tables.
* Demons
-built-in + custom
+In the custom demon mode, the demon is executed outside =sasa=, by a
+process that communicates via the standard input/output. More
+precisely, =sasa= writes on =stdout= a Boolean for each action and
+each process, that states if the corresponding action is enabled for
+the current step. Then it reads on =stdin= a Boolean for each action
+and each process that tells which actions (among the enabled ones)
+should be activated.
-file:../../lib/sasacore/demon.mli
-file:../../lib/sasacore/demon.ml
+The demon can thus be played by users that read and enter Boolean
+values. It can also by simulated by =lutin= programs via the use of
+=lurette= (for batch executions) or =rdbg= (for interactive sessions).
-custom in Lutin that can generated by:
-file:../../lib/sasacore/genLutin.mli
-file:../../lib/sasacore/genLutin.ml
+#+INCLUDE: "../../lib/sasacore/demon.mli" src ocaml
+- [[file:../../lib/sasacore/demon.mli][../../lib/sasacore/demon.mli]]
+- [[file:../../lib/sasacore/demon.ml][../../lib/sasacore/demon.ml]]
-* Dealing with Algorithm values
+custom Lutin programs that mimick the built-in modes can be generated
+by:
-file:../../lib/sasacore/env.mli
-file:../../lib/sasacore/env.ml
+#+INCLUDE: "../../lib/sasacore/genLutin.mli" src ocaml
+- [[file:../../lib/sasacore/genLutin.mli][../../lib/sasacore/genLutin.mli]]
+- [[file:../../lib/sasacore/genLutin.ml ][../../lib/sasacore/genLutin.ml]]
-* Representing Processes
+* Dealing with Algorithm values
-file:../../lib/sasacore/process.mli
+#+INCLUDE: "../../lib/sasacore/env.mli" src ocaml
-* CLI arguments (sasa options)
+The current implementation is based on
+- [[https://caml.inria.fr/pub/docs/manual-ocaml/libref/Map.html][map]] for the process level,
+- function for the variable level
+[[file:../../lib/sasacore/env.ml][../../lib/sasacore/env.ml]]
+
+* Processes
-file:../../lib/sasacore/sasArg.mli
-file:../../lib/sasacore/sasArg.ml
+#+INCLUDE: "../../lib/sasacore/process.mli" src ocaml
+- [[file:../../lib/sasacore/process.mli][../../lib/sasacore/process.mli]]
+- [[file:../../lib/sasacore/process.ml][../../lib/sasacore/process.ml]]
+
+* CLI arguments (sasa options)
+
+- [[file:../../lib/sasacore/sasArg.mli][../../lib/sasacore/sasArg.mli]]
+- [[file:../../lib/sasacore/sasArg.ml][../../lib/sasacore/sasArg.ml]]
* The Main Simulation
-Splitted into 2 modules, so that the sasa rdbg plugin
-can reuse the step functions
-file:../../lib/sasacore/sasa.ml
+It is splitted into 2 modules, so that the sasa rdbg plugin can reuse
+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
+
+In order to be able to use =sasa= from =rdbg=, we needed to implement
+an =rdbg= plugin. =rdbg= plugin must implement this interface:
+
+#+INCLUDE: "~/rdbg/src/rdbgPlugin.mli" src ocaml
+
+cf https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/rdbg/blob/master/src/rdbgPlugin.mli
+
+This is done the SasaRun module:
+#+INCLUDE: "../../lib/sasalib/sasaRun.mli" src ocaml
+- [[file:../../lib/sasalib/sasaRun.mli][../../lib/sasalib/sasaRun.mli]]
+- [[file:../../lib/sasalib/sasaRun.ml][../../lib/sasalib/sasaRun.ml]]
-file:../../src/sasaMain.ml
+
+using [[file:../../lib/sasacore/sasa.ml][../../lib/sasacore/sasa.ml]]
* Generating Version Numbers
-The file:../../lib/sasacore/sasaVersion.ml is automatically generated
-- by file:../../Makefile.version
+The [[file:../../lib/sasacore/sasaVersion.ml][../../lib/sasacore/sasaVersion.ml]] is automatically generated
+- by [[file:../../Makefile.version][../../Makefile.version]]
- using git tags that are automatically generated using the =release=
- job of the CI script, which is based on [[https://www.npmjs.com/package/semantic-release-gitlab][semantic-release-gitlab]]
+ job of the CI script, which is based on [[https://www.npmjs.com/package/semantic-release-gitlab][semantic-release-gitlab]]
In order to generate sensible version numbers, please follow in your
commit messages the conventions described here:
@@ -91,8 +140,8 @@ http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/lustre-v6/#outline-container-sec
#+INCLUDE: "../../lib/sasacore/rifRead.mli" src ocaml
-file:../../lib/sasacore/rifRead.mli
-file:../../lib/sasacore/rifRead.ml
+[[file:../../lib/sasacore/rifRead.mli][../../lib/sasacore/rifRead.mli]]
+[[file:../../lib/sasacore/rifRead.ml][../../lib/sasacore/rifRead.ml]]
** The rdbg plugin
@@ -100,4 +149,4 @@ file:../../lib/sasacore/rifRead.ml
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
+[[file:../../test/rdbg-utils/dot.ml][../../test/rdbg-utils/dot.ml]]
diff --git a/guides/users/README.md b/guides/users/README.md
index 3c3d4151..042a09e7 100644
--- a/guides/users/README.md
+++ b/guides/users/README.md
@@ -1,10 +1,14 @@
-- [Dot files](#org8fd8577)
-- [Algorithms](#orgcbbf32f)
-- [Simulation](#org996e21a)
-- [Custom mode](#orgd85b8c1)
-- [rdbg](#orgc83f02b)
-- [Releases Notes](#org56e1efd)
-- [Installation (not yet working)](#orgf1a43f7)
+- [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)
Basically, one needs to provide
@@ -12,7 +16,7 @@ Basically, one needs to provide
2. the algorithms mentionned in the dot file
-<a id="org8fd8577"></a>
+<a id="org6e13edb"></a>
# Dot files
@@ -36,11 +40,11 @@ graph ring {
```
-<a id="orgcbbf32f"></a>
+<a id="org5472073"></a>
# Algorithms
-Those algorithms must provide:
+Those algorithms, implemented in `ocaml`, must provide:
1. a set of variables (registers)
2. an `enable` fonction that says which actions are enabled (i.e., that can be activated)
@@ -54,7 +58,64 @@ 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)
-One can also register a function that provides initial values to local variables (`reg_init`). If not such registration is done, local variables will be set according to `init` annotations in the dot file. If no such annotations exists, initial values will be chosen at random.
+```ocaml
+(* Time-stamp: <modified the 26/03/2019 (at 16:25) by Erwan Jahier> *)
+
+(** Process programmer API *)
+type varT = It | Ft | Bt | Et of int | St | Nt | At of varT * int
+type vars = (string * varT) list
+
+type value = I of int | F of float | B of bool | E of int | S of string
+ | N of int (* neighbor canal number *)
+ | A of value array
+type local_env = string -> value
+type action = string (* label *)
+
+type neighbor = {
+ lenv: local_env;
+ n_vars: vars;
+ pid: unit -> string; (* this info is not available in all modes (e.g., anonymous) *)
+ reply: unit -> int; (* ditto *)
+}
+
+type enable_fun = neighbor list -> local_env -> action list
+type step_fun = neighbor list -> local_env -> action -> local_env
+
+(** Those 3 registering functions must be called! *)
+type algo_id = string
+val reg_vars : algo_id -> vars -> unit
+val reg_enable : algo_id -> enable_fun -> unit
+val reg_step : algo_id -> step_fun -> unit
+
+(** raised by sasa if one of the function above is not called *)
+exception Unregistred of string * string
+
+(** This one is not mandatory. The initialisation done in the dot
+ file have priority over this one. *)
+val reg_init_vars : algo_id -> (neighbor list -> local_env) -> unit
+
+(** Mandatory in custom mode only. *)
+val reg_actions : algo_id -> action list -> unit
+
+(** util(s) *)
+val value_to_string : value -> string
+
+
+(**/**)
+(** functions below are not part of the API *)
+val vart_to_rif_string: varT -> string -> string
+val verbose_level: int ref
+
+
+(** the following functions are used by sasa *)
+val get_vars : algo_id -> vars
+val get_enable : algo_id -> enable_fun
+val get_step : algo_id -> step_fun
+val get_init_vars : algo_id -> (string * varT) list -> (neighbor list -> local_env)
+val get_actions : algo_id -> action list
+```
+
+Optionnaly, one can register a function that provides initial values to local variables (`reg_init`). If not such registration is done, local variables will be set according to `init` annotations in the dot file. If no such annotations exists, initial values will be chosen at random.
```dot
graph ring {
@@ -76,41 +137,153 @@ Algorithms must then be compiled with `ocamlopt -shared` to produce the cmxs fil
ocamlopt -shared -I +sasa some_algo.ml -o some_algo.cmxs
```
+Actions names (`string`) must be registered if one wants to use `sasa` with custom demons (cf below).
+
Some examples can be found in the [test](https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/tree/master/test) directory.
-<a id="org996e21a"></a>
+<a id="orgd84484b"></a>
-# Simulation
+# Demons
-```sh
-sasa some_topo.dot
+
+<a id="org772ca23"></a>
+
+## Built-in demons
+
+Built-in demons are usable via one of the following options:
+
+ --synchronous-demon, -sd
+ --central-demon, -cd
+ --locally-central-demon, -lcd
+ --distributed-demon, -dd
+ --custom-demon, -custd
+
+
+<a id="org6740745"></a>
+
+## Custom demons
+
+In the custom demon mode, the demon is executed outside `sasa`, by a process that communicates via the standard input/output using [RIF](http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/lustre-v6/#outline-container-sec-5) conventions. More precisely, `sasa` writes on `stdout` a Boolean for each action and each process, that states if the corresponding action is enabled for the current step. Then it reads on `stdin` a Boolean for each action and each process that tells which actions (among the enabled ones) should be activated.
+
+The demon can thus be played by users that read and enter Boolean values.
+
+```shell
+cd ../../test/unison
+sasa ring.dot --custom-demon
+```
+
+It can also by simulated by `lutin` programs via the use of `lurette` (for batch executions) or `rdbg` (for interactive sessions).
+
+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`).
+
+
+<a id="org8becf3b"></a>
+
+# CLI
+
+```shell
sasa --help
```
+ usage: sasa [<option>]* <topology>.dot
+ use -h to see the available options.
+
+ --synchronous-demon, -sd
+ Use a Synchronous demon
+ --central-demon, -cd
+ Use a Central demon (selects exactly one action)
+ --locally-central-demon, -lcd
+ Use a Locally Central demon
+ (i.e., never activates two neighbors actions in the same step)
+ --distributed-demon, -dd
+ Use a Distributed demon (which select at least one action)
+ --custom-demon, -custd
+ Use a Custom demon (forces --rif)
+ --rif, -rif Follows RIF conventions
+ --seed, -seed
+ Set the pseudo-random generator seed of build-in demons
+ --length, -l <int>
+ Maximum number of steps to be done (10000 by default).
+
+ --verbose, -vl <int>
+ Set the verbose level
+ --help, -help, -h
+ Display main options
+ --more, -m Display more options
+
+For more options:
+
+```shell
+sasa --more
+```
+
+ --gen-lutin-demon, -gld
+ Generate Lutin demons 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.
+ --ocaml-version
+ Display the version ocaml version sasa was compiled with and exit.
+
+
+<a id="org5638eae"></a>
-<a id="orgd85b8c1"></a>
+# TODO Lutin, `lurette`, and `rdbg`
-# Custom mode
+cf `Makefile` in the [test](https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/tree/master/test) directory.
-For using the custom mode, it is mandatory to register actions
+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="orgc83f02b"></a>
+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`
+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 [])
+7. `nr` to move one round forward
+8. `go` to move forward until convergence
-# rdbg
+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!
-<a id="org56e1efd"></a>
+<a id="orgc326780"></a>
# Releases Notes
<https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/releases>
-<a id="orgf1a43f7"></a>
+<a id="org4f42e09"></a>
+
+# Installation
+
+
+<a id="org394c459"></a>
+
+## From source
+
+You will need:
+
+- `make` (gnu)
+- a set of tools installable via [opam](https://opam.ocaml.org/)
+ - `dune`
+ - `ocamlgraph`
+ - `lutin` (not for compiling actually, but for using sasa with custom demons)
+
+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>
-# Installation (not yet working)
+## Via opam (not yet working)
```sh
# optional
@@ -120,7 +293,7 @@ opam depext -y sasa
opam install -y sasa
```
-Once is is done, upgrading to the last version of the tools is as simple as:
+Once this is done, upgrading to the last version of the tools is as simple as:
```yaml
opam update
diff --git a/guides/users/README.org b/guides/users/README.org
index 644ec0c3..e9b8ddd1 100644
--- a/guides/users/README.org
+++ b/guides/users/README.org
@@ -25,10 +25,9 @@ graph ring {
}
#+END_SRC
-
* Algorithms
-Those algorithms must provide:
+Those algorithms, implemented in =ocaml=, must provide:
1. a set of variables (registers)
2. an =enable= fonction that says which actions are enabled (i.e., that can be activated)
3. a =step= function that executes enabled actions
@@ -41,9 +40,11 @@ registred using the string used in dot file algo fields with:
which profiles is defined in [[https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/blob/master/lib/algo/algo.mli][algo.mli]]
-One can also register a function that provides initial values to local
-variables (=reg_init=). If not such registration is done, local
-variables will be set according to =init= annotations in the dot
+#+INCLUDE: "../../lib/algo/algo.mli" src ocaml
+
+Optionnaly, one can register a function that provides initial values
+to local variables (=reg_init=). If not such registration is done,
+local variables will be set according to =init= annotations in the dot
file. If no such annotations exists, initial values will be chosen at
random.
@@ -68,25 +69,165 @@ the cmxs files mentionned in the dot file algo fields.
ocamlopt -shared -I +sasa some_algo.ml -o some_algo.cmxs
#+END_SRC
+Actions names (=string=) must be registered if one wants to use =sasa=
+with custom demons (cf below).
+
Some examples can be found in the [[https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/tree/master/test][test]] directory.
-* Simulation
+* Demons
-#+BEGIN_SRC sh
- sasa some_topo.dot
+** Built-in demons
+Built-in demons are usable via one of the following options:
+
+#+BEGIN_SRC shell :results output :exports results
+sasa -h | grep "\-demon"
+#+END_SRC
+
+#+RESULTS:
+: --synchronous-demon, -sd
+: --central-demon, -cd
+: --locally-central-demon, -lcd
+: --distributed-demon, -dd
+: --custom-demon, -custd
+
+** Custom demons
+
+In the custom demon mode, the demon is executed outside =sasa=, by a
+process that communicates via the standard input/output using [[http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/lustre-v6/#outline-container-sec-5][RIF]]
+conventions. More precisely, =sasa= writes on =stdout= a Boolean for
+each action and each process, that states if the corresponding action
+is enabled for the current step. Then it reads on =stdin= a Boolean
+for each action and each process that tells which actions (among the
+enabled ones) should be activated.
+
+The demon can thus be played by users that read and enter Boolean
+values.
+
+#+BEGIN_SRC shell :results output :exports both :var input="t t t t t t t"
+cd ../../test/unison
+sasa ring.dot --custom-demon
+#+END_SRC
+
+#+RESULTS:
+
+It can also by simulated by =lutin= programs via the use of
+=lurette= (for batch executions) or =rdbg= (for interactive sessions).
+
+
+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=).
+
+* CLI
+
+#+BEGIN_SRC shell :results output :exports both
sasa --help
-#+END_SRC
+#+END_SRC
-* Custom mode
+#+RESULTS:
+#+begin_example
+usage: sasa [<option>]* <topology>.dot
+use -h to see the available options.
+
+--synchronous-demon, -sd
+ Use a Synchronous demon
+--central-demon, -cd
+ Use a Central demon (selects exactly one action)
+--locally-central-demon, -lcd
+ Use a Locally Central demon
+ (i.e., never activates two neighbors actions in the same step)
+--distributed-demon, -dd
+ Use a Distributed demon (which select at least one action)
+--custom-demon, -custd
+ Use a Custom demon (forces --rif)
+--rif, -rif Follows RIF conventions
+--seed, -seed
+ Set the pseudo-random generator seed of build-in demons
+--length, -l <int>
+ Maximum number of steps to be done (10000 by default).
+
+--verbose, -vl <int>
+ Set the verbose level
+--help, -help, -h
+ Display main options
+--more, -m Display more options
+#+end_example
+
+For more options:
+
+#+BEGIN_SRC shell :results output :exports both
+ sasa --more
+#+END_SRC
+
+#+RESULTS:
+#+begin_example
+--gen-lutin-demon, -gld
+ Generate Lutin demons 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.
+--ocaml-version
+ Display the version ocaml version sasa was compiled with and exit.
+#+end_example
+
+
+* TODO Lutin, =lurette=, and =rdbg=
+
+cf =Makefile= in the [[https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/tree/master/test][test]] directory.
+
+
+In each sub-directory of [[file:../../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:
+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=
+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 [])
+7. =nr= to move one round forward
+8. =go= to move forward until convergence
+
+All those commands are defined in [[file:../../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 using the custom mode, it is mandatory to register actions
-* rdbg
* Releases Notes
https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/releases
-* Installation (not yet working)
+* Installation
+** From source
+
+You will need:
+- =make= (gnu)
+- a set of tools installable via [[https://opam.ocaml.org/][opam]]
+ - =dune=
+ - =ocamlgraph=
+ - =lutin= (not for compiling actually, but for using sasa with custom demons)
+
+One can mimick the content of the =test= job in the project [[https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/blob/master/.gitlab-ci.yml][Gitlab CI
+script]].
+
+** Via opam (not yet working)
#+BEGIN_SRC sh :tangle sh/install-opam.sh :noweb yes :tangle-mode (identity #o444)
# optional
@@ -96,7 +237,7 @@ opam depext -y sasa
opam install -y sasa
#+END_SRC
-Once is is done, upgrading to the last version of the tools is as
+Once this is done, upgrading to the last version of the tools is as
simple as:
#+BEGIN_SRC yaml
diff --git a/lib/sasacore/demon.ml b/lib/sasacore/demon.ml
index 25026063..6dccbc63 100644
--- a/lib/sasacore/demon.ml
+++ b/lib/sasacore/demon.ml
@@ -1,4 +1,4 @@
-(* Time-stamp: <modified the 02/04/2019 (at 10:48) by Erwan Jahier> *)
+(* Time-stamp: <modified the 02/04/2019 (at 13:57) by Erwan Jahier> *)
type t =
| Synchronous (* select all actions *)
@@ -31,17 +31,7 @@ let (synchrone: 'a list list -> 'a list) = fun all ->
type pna = Process.t * Algo.neighbor list * Algo.action
-(* From a list of enabled actions (pna) returns:
- - a string containing the values (in RIF) of activing_variables
- - the list of activated actions
-As a side-effect, read on stdin which actions should be activated.
-
-nb: it is possible that we read on stdin that an action should be
- activated even if it is not enabled (which would be a demon
- "error"). For the time being, we ignore the demon "error" and
- inhibit the activation.
-*)
let rec map3 f l1 l2 l3 =
match (l1, l2, l3) with
([], [], []) -> []
diff --git a/lib/sasacore/demon.mli b/lib/sasacore/demon.mli
index ed7ae474..07c6611b 100644
--- a/lib/sasacore/demon.mli
+++ b/lib/sasacore/demon.mli
@@ -1,4 +1,4 @@
-(* Time-stamp: <modified the 02/04/2019 (at 10:48) by Erwan Jahier> *)
+(* Time-stamp: <modified the 02/04/2019 (at 14:03) by Erwan Jahier> *)
type t =
| Synchronous (* select all actions *)
@@ -7,20 +7,35 @@ type t =
| Distributed (* select at least one action *)
| Custom (* enable/actions are communicated via stdin/stdout in RIF *)
-(** At the inner list level, exactly one action is chosen. At the
- outter list level, the number of chosen actions depends on the kind
- of demons.
- nb: only the Demon.custom mode may contain empty list, which
- happens if no rule is enabled in the corresponding process
+type pna = Process.t * Algo.neighbor list * Algo.action
+
+(** f dummy_input_flag verbose_mode demon pl actions_ll enab
+
+inputs:
+- dummy_input_flag: true when used with --ignore-first-inputs
+- verbose_mode: true when the verbose level is > 0
+- demon:
+- pl:
+- actions_ll: list of list of existing actions
+- enab_ll: list of list of enabled actions
- In custom mode, also returns the rif values read on stdin
- (returns the empty string in other modes).
+ At the inner list level, exactly one action ougth to be chosen. At the
+ outter list level, the number of chosen actions depends on the kind
+ of demons.
-f dummy_input verbose_mode demon pl all enab
+ In custom mode, as a side-effect, read on stdin which actions should be activated.
+
+returns:
+ - a string containing the values (in RIF) of activating variables
+ - the list of activated actions
+
+nb: it is possible that we read on stdin that an action should be
+ activated even if it is not enabled (which would be a demon
+ "error"). For the time being, we ignore the demon "error" and
+ inhibit the activation.
*)
-type pna = Process.t * Algo.neighbor list * Algo.action
val f : bool -> bool -> t -> Process.t list -> pna list list -> bool list list ->
string * pna list
diff --git a/lib/sasacore/env.mli b/lib/sasacore/env.mli
index 532860c7..50f60fb8 100644
--- a/lib/sasacore/env.mli
+++ b/lib/sasacore/env.mli
@@ -1,7 +1,10 @@
-
+(* Storing process variables values *)
type t
val init: unit -> t
-val get: t -> string -> string -> Algo.value
+
+(** [set env process_id var_name var_value] *)
val set: t -> string -> string -> Algo.value -> t
+(** [get env process_id var_name] *)
+val get: t -> string -> string -> Algo.value
diff --git a/lib/sasacore/genLutin.mli b/lib/sasacore/genLutin.mli
index ac5c2f02..4891f97b 100644
--- a/lib/sasacore/genLutin.mli
+++ b/lib/sasacore/genLutin.mli
@@ -1,4 +1,4 @@
-(* Time-stamp: <modified the 14/03/2019 (at 13:21) by Erwan Jahier> *)
-
+(* Time-stamp: <modified the 01/04/2019 (at 17:21) by Erwan Jahier> *)
+(** generated various Lutin demons (distributed, synchronous, etc.) *)
val f: Process.t list -> string
diff --git a/lib/sasacore/process.ml b/lib/sasacore/process.ml
index 0fd4235a..4cf6f3d8 100644
--- a/lib/sasacore/process.ml
+++ b/lib/sasacore/process.ml
@@ -1,4 +1,4 @@
-(* Time-stamp: <modified the 22/03/2019 (at 16:25) by Erwan Jahier> *)
+(* Time-stamp: <modified the 02/04/2019 (at 14:30) by Erwan Jahier> *)
type t = {
pid : string;
@@ -44,7 +44,8 @@ let (make: bool -> Topology.node -> t) =
try Algo.get_actions id
with _ ->
if custom_mode then
- failwith "Registering actions is mandatory in algorithms when using custom demon!"
+ failwith
+ "Registering actions is mandatory in algorithms when using custom demon!"
else ["a"]
in
let process = {
diff --git a/lib/sasacore/process.mli b/lib/sasacore/process.mli
index 7f9fb794..50432e5f 100644
--- a/lib/sasacore/process.mli
+++ b/lib/sasacore/process.mli
@@ -1,13 +1,20 @@
-(* Time-stamp: <modified the 10/03/2019 (at 22:47) by Erwan Jahier> *)
+(* Time-stamp: <modified the 02/04/2019 (at 14:39) by Erwan Jahier> *)
+(** There is such a Process.t per node in the dot file. *)
type t = {
pid : string; (* unique *)
variables : Algo.vars;
actions: Algo.action list;
init : Algo.neighbor list -> Algo.local_env;
- enable : Algo.enable_fun;
- step : Algo.step_fun ;
+ enable : Algo.enable_fun;
+ step : Algo.step_fun;
}
-(** build a process and set its variable initial values *)
+(** [make 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.
+
+ 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
diff --git a/lib/sasacore/sasArg.ml b/lib/sasacore/sasArg.ml
index 6ce0918b..86e6837b 100644
--- a/lib/sasacore/sasArg.ml
+++ b/lib/sasacore/sasArg.ml
@@ -1,4 +1,4 @@
-(* Time-stamp: <modified the 28/03/2019 (at 17:56) by Erwan Jahier> *)
+(* Time-stamp: <modified the 02/04/2019 (at 08:25) by Erwan Jahier> *)
type t = {
@@ -89,23 +89,23 @@ let (mkoptab : string array -> t -> unit) =
(
mkopt args ["--synchronous-demon";"-sd"]
(Arg.Unit(fun () -> args.demon <- Demon.Synchronous))
- ["Use a Synchronous deamon"];
+ ["Use a Synchronous demon"];
mkopt args ["--central-demon";"-cd"]
(Arg.Unit(fun () -> args.demon <- Demon.Central))
- ["Use a Central deamon (which selects exactly one action)"];
+ ["Use a Central demon (selects exactly one action)"];
mkopt args ["--locally-central-demon";"-lcd"]
(Arg.Unit(fun () -> args.demon <- Demon.LocallyCentral))
- ["Use a Locally Central deamon (which never activates two neighbors";
- "actions in the same step)"];
+ ["Use a Locally Central demon";
+ "(i.e., never activates two neighbors actions in the same step)"];
mkopt args ["--distributed-demon";"-dd"]
(Arg.Unit(fun () -> args.demon <- Demon.Distributed))
- ["Use a Distributed deamon (which select at least one action)"];
+ ["Use a Distributed demon (which select at least one action)"];
mkopt args ["--custom-demon";"-custd"]
(Arg.Unit(fun () -> args.demon <- Demon.Custom;args.rif <- true))
- ["Use a Custom deamon (forces --rif)"];
+ ["Use a Custom demon (forces --rif)"];
mkopt args ["--rif";"-rif"]
(Arg.Unit(fun () -> args.rif <- true))
diff --git a/lib/sasacore/sasArg.mli b/lib/sasacore/sasArg.mli
index e679d4d9..8b2aac96 100644
--- a/lib/sasacore/sasArg.mli
+++ b/lib/sasacore/sasArg.mli
@@ -1,5 +1,4 @@
-(* Time-stamp: <modified the 28/03/2019 (at 17:54) by Erwan Jahier> *)
-
+(* Time-stamp: <modified the 02/04/2019 (at 14:43) by Erwan Jahier> *)
type t = {
mutable topo: string;
@@ -22,5 +21,4 @@ type t = {
val usage_msg : string -> string
-
val parse : string array -> t
diff --git a/lib/sasacore/topology.mli b/lib/sasacore/topology.mli
index 102d2f20..e6ec97c7 100644
--- a/lib/sasacore/topology.mli
+++ b/lib/sasacore/topology.mli
@@ -1,18 +1,17 @@
-(* Time-stamp: <modified the 02/04/2019 (at 10:13) by Erwan Jahier> *)
+(* Time-stamp: <modified the 02/04/2019 (at 13:42) by Erwan Jahier> *)
type node_id = string
type node = {
- id: node_id;
- file: string;
- init: (string * string) list;
+ id: node_id; (* The id of the node as stated in the dot file *)
+ file: string; (* the content of the algo field (a cxms file) *)
+ init: (string * string) list; (* store the content of the init field *)
}
type edge = node_id * node_id list
-
type t = {
nodes: node list;
- succ: node_id -> node_id list;
+ succ: node_id -> node_id list;
of_id: node_id -> node;
}
diff --git a/test/README.md b/test/README.md
new file mode 100644
index 00000000..fa47f8d0
--- /dev/null
+++ b/test/README.md
@@ -0,0 +1,15 @@
+This directory contains various examples of self-stabilizing distributed programs taken from the book \`\`Introduction to Distributed Self-Stabilizing Algorithms'' By Altisen, Devismes, Dubois, and Petit.
+
+- <bfs-spanning-tree> : Bread-first-search spanning tree
+- <coloring>: graph coloring
+- <dijkstra-ring>: Dijkstra token ring
+- <unison>:
+
+It also contains an \`\`atomic state model'' version of a Depth First Search algorithm proposed by Collin and Dolev in 1994
+
+- <dfs>: Depth First search
+
+The following illustrate some possible use of `sasa` with `rdbg` on the examples above
+
+- <my-rdbg-tuning.ml>
+- <rdbg-utils/dot.ml>
diff --git a/test/README.org b/test/README.org
new file mode 100644
index 00000000..6c4f184d
--- /dev/null
+++ b/test/README.org
@@ -0,0 +1,22 @@
+
+
+This directory contains various examples of self-stabilizing
+distributed programs taken from the book ``Introduction to Distributed
+Self-Stabilizing Algorithms'' By Altisen, Devismes, Dubois, and Petit.
+
+- file:bfs-spanning-tree : Bread-first-search spanning tree
+- file:coloring: graph coloring
+- file:dijkstra-ring: Dijkstra token ring
+- file:unison:
+
+It also contains an ``atomic state model'' version of a Depth First
+Search algorithm proposed by Collin and Dolev in 1994
+
+- file:dfs: Depth First search
+
+
+The following illustrate some possible use of =sasa= with =rdbg= on
+the examples above
+
+- file:my-rdbg-tuning.ml
+- file:rdbg-utils/dot.ml
diff --git a/test/my-rdbg-tuning.ml b/test/my-rdbg-tuning.ml
index 59a0b8f4..854739f7 100644
--- a/test/my-rdbg-tuning.ml
+++ b/test/my-rdbg-tuning.ml
@@ -1,3 +1,4 @@
+(* Some useful short-cuts for rdbg interactive sessions *)
let _ = time_travel true;;
let e = ref (RdbgStdLib.run());;
diff --git a/test/rdbg-utils/dot.ml b/test/rdbg-utils/dot.ml
index 7ad93643..d5a4695b 100644
--- a/test/rdbg-utils/dot.ml
+++ b/test/rdbg-utils/dot.ml
@@ -1,4 +1,4 @@
-
+(** Generating dot files dynamically from rdbg *)
open Graph
open Graph.Dot_ast
--
GitLab