X-Git-Url: https://bilbo.iut-bm.univ-fcomte.fr/and/gitweb/loba.git/blobdiff_plain/ffc874c5572820b9e2533d6e7b01602bfd5909d2..acde6b9f1a36c21e89e587eade3a57d636cd8f86:/README

diff --git a/README b/README
index db47b28..7db502a 100644
--- a/README
+++ b/README
@@ -1,3 +1,15 @@
+Contenu
+=======
+* Compilation de SimGrid
+* Compilation...
+* Utilisation
+* Tracé de courbes
+* Communications
+* Pour ajouter un nouvel algorithme d'équilibrage
+* Pour ajouter une nouvelle option au programme
+* Liste des fichiers
+----------------------------------------------------------------------
+
 Compilation de SimGrid
 ======================
 
@@ -15,18 +27,99 @@ d'installation de SimGrid (par ex. /usr/local).
 Utilisation
 ===========
 
-Pour avoir l'aide en ligne :
-$ ./loba -hhh
+Idée générale : on dispose d'une plate-forme (décrite dans le fichier
+XML qui va bien), et on déploie dessus une application.  La notion de
+voisinage entre les processus est *liée à l'application*.  Il faut
+évidemment que la plate-forme sous-jacente autorise les communications
+entre voisins...
+
+Pour avoir l'aide en ligne sur les différents paramètres :
+    $ ./loba -h                 (ou -hh, ou -hhh, pour plus de détails)
 
 Pour changer le niveau de détail des affichages :
         --log=category.thres:level
     avec
         category : simu, main, depl, comm, proc, loba
     et
-        level : trace, debug, verbose, info, warning, error, critical
+           level : trace, debug, verbose, info, warning, error, critical
+
+Pour plus de détail sur les options de logging :
+    http://simgrid.gforge.inria.fr/doc/group__XBT__log.html#log_use
+
+Tracé de courbes
+================
+
+Le script extract.pl permet d'extraire les données à partir des traces
+de simulation et de le présenter sous un format acceptable par gnuplot
+ou par graph (plotutils).
+
+Exemple:
+        ./loba platform.xml 2>&1 | ./extract.pl | graph -CTX
+
+Communications
+==============
+
+Pour communiquer, chaque processus écoute sur 2 mailboxes (sortes de
+ports) :
+  - une pour les message de contrôle ;
+  - une pour les transferts de charge.
+
+Ceci afin d'éviter de bloquer les échanges d'information pendant un
+transfert de charge.
+
+À la fin, chaque processus envoie un message "CLOSE" à tous ses
+voisins (sur chaque mailbox), et attends d'avoir reçu deux messages par
+voisin (un sur chaque mailbox).
+
+Ceci permet de synchroniser les processus à la terminaison (ça, à la
+rigueur, on s'en fout un peu), et surtout de s'assurer qu'il n'y a
+plus de communication qui « traîne » dans les canaux.
+
+Cela permet aussi de ne pas réarmer les communications non bloquantes
+qu'on ne sait pas annuler proprement (un manque dans SimGrid).
+
+Il ne faut bien sûr plus envoyer de message après avoir envoyé un
+"CLOSE".
 
-Fichiers
-========
+Attention : lors du déploiement de l'application, il faut s'assurer que
+la relation de voisinage est symétrique !
+*Ce n'est pas vérifié par le programme.*
+
+Pour ajouter un nouvel algorithme d'équilibrage
+===============================================
+
+1. Imiter ce qui est fait pour loba_simple :
+   - définir une nouvelle classe dérivant de process
+   - attention, il faut construire le process explicitement
+   - redéfinir la méthode load_balance qui :
+     - peut récupérer la charge courante avec get_load()
+     - peut utiliser et éventuellement réordonner le tableau process::pneigh ;
+     - peut récupérer l'information de charge d'un voisin avec
+           pneigh[i]->get_load() ;
+     - définit la charge à envoyer avec
+           send(pneigh[i], quantité) ;
+
+2. Ajouter l'algorithme dans la liste des options.  Dans options.cpp :
+   - faire le #include adéquat ;
+   - ajouter une ligne NOL_INSERT(...) dans la liste existante
+     (dans loba_algorithms_type::loba_algorithms_type()).
+
+Pour ajouter une nouvelle option au programme
+=============================================
+
+1. Ajouter une variable, déclarée dans options.h et définie dans options.cpp
+   (classement plus ou moins thématique).
+
+2. Toujours dans options.cpp, il faut :
+   - compléter la fonction opt::parse_args(), normalement le 3e paramètre à
+     getopt() et le switch..case qui suit (garder l'ordre alphabétique) ;
+   - compléter la fonction opt::print() (avec le même ordre que en 1.) ;
+   - compléter la fonction opt::usage() (avec le même ordre que en 1.).
+
+3. Utiliser la nouvelle variable au(x) bon(s) endroit(s) !
+
+Liste de fichiers
+=================
 
 * fichiers de description de plates-formes
 
@@ -53,8 +146,10 @@ Fichiers
     hostdata.h                  gestion des boites de réception, par hôte
     hostdata.cpp
 
-    loba_simple.h               load-balancing simple (à copier pour ajouter
-    loba_simple.cpp             d'autres algorithmes)
+    loba_simple.h               équilibrage simple
+    loba_simple.cpp             (à imiter pour ajouter d'autres algorithmes)
+
+    loba_*.{h,cpp}              autres algos d'équilibrage
 
     main.cpp                    le programme principal
 
@@ -62,7 +157,7 @@ Fichiers
     misc.cpp
 
     named_object_list.h         gestion d'une table de constructeurs
-                                avec des noms et des descritpions
+                                avec des noms et des descriptions
 
     neighbor.h                  un voisin pour un processus
     neighbor.cpp
@@ -82,6 +177,17 @@ Fichiers
     version.h                   gestion de la version du programme
     version.cpp
 
+* scripts
+
+    colorized-loba              script pour exécuter loba en colorant les
+                                sorties
+
+    extract.pl                  outil d'extraction des données à partir des
+                                traces, pour tracer des courbes
+
+    setlocalversion             calcule un numéro de version à partir du hash
+                                du dernier commit (git)
+
 * autres fichiers
 
     .gitignore                  liste des fichiers ignorés par git