From d4752be10fa54d0d949d900921dda4fa06456436 Mon Sep 17 00:00:00 2001
From: Erwan Jahier <erwan.jahier@univ-grenoble-alpes.fr>
Date: Wed, 16 Sep 2020 15:46:18 +0200
Subject: [PATCH] Doc: some enhancements in the Algo API doc
---
lib/algo/algo.mli | 96 +++++++++++++++++++++++++++++------------------
1 file changed, 59 insertions(+), 37 deletions(-)
diff --git a/lib/algo/algo.mli b/lib/algo/algo.mli
index 282c8ebb..9460dc00 100644
--- a/lib/algo/algo.mli
+++ b/lib/algo/algo.mli
@@ -1,9 +1,11 @@
-(* Time-stamp: <modified the 02/09/2020 (at 10:27) by Erwan Jahier> *)
-(** {1 The Algorithm programming Interface.} *)
-(**
- {1 What's need to be provided by users.}
+(* Time-stamp: <modified the 16/09/2020 (at 15:42) by Erwan Jahier> *)
+(** {1 The Algorithm programming Interface}
+
A SASA process is an instance of an algorithm defined via this
module.
+*)
+(**
+ {2 To be provided by users}
In order to define a SASA algorithm, one need to provide an enable
and a step function:
@@ -18,15 +20,22 @@ type 's neighbor
type action = string
type 's enable_fun = 's -> 's neighbor list -> action list
type 's step_fun = 's -> 's neighbor list -> action -> 's
-(** The first argument holds the current state of the process. As it is
+(** [enable_fun] and [step_fun] have the same arguments in input:
+
+ - The first argument holds the current state of the process. As it is
polymorphic (['s]), algorithms designers can put anything they need
into this state (an integer, a structure, etc.). The only constraint
is that all algorithms should use the same type.
- The second argument holds the process neighbors. Note that SASA
+ - The second argument holds the process neighbors. Note that SASA
processes, that live in graph nodes, can only access to their
immediate neighbors. From each neighbor, a process can access to
- various information thanks to the functions below.
+ various information (cf [state], [reply], and [weight] functions below).
+
+ [enable_fun] returns the list of enable actions.
+
+ [step_fun], which also takes an action in input, returns the new value
+ of the local state resulting from the execution of the action.
*)
type 's state_init_fun = int -> string -> 's
@@ -35,14 +44,47 @@ type 's state_init_fun = int -> string -> 's
of node neighbors, and the pid. Anonymous algorithms are not
supposed to use the pid. *)
-(** Returns the processes local state *)
+(** {2 To be provided optionally} *)
+
+(** {3 Potential function}
+
+ Let the user define what the potential of a configuration is.
+ Used to explore best/worst case daemons (--worst-daemon)
+*)
+
+type pid = string
+type 's potential_fun = pid list -> (pid -> 's * 's neighbor list) -> float
+
+
+(** {3 Legitimate Configurations} *)
+
+type 's legitimate_fun = pid list -> (pid -> 's * 's neighbor list) -> bool
+(** By default, legitimate configurations (i.e., global states) are
+ silent ones. But this is not true for all algorithms. Predicates
+ of this type are used to redefine what's a legitimate configuration
+ is. *)
+
+
+(** {3 Fault Injection } *)
+
+type 's fault_fun = int -> string -> 's -> 's
+(** The fault function is called on each node to update their state
+ each time a legitimate configuration is reached. It takes 3
+ arguments: the number of node neighbors, the pid, and the value of
+ the current state. *)
+
+(** {2 Can be used in algorithms} *)
+
+(** {3 Process (local) Information} *)
+
+(** Returns the neighbor processes local state *)
val state : 's neighbor -> 's
-(** Returns the channel number, that let this neighbor access to the
- content of the current process, if its neighbor can access it. The
- channel number is the rank,starting at 0, in the neighbors' list.
- Returns -1 if the neighbor can not access to the process, which may
- happen in directed graphs.
+(** Returns the neighbor channel number, that let this neighbor access
+ to the content of the current process, if its neighbor can access
+ it. The channel number is the rank,starting at 0, in the
+ neighbors' list. Returns -1 if the neighbor can not access to the
+ process, which may happen in directed graphs.
An algorithm that uses reply, and not the pid, is called
semi-anonymous. It is called anonymous if it can access none. *)
@@ -53,10 +95,11 @@ val reply : 's neighbor -> int
returned if not weight is set in the graph. *)
val weight : 's neighbor -> int
+(** For debugging *)
val print_neighbor: 's neighbor -> unit
val fmt_print_neighbor: Format.formatter -> 's neighbor -> unit
-(** {1 Access to Topological Information}
+(** {3 Topological Information}
When writing algorithms, one can also have access to topological
information (i.e., information that are relative to the graph) *)
@@ -79,29 +122,8 @@ val diameter : unit -> int
val get_graph_attribute : string -> string
-(** {1 Potential function }
-
- Let the user define what the potential of a configuration is.
- Used to explore best/worst case daemons (--worst-daemon)
-*)
-type pid = string
-type 's potential_fun = pid list -> (pid -> 's * 's neighbor list) -> float
-
-(** {1 Legitimate Configurations} *)
-type 's legitimate_fun = pid list -> (pid -> 's * 's neighbor list) -> bool
-(** By default, legitimate configurations (i.e., global states) are
- silent ones. But this is not true for all algorithms. Predicates
- of this type are used to redefine what's a legitimate configuration
- is. *)
-
-(** {1 Fault Injection} *)
-type 's fault_fun = int -> string -> 's -> 's
-(** The fault function is called on each node to update their state
- each time a legitimate configuration is reached. It takes 3
- arguments: the number of node neighbors, the pid, and the value of
- the current state. *)
-(** {1 Code Registration}
+(** {2 Code Registration}
The [register: 's to_register -> unit] function must be called once in
the user code. *)
@@ -135,7 +157,7 @@ type 's to_register = {
(** To be called once *)
val register : 's to_register -> unit
-(** {1 Automatic Generation of Registration Code}
+(** {1 Automatic Code Registration }
Once enable and step functions are defined, they need to be
registered by calling the register function.
--
GitLab