SimGrid  3.16
Versatile Simulation of Distributed Systems
Deploy the simulation

Once you've specified your virtual platform and the 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 here.

There is two ways to specify the mapping of your program onto virtual hosts: either directly from your program (with MSG_process_create or as in 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.

Deployment with S4U

The following example shows the several ways of doing so in the S4U interface: examples/s4u/actor-create/s4u_actor-create.cpp. Associated XML file: examples/s4u/actor-create/s4u_actor-create_d.xml

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: MSG_process_create, MSG_process_create_with_arguments or MSG_process_create_with_environment. These functions are used in many of the provided example, just grep for them.

Deployment with XML

Deploying actors 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 platform file, with only 3 tags used:

  • <actor> starts a new actor on a given host;
  • <argument> passes a given argument in the argv of an actor (the list of arguments is ordered);
  • <prop> adds a property to the actor.

Examples

To make them easy to find, almost all deployment files in the archive are named ***_d_xml.

<?xml version='1.0'?>
<!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 -->
  <actor host="host1" function="alice" />

  <!-- Bob, which runs on 'host2', has 2 parameters "3" and "3000" in its argv -->
  <actor host="host2" function="bob" />
     <argument value="3"/>
     <argument value="3000"/>
  </actor>

  <!-- Carole runs on 'host3', has 1 parameter "42" in its argv and one property -->
  <!-- See MSG_process_get_property_value() to retrieve this property -->
  <actor host="host3" function="carole">
      <argument value="42"/>
      <prop id="SomeProp" value="SomeValue"/>
  </actor>
</platform>

The actor tag

<actor> starts a new actor on a given host. It specifies which function (from your application) gets executed on the host. Hence, the host and 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 Declaring startable 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 actor fails (Default: die).

The argument tag

This tag (which must be enclosed in a <actor> tag) adds a new string to the parameter list received by your actor (either its argv array in MSG or its 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

The prop tag

This tag (which must be enclosed in a <actor> tag) adds a new property to your actor. You can retrieve these properties with MSG_process_get_property_value() or simgrid::s4u::Actor::property(). 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

Declaring startable functions

You need to connect your code to the names that you use in the XML deployment file. Depending 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).