docs/source/Deploying_your_Application.rst

   1 .. _deploy:
   2
   3 Deploying your Application
   4 ==========================
   5
   6 .. raw:: html
   7
   8    <object id="TOC" data="graphical-toc.svg" width="100%" type="image/svg+xml"></object>
   9    <script>
  10    window.onload=function() { // Wait for the SVG to be loaded before changing it
  11      var elem=document.querySelector("#TOC").contentDocument.getElementById("DeployBox")
  12      elem.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    }
  14    </script>
  15    <br/>
  16    <br/>
  17
  18 There is several ways to deploy the :ref:`application <application>` you want to
  19 study on your :ref:`simulated platform <platform>`, i.e. to specify which actor
  20 should be started on which host. You can do so directly in your program (as
  21 shown in :ref:`these examples <s4u_ex_actors>`), or using an XML deployment
  22 file. Unless you have a good reason, you should keep your application appart
  23 from the deployment as it will :ref:`ease your experimental campain afterward
  24 <howto_science>`.
  25
  26 Deploying actors from XML is easy: it only involves 3 tags: :ref:`pf_tag_actor`,
  27 :ref:`pf_tag_argument`, and :ref:`pf_tag_prop`. They must be placed in an
  28 encompassing :ref:`pf_tag_platform`. Here is a first example (search in the
  29 archive for files named ``???_d.xml`` for more):
  30
  31 .. code-block:: xml
  32
  33    <?xml version='1.0'?>
  34    <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
  35    <platform version="4.1">
  36      <!-- The following starts an actor that runs the function `alice()` on the given host.
  37        -- It is not given any parameter, so its args is empty.
  38        -->
  39      <actor host="host1" function="alice" />
  40
  41      <!-- The following starts another actor that runs `bob()` on host2.
  42        -- The args of this actor contains "3" and "3000" on creation.
  43        -->
  44      <actor host="host2" function="bob" />
  45        <argument value="3"/>
  46        <argument value="3000"/>
  47      </actor>
  48
  49      <!-- Carole runs on 'host3', has 1 parameter "42" in its argv and one property.
  50        -- Use simgrid::s4u::Actor::get_property() to retrive it.-->
  51      <actor host="host3" function="carol">
  52        <argument value="42"/>
  53        <prop id="SomeProp" value="SomeValue"/>
  54      </actor>
  55    </platform>
  56
  57
  58 -------------------------------------------------------------------------------
  59
  60 .. _pf_tag_actor:
  61
  62 <actor>
  63 --------
  64
  65 This tag starts a new actor executing the given function on a given host.
  66
  67
  68 **Parent tags:** :ref:`pf_tag_platform` (only in deployment files) |br|
  69 **Children tags:** :ref:`pf_tag_argument`, :ref:`pf_tag_prop` |br|
  70 **Attributes:**
  71
  72 :``host``: Host on which this actor should be started (mandatory).
  73 :``function``: Code to execute.
  74
  75    That function must be registered beforehand
  76    with :cpp:func:`simgrid::s4u::Engine::register_actor` or
  77    with :cpp:func:`simgrid::s4u::Engine::register_function`.
  78
  79    If you are stuck with MSG, use :cpp:func:`MSG_process_create`,
  80    :cpp:func:`MSG_process_create_with_arguments` or
  81    :cpp:func:`MSG_process_create_with_environment`.
  82
  83    There is nothing to do in Java, as SimGrid uses introspection abilities to
  84    retrieve the classes from their names. You must then use the full class name
  85    (including the package name) in your XML file.
  86
  87 :``start_time``: Useful to delay the start of your actor.
  88
  89          -1 starts the actor immediately.
  90 :``kill_time``:  Time at which the actor should be killed.
  91
  92    -1 means that the actor should not be killed automatically.
  93 :``on_failure``: What to do when the actor's host is turned off and back on.
  94
  95    Either ``DIE`` (default -- don't restart the actor) or ``RESTART``
  96
  97 -------------------------------------------------------------------------------
  98
  99 .. _pf_tag_argument:
 100
 101 <argument>
 102 ----------
 103
 104 Add a parameter to the actor, to its args vector. Naturally, the semantic of
 105 these parameters completely depend on your program.
 106
 107
 108 **Parent tags:** :ref:`pf_tag_actor`  |br|
 109 **Children tags:** none |br|
 110 **Attributes:**
 111
 112 :``value``: The string to add to the actor's args vector.
 113
 114 .. |br| raw:: html
 115
 116    <br />