doc/module-msg.doc

   1 /** \defgroup MSG_JAVA      jMSG
   2     \ingroup MSG_API
   3     \brief Java bindings to MSG (\ref MSG_API)
   4
   5     \htmlonly <!--
   6       DOXYGEN_NAVBAR_LABEL="JAVA bindings"
   7       DOXYGEN_NAVBAR_CHILD "Simulation functions"=classsimgrid_1_1msg_1_1Msg.html
   8       DOXYGEN_NAVBAR_CHILD "Host"=classsimgrid_1_1msg_1_1Host.html
   9       DOXYGEN_NAVBAR_CHILD "Process"=classsimgrid_1_1msg_1_1Process.html
  10       DOXYGEN_NAVBAR_CHILD "Task"=classsimgrid_1_1msg_1_1Task.html
  11       DOXYGEN_NAVBAR_CHILD "MsgException"=classsimgrid_1_1msg_1_1MsgException.html
  12     --> \endhtmlonly
  13
  14       MSG was the first distributed programming environment provided within
  15       SimGrid. While almost realistic, it remains quite simple (simplistic?).
  16       This describes the Java bindings to this interface.
  17
  18       \section jMSG_who Who should use this (and who shouldn't)
  19
  20       You should use MSG if you want to study some heuristics for a
  21       given problem you don't really want to implement. If you want to
  22       use the Java programming language, your are in the right
  23       section. To use the C interface, please refer to \ref MSG_C.
  24 */
  25
  26 /** \defgroup MSG_C      MSG native
  27     \ingroup MSG_API
  28     \brief Native interface to MSG (\ref MSG_API)
  29
  30     \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Native interface" --> \endhtmlonly
  31
  32       MSG was the first distributed programming environment provided within
  33       SimGrid. While almost realistic, it remains quite simple (simplistic?).
  34       This describes the native to MSG.
  35
  36       \section jMSG_who Who should use this (and who shouldn't)
  37
  38       You should use MSG if you want to study some heuristics for a
  39       given problem you don't really want to implement. If you want to
  40       use the C programming language, your are in the right
  41       section. To use the Java programming interface, please refer to
  42       \ref MSG_JAVA.
  43 */
  44
  45 /** @addtogroup MSG_C
  46
  47   \section MSG_funct Offered functionnalities
  48    - \ref m_process_management
  49    - \ref m_datatypes_management
  50    - \ref m_host_management
  51    - \ref m_task_management
  52    - \ref msg_gos_functions
  53    - \ref m_channel_management
  54    - \ref msg_easier_life
  55    - \ref msg_simulation
  56
  57   \section MSG_examples Examples of MSG
  58
  59    - \ref MSG_ex_master_slave
  60 */
  61
  62 /** @defgroup m_datatypes_management MSG Data Types
  63     @ingroup MSG_C
  64     @brief This section describes the different datatypes provided by MSG.
  65
  66     \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Data types" --> \endhtmlonly
  67 */
  68 /**     \addtogroup m_process_management
  69         \ingroup MSG_C  */
  70 /**     \addtogroup m_host_management
  71         \ingroup MSG_C  */
  72 /**     \addtogroup m_task_management
  73         \ingroup MSG_C  */
  74 /**     \addtogroup msg_gos_functions
  75         \ingroup MSG_C  */
  76 /**     \addtogroup m_channel_management
  77         \ingroup MSG_C  */
  78 /**     \addtogroup msg_easier_life
  79         \ingroup MSG_C  */
  80 /**     \addtogroup msg_simulation
  81         \ingroup MSG_C  */
  82
  83 /** \page MSG_ex_master_slave Master/slave application
  84
  85     Simulation of a master-slave application using a realistic platform and
  86     an external description of the deployment.
  87
  88     \section MSG_ex_ms_TOC Table of contents:
  89
  90      - \ref MSG_ext_ms_code
  91        - \ref MSG_ext_ms_preliminary
  92        - \ref MSG_ext_ms_master
  93        - \ref MSG_ext_ms_slave
  94        - \ref MSG_ext_ms_forwarder
  95        - \ref MSG_ext_ms_core
  96        - \ref MSG_ext_ms_main
  97      - \ref MSG_ext_ms_helping
  98        - \ref MSG_ext_ms_application
  99        - \ref MSG_ext_ms_platform
 100
 101     <hr>
 102
 103     \dontinclude msg/masterslave/masterslave_forwarder.c
 104
 105     \section MSG_ext_ms_code Code of the application
 106
 107     \subsection MSG_ext_ms_preliminary Preliminary declarations
 108
 109     \skip include
 110     \until printf
 111     \until }
 112
 113     \subsection MSG_ext_ms_master Master code
 114
 115       This function has to be assigned to a m_process_t that will behave as the master.
 116       It should not be called directly but either given as a parameter to
 117       #MSG_process_create() or registered as a public function through
 118       #MSG_function_register() and then automatically assigned to a process through
 119       #MSG_launch_application().
 120
 121       C style arguments (argc/argv) are interpreted as:
 122        - the number of tasks to distribute
 123        - the computation size of each task
 124        - the size of the files associated to each task
 125        - a list of host that will accept those tasks.
 126
 127       Tasks are dumbly sent in a round-robin style.
 128
 129       \until end_of_master
 130
 131     \subsection MSG_ext_ms_slave Slave code
 132
 133       This function has to be assigned to a #m_process_t that has to behave as a slave.
 134       Just like the master fuction (described in \ref MSG_ext_ms_master), it should not be called directly.
 135
 136       This function keeps waiting for tasks and executes them as it receives them.
 137
 138       \until end_of_slave
 139
 140    \subsection MSG_ext_ms_forwarder Forwarder code
 141
 142       This function has to be assigned to a #m_process_t that has to behave as a forwarder.
 143       Just like the master fuction (described in \ref MSG_ext_ms_master), it should not be called directly.
 144
 145       C style arguments (argc/argv) are interpreted as a list of host
 146       that will accept those tasks.
 147
 148       This function keeps waiting for tasks and dispathes them to its slaves.
 149
 150       \until end_of_forwarder
 151
 152    \subsection MSG_ext_ms_core Simulation core
 153
 154       This function is the core of the simulation and is divided only into 3 parts
 155       thanks to MSG_create_environment() and MSG_launch_application().
 156          -# Simulation settings : MSG_create_environment() creates a realistic
 157             environment
 158          -# Application deployment : create the agents on the right locations with
 159             MSG_launch_application()
 160          -# The simulation is run with #MSG_main()
 161
 162       Its arguments are:
 163         - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.
 164         - <i>application_file</i>: the name of a file containing a valid surfxml application description
 165
 166       \until end_of_test_all
 167
 168    \subsection MSG_ext_ms_main Main() function
 169
 170       This initializes MSG, runs a simulation, and free all data-structures created by MSG.
 171
 172       \until end_of_main
 173
 174    \section MSG_ext_ms_helping Helping files
 175
 176    \subsection MSG_ext_ms_application Example of application file
 177
 178    \include msg/masterslave/deployment_masterslave.xml
 179
 180    \subsection MSG_ext_ms_platform Example of platform file
 181
 182    \include msg/small_platform.xml
 183
 184 */