From: alegrand Date: Thu, 27 Jan 2005 22:22:06 +0000 (+0000) Subject: updating the doc X-Git-Tag: v3.3~4554 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/52bbec97eae35ac830edcf70ab4970629e19e2b6?hp=10ba4620635259ef1dd168c905bc30deeaeb9bcd updating the doc git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@796 48e7efb5-ca39-0410-a469-dd3cf9ba447f --- diff --git a/doc/Doxyfile.API b/doc/Doxyfile.API index 73e9d18cbc..95d6a8c2ed 100644 --- a/doc/Doxyfile.API +++ b/doc/Doxyfile.API @@ -203,7 +203,7 @@ EXTRACT_PRIVATE = NO # If the EXTRACT_STATIC tag is set to YES all static members of a file # will be included in the documentation. -EXTRACT_STATIC = NO +EXTRACT_STATIC = YES # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) # defined locally in source files will be included in the documentation. diff --git a/doc/Doxyfile.Examples b/doc/Doxyfile.Examples index 743cb578a0..4059256b2f 100644 --- a/doc/Doxyfile.Examples +++ b/doc/Doxyfile.Examples @@ -203,7 +203,7 @@ EXTRACT_PRIVATE = NO # If the EXTRACT_STATIC tag is set to YES all static members of a file # will be included in the documentation. -EXTRACT_STATIC = NO +EXTRACT_STATIC = YES # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) # defined locally in source files will be included in the documentation. @@ -391,7 +391,7 @@ WARN_LOGFILE = # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = ../examples/msg \ +INPUT = ../examples/msg/ \ ../examples/modules.doc # If the value of the INPUT tag contains directories, you can use the diff --git a/doc/Makefile.am b/doc/Makefile.am index b530bdcf54..2b2f423c92 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -8,7 +8,7 @@ html: $(DOCSOURCES) Doxyfile.API Doxyfile.Examples Doxyfile.main @doxygen Doxyfile.API @doxygen Doxyfile.Examples @@top_srcdir@/tools/doxygen/index_create.pl html/API/API.tag @top_srcdir@/src/api_index.doc - @cp simgrid_logo.png html/ + @cp simgrid_logo.png simgrid_modules.jpg html/ @doxygen Doxyfile.API @doxygen Doxyfile.Examples @doxygen Doxyfile.main diff --git a/doc/index.doc b/doc/index.doc index 82bdf72296..c72b61e3c1 100644 --- a/doc/index.doc +++ b/doc/index.doc @@ -53,6 +53,12 @@ The SimGrid toolkit is composed of different modules : virtual platform through SURF. It follows the same principle as the ones used in GRAS but is specific to MPI applications. +Here is a figure the depicts the relation between those different modules. +
+\image html simgrid_modules.jpg +
+ + The section \ref publications contains links to papers that provide additional details on the project as well as validation and experimental results. diff --git a/doc/simgrid_modules.fig b/doc/simgrid_modules.fig new file mode 100644 index 0000000000..edc78c63ff --- /dev/null +++ b/doc/simgrid_modules.fig @@ -0,0 +1,79 @@ +#FIG 3.2 Produced by xfig version 3.2.5-alpha5 +Landscape +Center +Metric +A4 +100.00 +Single +-2 +1200 2 +0 32 #86e371 +0 33 #ffcb86 +0 34 #aebeff +0 35 #ff4951 +0 36 #a6a6a6 +6 810 4815 3915 5490 +6 832 4905 3892 5400 +4 1 0 50 -1 0 12 0.0000 2 150 2250 2362 5085 eXtensive Bundle of Tools\001 +4 1 0 50 -1 0 12 0.0000 2 195 3060 2362 5340 (lists, sets, dictionnaries, context...)\001 +-6 +2 2 0 1 0 33 60 -1 20 0.000 0 0 -1 0 0 5 + 810 4815 3915 4815 3915 5490 810 5490 810 4815 +-6 +6 -495 2520 1485 3465 +6 -405 2632 1395 3352 +4 1 0 50 -1 0 12 0.0000 2 150 480 495 2812 MSG\001 +4 1 0 50 -1 0 12 0.0000 2 150 1245 495 3322 level simulator\001 +4 1 0 50 -1 0 12 0.0000 2 195 1740 495 3067 a simple application-\001 +-6 +2 2 0 1 0 32 60 -1 20 0.000 0 0 -1 0 0 5 + -495 2520 1485 2520 1485 3465 -495 3465 -495 2520 +-6 +6 1845 765 4410 1935 +6 1957 855 4297 1845 +4 1 0 50 -1 0 12 0.0000 2 150 585 3127 1035 GRAS\001 +4 1 0 50 -1 0 12 0.0000 2 195 1890 3127 1290 framework to develop\001 +4 1 0 50 -1 0 12 0.0000 2 195 2220 3127 1545 distributed applications on\001 +4 1 0 50 -1 0 12 0.0000 2 195 2340 3127 1800 top of a virtual environment\001 +-6 +2 2 0 1 0 35 60 -1 20 0.000 0 0 -1 0 0 5 + 1845 765 4410 765 4410 1935 1845 1935 1845 765 +-6 +6 5130 1530 7920 2475 +6 5220 1620 7830 2385 +4 1 0 50 -1 0 12 0.0000 2 150 510 6525 1800 SMPI\001 +4 1 0 50 -1 0 12 0.0000 2 195 2595 6525 2055 library to run MPI applications\001 +4 1 0 50 -1 0 12 0.0000 2 195 2595 6525 2310 on top of a virtual environment\001 +-6 +2 2 0 1 0 36 60 -1 20 0.000 0 0 -1 0 0 5 + 5130 1530 7920 1530 7920 2475 5130 2475 5130 1530 +-6 +6 4995 4140 7245 4815 +6 5040 4230 7200 4725 +4 1 0 50 -1 0 12 0.0000 2 150 525 6120 4410 SURF\001 +4 1 0 50 -1 0 12 0.0000 2 195 2145 6120 4665 virtual platform simulator\001 +-6 +2 2 0 1 0 34 60 -1 20 0.000 0 0 -1 0 0 5 + 4995 4140 7245 4140 7245 4815 4995 4815 4995 4140 +-6 +2 1 0 1 0 7 70 -1 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 405 2970 2160 4815 +2 1 0 1 0 7 70 -1 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 3060 1305 2430 4815 +2 1 0 1 0 7 70 -1 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 3060 1305 5715 4140 +2 1 0 1 0 7 70 -1 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 450 2970 5265 4140 +2 1 0 1 0 7 70 -1 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 6480 1935 3015 4815 +2 1 0 1 0 7 70 -1 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 6480 1935 6795 4140 +2 1 0 1 0 7 70 -1 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 6120 4455 3915 5130 diff --git a/doc/simgrid_modules.jpg b/doc/simgrid_modules.jpg new file mode 100644 index 0000000000..5459dcfded Binary files /dev/null and b/doc/simgrid_modules.jpg differ diff --git a/examples/msg/messages.h b/examples/msg/messages.h index 02770d57d6..d20303350f 100644 --- a/examples/msg/messages.h +++ b/examples/msg/messages.h @@ -5,6 +5,12 @@ /* This program is free software; you can redistribute it and/or modify it * under the terms of the license (GNU LGPL) which comes with this package. */ +/** \file messages.h + * \ingroup MSG_examples + * \brief Convenient debuging functions that should be used in combination with + * the perl-script tools/MSG_visualization/colorize.pl. +*/ + #ifndef MESSAGES_H #define MESSAGES_H @@ -13,6 +19,11 @@ #include "msg/datatypes.h" #include "xbt/error.h" +/** just like an assert. + * This function is used to ensure that a condition is true. + * If not, it prints an error message (with the virtual date and the + * PID of the #m_process_t that called it). + */ static void ASSERT(int value, const char *fmt, ...) { m_process_t self = MSG_process_self(); @@ -31,6 +42,10 @@ static void ASSERT(int value, const char *fmt, ...) return; } +/** Die + * Just like #ASSERT() except you already know that the condition does not hold + * true. + */ static void DIE(const char *fmt, ...) { m_process_t self = MSG_process_self(); @@ -47,6 +62,10 @@ static void DIE(const char *fmt, ...) return; } +/** + * Print a one-line message with the virtual date and the PID of the #m_process_t + * that called it + */ static void PRINT_MESSAGE(const char *fmt, ...) { #ifdef VERBOSE @@ -63,6 +82,9 @@ static void PRINT_MESSAGE(const char *fmt, ...) return; } +/** + * Just like #PRINT_MESSAGE() except that it prints DEBUG in front of the line. + */ static void PRINT_DEBUG_MESSAGE(const char *fmt, ...) { #ifdef VERBOSE diff --git a/examples/msg/msg_test.c b/examples/msg/msg_test.c index 06adbb9ecf..cf6136e84f 100644 --- a/examples/msg/msg_test.c +++ b/examples/msg/msg_test.c @@ -5,8 +5,16 @@ /* This program is free software; you can redistribute it and/or modify it * under the terms of the license (GNU LGPL) which comes with this package. */ +/** \file msg_test.c + * \ingroup MSG_examples + * \brief Simulation of a master-slave application using a realistic platform + * and an external description of the deployment. +*/ + +/** Yeah! If you want to use msg, you need to include msg/msg.h */ #include "msg/msg.h" +/** This flag enable the debugging messages from #PRINT_DEBUG_MESSAGE() */ #define VERBOSE #include "messages.h" @@ -21,8 +29,11 @@ typedef enum { MAX_CHANNEL } channel_t; -void print_args(int argc, char** argv); -void print_args(int argc, char** argv) +/** Print arguments + * This function is just used so that users can check that each process + * has received the arguments it was supposed to receive. + */ +static void print_args(int argc, char** argv) { int i ; @@ -32,6 +43,21 @@ void print_args(int argc, char** argv) fprintf(stderr,">\n"); } +/** Emitter function + * This function has to be assigned to a m_process_t that will behave as the master. + It should not be called directly but either given as a parameter to + #MSG_process_create() or registered as a public function through + #MSG_function_register() and then automatically assigned to a process through + #MSG_launch_application(). + + C style arguments (argc/argv) are interpreted as + \li the number of tasks to distribute + \li the computation size of each task + \li the size of the files associated to each task + \li a list of host that will accept those tasks. + + Tasks are dumbly sent in a round-robin style. + */ int master(int argc, char *argv[]) { int slaves_count = 0; @@ -101,6 +127,12 @@ int master(int argc, char *argv[]) return 0; } +/** Receiver function + * This function has to be assigned to a #m_process_t that has to behave as a slave. + Just like #master(), it should not be called directly. + + This function keeps waiting for tasks and executes them as it receives them. + */ int slave(int argc, char *argv[]) { print_args(argc,argv); @@ -124,7 +156,15 @@ int slave(int argc, char *argv[]) return 0; } +/** Receiver function + * This function has to be assigned to a #m_process_t that has to behave as a forwarder. + Just like #master(), it should not be called directly. + C style arguments (argc/argv) are interpreted as a list of host + that will accept those tasks. + + This function keeps waiting for tasks and dispathes them to its slaves. + */ int forwarder(int argc, char *argv[]) { int i; @@ -169,6 +209,19 @@ int forwarder(int argc, char *argv[]) } +/** Test function + * This function is the core of the simulation and is divided only into 3 parts + * thanks to MSG_create_environment() and MSG_launch_application(). + * -# Simulation settings : MSG_create_environment() creates a realistic + * environment + * -# Application deployment : create the agents on the right locations with + * MSG_launch_application() + * -# The simulation is run with #MSG_main() + * @param platform_file the name of a file containing an valid surfxml platform + * description. + * @param application_file the name of a file containing a valid surfxml application + * description + */ void test_all(const char *platform_file,const char *application_file) { { /* Simulation setting */ @@ -185,6 +238,11 @@ void test_all(const char *platform_file,const char *application_file) printf("Simulation time %Lg\n",MSG_getClock()); } + +/** Main function + * This initializes MSG, runs a simulation, and free all data-structures created + * by MSG. + */ int main(int argc, char *argv[]) { MSG_global_init_args(&argc,argv);