doc/doxygen/deployment.doc

   1 /*! @page deployment Deploy the simulation
   2
   3 @tableofcontents
   4
   5 \htmlonly
   6 <div align="center">
   7 \endhtmlonly
   8 \htmlinclude graphical-toc.svg
   9 \htmlonly
  10 </div>
  11 <script>
  12 document.getElementById("Deployment").style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1;stroke:#000000;stroke-width:0.35277778;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1";
  13 </script>
  14 \endhtmlonly
  15
  16 Once you've specified your @ref platform "virtual platform" and the
  17 @ref application "application" you want to study, you must describe
  18 the mapping of the application onto the platform. This page says how
  19 to do that if you go for online simulation (that is, the study of a
  20 program), you must say which code starts on which host, with which
  21 parameters. You can also go for offline simulation, i.e. the study of
  22 a trace captured from a past applicative run, as briefly explained
  23 @ref XBT_replay "here".
  24
  25 There is two ways to specify the mapping of your program onto virtual
  26 hosts: either directly from your program (with @ref MSG_process_create
  27 or as in @ref s4u_ex_actors_start "this S4U example"), or using an external
  28 XML file.  You should really logically separate your application from
  29 the deployment, as it will ease your experimental campain afterward.
  30 How exactly you organize your work remains up to you.
  31
  32 @section deploy_s4u Deployment with S4U
  33
  34 The following example shows the several ways of doing so in the S4U
  35 interface: @ref examples/s4u/actor-create/s4u-actor-create.cpp.
  36 Associated XML file: @ref examples/s4u/actor-create/s4u-actor-create_d.xml
  37
  38 @section deploy_msg Deployment with MSG
  39
  40 If you're stuck with the MSG interface, then you should simply use one
  41 of the following functions to start new actors onto your virtual
  42 hosts: @ref MSG_process_create, @ref MSG_process_create_with_arguments
  43 or @ref MSG_process_create_with_environment. These functions are used
  44 in many of the provided example, just grep for them.
  45
  46 @section deploy_xml Deployment with XML
  47
  48 Deploying actors from XML is easy. This section presents a complete
  49 example and the reference guide of the involved tags.
  50
  51 The deployment file looks just like a @ref platform "platform" file,
  52 with only 3 tags used:
  53
  54   - @c &lt;actor&gt; starts a new actor on a given host;
  55   - @c &lt;argument&gt; passes a given argument in the argv of an actor
  56     (the list of arguments is ordered);
  57   - @c &lt;prop&gt; adds a property to the actor.
  58
  59 @subsection deploy_xml_ex Examples
  60
  61 To make them easy to find, almost all deployment files in the archive
  62 are named @c ***_d_xml.
  63
  64 @verbatim
  65 <?xml version='1.0'?>
  66 <!DOCTYPE platform SYSTEM "http://simgrid.gforge.inria.fr/simgrid/simgrid.dtd">
  67 <platform version="4">
  68   <!-- Alice, which runs on the machine named 'host1', does not take any parameter -->
  69   <actor host="host1" function="alice" />
  70
  71   <!-- Bob, which runs on 'host2', has 2 parameters "3" and "3000" in its argv -->
  72   <actor host="host2" function="bob" />
  73      <argument value="3"/>
  74      <argument value="3000"/>
  75   </actor>
  76
  77   <!-- Carole runs on 'host3', has 1 parameter "42" in its argv and one property -->
  78   <!-- See MSG_process_get_property_value() to retrieve this property -->
  79   <actor host="host3" function="carole">
  80       <argument value="42"/>
  81       <prop id="SomeProp" value="SomeValue"/>
  82   </actor>
  83 </platform>
  84 @endverbatim
  85
  86 @subsection deploy_xml_actor The actor tag
  87
  88 &lt;actor&gt; starts a new actor on a given host. It specifies which
  89 function (from your application) gets executed on the host. Hence, the
  90 @c host and @c function attributes are mandatory, but this tag accepts
  91 some optional attributes too.
  92
  93 | Attribute name  | Mandatory | Values       | Description                                                                     |
  94 | --------------- | --------- | ------------ | -----------                                                                     |
  95 | host            | yes       | String       | This must match the name of an host defined in the platform file.               |
  96 | function        | yes       | String       | Name of the function (from your own code) that will be executed.  See @ref deploy_xml_functions. |
  97 | start_time      | no        | int          | The simulated time when this actor will be started (Default: ASAP).             |
  98 | kill_time       | no        | int          | The simulated time when this actor will be forcefully stopped (Default: never). |
  99 | on_failure      | no        | DIE\|RESTART | What should be done when the actor fails (Default: die).       |
 100
 101 @subsection deploy_xml_argument The argument tag
 102
 103 This tag (which must be enclosed in a @c &lt;actor&gt; tag) adds a
 104 new string to the parameter list received by your actor (either its @c
 105 argv array in MSG or its @c args vector in S4U).  Naturally, the
 106 semantic of these parameters completely depend on your program.
 107
 108 | Attribute name  | Mandatory | Values                 | Description             |
 109 | --------------- | --------- | ---------------------- | -----------             |
 110 | value           | yes       | String                 | Value of this parameter |
 111
 112 @subsection deploy_xml_prop The prop tag
 113
 114 This tag (which must be enclosed in a @c &lt;actor&gt; tag) adds a new
 115 property to your actor. You can retrieve these properties with
 116 MSG_process_get_property_value() or simgrid::s4u::Actor::property().
 117 Naturally, the semantic of these parameters completely depend on your
 118 program.
 119
 120 | Attribute name  | Mandatory | Values                 | Description                  |
 121 | --------------- | --------- | ---------------------- | -----------                  |
 122 | id              | yes       | String                 | Name of the defined property |
 123 | value           | yes       | String                 | Value of this property       |
 124
 125 @subsection deploy_xml_functions Declaring startable functions
 126
 127 You need to connect your code to the names that you use in the XML
 128 deployment file. Depending on the interface you use, this is done with
 129 MSG_process_create() or simgrid::s4u::Engine::registerFunction().
 130 There is nothing to do in your **Java code** since SimGrid uses
 131 the Java introspection abilities to retrieve the classes from their
 132 names. In your XML file, you must then use the full class name
 133 (including the package name).
 134
 135 */