Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
2a35441fcfecc170750b7695da8a84536c39c0bc
[simgrid.git] / 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 */