-/*! \page deployment Deployment Description
+/*! @page deployment Deploy the simulation
-\section dep_over Overview
+@tableofcontents
-When using SimGrid, you basically need your user code, a platform description, and something allowing to map your (simulated) process on your (simulated) platform. This is what deployment file is all about. Note that you can bypass the file stuff and code it directly in your user code, if you want to.
+Once you've specified your @ref platform "virtual platform" and the
+@ref application "application" you want to study, you must describe
+the mapping of the application onto the platform. This page says how
+to do that if you go for online simulation (that is, the study of a
+program), you must say which code starts on which host, with which
+parameters. You can also go for offline simulation, i.e. the study of
+a trace captured from a past applicative run, as briefly explained
+@ref XBT_replay "here".
+There is two ways to specify the mapping of your program onto virtual
+hosts: either directly from your program (with @ref MSG_process_create
+or as in @ref s4u_ex_basics "this S4U example"), or using an external
+XML file. You should really logically separate your application from
+the deployment, as it will ease your experimental campain afterward.
+How exactly you organize your work remains up to you.
-\section dep_ex An example
-So deployment file just consists of saying which
-process runs where and which arguments it should take as input, the easier way to
-understand how to write it is just to take a look at the examples. Here is an example of it:
+@section deploy_s4u Deployment with S4U
-\verbatim
+The following example shows the several ways of doing so in the S4U
+interface: @ref examples/s4u/actor-create/s4u_actor-create.cpp.
+Associated XML file: @ref examples/s4u/actor-create/s4u_actor-create_d.xml
+
+@section deploy_msg Deployment with MSG
+
+If you're stuck with the MSG interface, then you should simply use one
+of the following functions to start new actors onto your virtual
+hosts: @ref MSG_process_create, @ref MSG_process_create_with_arguments
+or @ref MSG_process_create_with_environment. These functions are used
+in many of the provided example, just grep for them.
+
+@section deploy_xml Deployment with XML
+
+Deploying processes from XML is easy. This section presents a complete
+example and the reference guide of the involved tags.
+
+The deployment file looks just like a @ref platform "platform" file,
+with only 3 tags used:
+
+ - @c <process> starts a new actor on a given host;
+ - @c <argument> passes a given argument in the argv of an actor
+ (the list of arguments is ordered);
+ - @c <prop> adds a property to the actor.
+
+@subsection deploy_xml_ex Examples
+
+To make them easy to find, almost all deployment files in the archive
+are named @c ***_d_xml.
+
+@verbatim
<?xml version='1.0'?>
-<!DOCTYPE platform SYSTEM "http://simgrid.gforge.inria.fr/simgrid.dtd">
-<platform version="3">
- <!-- The master process (with some arguments) -->
- <process host="Tremblay" function="master">
- <argument value="20"/> <!-- Number of tasks -->
- <argument value="50000000"/> <!-- Computation size of tasks -->
- <argument value="1000000"/> <!-- Communication size of tasks -->
- <argument value="Jupiter"/> <!-- First slave -->
- <argument value="Fafard"/> <!-- Second slave -->
- <argument value="Ginette"/> <!-- Third slave -->
- <argument value="Bourassa"/> <!-- Last slave -->
- <argument value="Tremblay"/> <!-- Me! I can work too! -->
+<!DOCTYPE platform SYSTEM "http://simgrid.gforge.inria.fr/simgrid/simgrid.dtd">
+<platform version="4">
+ <!-- Alice, which runs on the machine named 'host1', does not take any parameter -->
+ <process host="host1" function="alice" />
+
+ <!-- Bob, which runs on 'host2', has 2 parameters "3" and "3000" in its argv -->
+ <process host="host2" function="bob" />
+ <argument value="3"/>
+ <argument value="3000"/>
+ </process>
+
+ <!-- Carole runs on 'host3', has 1 parameter "42" in its argv and one property -->
+ <!-- See MSG_process_get_property_value() to retrieve this property -->
+ <process host="host3" function="carole">
+ <argument value="42"/>
+ <prop id="SomeProp" value="SomeValue"/>
</process>
- <!-- The slave processes (with no argument) -->
- <process host="Tremblay" function="slave"/>
- <process host="Jupiter" function="slave"/>
- <process host="Fafard" function="slave"/>
- <process host="Ginette" function="slave"/>
- <process host="Bourassa" function="slave"/>
</platform>
-\endverbatim
+@endverbatim
+
+@subsection deploy_xml_process The process tag
+
+<process> starts a new actor on a given host. It specifies which
+function (from your application) gets executed on the host. Hence, the
+@c host and @c function attributes are mandatory, but this tag accepts
+some optional attributes too.
+
+| Attribute name | Mandatory | Values | Description |
+| --------------- | --------- | ------------ | ----------- |
+| host | yes | String | This must match the name of an host defined in the platform file. |
+| function | yes | String | Name of the function (from your own code) that will be executed. See @ref deploy_xml_functions. |
+| start_time | no | int | The simulated time when this actor will be started (Default: ASAP). |
+| kill_time | no | int | The simulated time when this actor will be forcefully stopped (Default: never). |
+| on_failure | no | DIE\|RESTART | What should be done when the process fails (Default: die). |
+
+@subsection deploy_xml_argument The argument tag
+
+This tag (which must be enclosed in a @c <process> tag) adds a
+new string to the parameter list received by your actor (either its @c
+argv array in MSG or its @c args vector in S4U). Naturally, the
+semantic of these parameters completely depend on your program.
+
+| Attribute name | Mandatory | Values | Description |
+| --------------- | --------- | ---------------------- | ----------- |
+| value | yes | String | Value of this parameter |
+
+@subsection deploy_xml_prop The prop tag
+
+This tag (which must be enclosed in a @c <process> tag) adds a
+new property to your actor.
+
+(either its @c
+argv array in MSG or its @c args vector in S4U). Naturally, the
+semantic of these parameters completely depend on your program.
+
+| Attribute name | Mandatory | Values | Description |
+| --------------- | --------- | ---------------------- | ----------- |
+| id | yes | String | Name of the defined property |
+| value | yes | String | Value of this property |
-\section process_tag Process
-There are optional attributes to the process tag, here is a list of all attributes of process:
+@subsection deploy_xml_functions Declaring startable functions
-\li <b>host (mandatory)</b>: the host on which the function will be executed.
-\li <b>process (mandatory)</b>: the process function that will be executed on that host. You can deploy as many process as you want on the same host.
-\li <b>start_time</b>: the (simulated) time when the function will start. Default is zero.
-\li <b>kill_time</b>: the (simulated) time when the function will stop. Default is when it's actually finishing.
+You need to connect your code to the names that you use in the XML
+deployment file. Depends on the interface you use, this is done with
+MSG_process_create() or simgrid::s4u::Engine::registerFunction().
+There is nothing to do in your **Java code** since SimGrid uses
+the Java introspection abilities to retrieve the classes from their
+names. In your XML file, you must then use the full class name
+(including the package name).
*/
