Use git diff instead of diff-index for setlocalversion.

[loba.git] / README

diff --git a/README b/README
index db47b28872728d02432899de5b1f9b645dc7454f..8e4e1c72ca45f1ee0b0bb1caf5b26dbbe2075466 100644 (file)
--- 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
 ======================
 
 Compilation de SimGrid
 ======================
 


@@ -15,23 +27,150 @@ d'installation de SimGrid (par ex. /usr/local).
 Utilisation
 ===========
 
 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
 
 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/simgrid/latest/doc/outcomes_logs.html#log_user
+
+Sorties
+=======
+
+* pendant la simulation :
+[Bourassa 5.000000] [proc/INFO] (6:1) current load: 5
+ +------- +-------   +--------   + +  -----+---------
+ |        |          |           | |       |
+ |        |          |           | |       \_ charge courante
+ |        |          |           | |
+ |        |          |           | \_ nombre d'itérations de calculs
+ |        |          |           |
+ |        |          |           \_ nombre d'itérations d'équilibrage
+ |        |          |
+ |        |          \_ catégorie de messages
+ |        |
+ |        \_ date courante (en secondes, dans la simulation)
+ |
+ \ nom du nœud
+
+* à la fin de la simulation :
+[Bourassa 108.886866] [proc/INFO] Final load after 107:4 iterations: 1.04113
+ +------- +---------   +--------                   +-- +             +------
+ |        |            |                           |   |             |
+ |        |            |                           |   |             \_ charge
+ |        |            |                           |   |                courante
+ |        |            |                           |   |
+ |        |            |                           |   \_ nombre d'itérations
+ |        |            |                           |      de calculs
+ |        |            |                           |
+ |        |            |                           \_ nombre d'itérations
+ |        |            |                              d'équilibrage
+ |        |            |
+ |        |            \_ catégorie de messages
+ |        |
+ |        \_ date courante (en secondes, dans la simulation)
+ |
+ \ nom du nœud
+
+
+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).
+
+Exemples:
+        ./loba platform.xml 2>&1 | ./extract.pl | graph -CTX
+
+        ./loba platform.xml 2>&1 | ./extract.pl | graph -CTX -y 0 250
+
+        ./loba platform.xml 2>&1 | ./extract.pl \
+            | gnuplot -p -e 'plot "-" using 1:2:(column(-2)) with lines lc variable'
+
+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é) ;
+   NB: le script new_loba.sh peut servir à créer les fichiers.
+
+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
 
     Plat.xml
     cluster1000.xml
 
 * fichiers de description de plates-formes
 
     Plat.xml
     cluster1000.xml

+    machines1000.xml

     platform.xml
 
 * fichiers de description de déploiement (tests)
     platform.xml
 
 * fichiers de description de déploiement (tests)


@@ -41,28 +180,36 @@ Fichiers
 
 * fichiers sources
 
 
 * fichiers sources
 

-    communicator.h
-    communicator.cpp            la couche de communication
+    communicator.h              la couche de communication
+    communicator.cpp

 
 

-    cost_func.h
-    cost_func.cpp               fonctions de coût pour comm_cost et comp_cost
+    cost_func.h                 fonctions de coût pour comm_cost et comp_cost
+    cost_func.cpp

 
 

-    deployment.h
-    deployment.cpp              génération automatique de déploiement
+    deployment.h                génération automatique de déploiement
+    deployment.cpp

 
     hostdata.h                  gestion des boites de réception, par hôte
     hostdata.cpp
 
 
     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
 
 
     main.cpp                    le programme principal
 

+    message.h                   file de messages reçus
+    message.cpp
+

     misc.h                      divers trucs inclassables
     misc.cpp
 
     misc.h                      divers trucs inclassables
     misc.cpp
 

+    msg_thread.h                creation de threads SG/MSG
+    msg_thread.cpp
+

     named_object_list.h         gestion d'une table de constructeurs
     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
 
     neighbor.h                  un voisin pour un processus
     neighbor.cpp


@@ -75,15 +222,35 @@ Fichiers
 
     simgrid_features.h          macros pour détecter la version de SimGrid
 
 
     simgrid_features.h          macros pour détecter la version de SimGrid
 

-    simple_async.cpp            un simple programme de test
+    statistics.h                pour calculer moyenne, variance, etc.
+
+    synchro.h                   mutex, condition, etc.
+
+    sync_queue.h                lock-free synchronized queue

 
     timer.h                     gestion de timer
 
 
     timer.h                     gestion de timer
 

+    tracing.h                   définitions liées au traçage
+

     version.h                   gestion de la version du programme
     version.cpp
 
     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
+
+    new_loba.sh                 pour créer le squelette d'un nouvel algo
+                                d'équiblibrage loba_*
+
+    setlocalversion             calcule un numéro de version à partir du hash
+                                du dernier commit (git)
+

 * autres fichiers
 
     .gitignore                  liste des fichiers ignorés par git
 * autres fichiers
 
     .gitignore                  liste des fichiers ignorés par git

-    valgrind_suppressions_3.5   liste de quelques suppressions pour valgrind
+    valgrind_suppressions       liste de quelques suppressions pour valgrind

                                 avec SimGrid 3.5
                                 avec SimGrid 3.5