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" 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. Either way, it is a good habit to keep your application apart
  23 from the deployment as it will :ref:`ease your experimental campaign 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 retrieve 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 :``start_time``: Useful to delay the start of your actor.
  80
  81          -1 starts the actor immediately.
  82 :``kill_time``:  Time at which the actor should be killed.
  83
  84    -1 means that the actor should not be killed automatically.
  85 :``on_failure``: What to do when the actor's host is turned off and back on.
  86
  87    Either ``DIE`` (default -- don't restart the actor) or ``RESTART``
  88
  89 -------------------------------------------------------------------------------
  90
  91 .. _pf_tag_argument:
  92
  93 <argument>
  94 ----------
  95
  96 Add a parameter to the actor, to its args vector. Naturally, the semantic of
  97 these parameters completely depend on your program.
  98
  99
 100 **Parent tags:** :ref:`pf_tag_actor`  |br|
 101 **Children tags:** none |br|
 102 **Attributes:**
 103
 104 :``value``: The string to add to the actor's args vector.
 105
 106 .. |br| raw:: html
 107
 108    <br />