doc/doxygen/deployment.doc

   1 /*! @page deployment Deploy the simulation
   2
   3 Once you've specified your @ref platform "virtual platform" and the
   4 @ref application "application" you want to study, you must describe
   5 the mapping of the application onto the platform. This page says how
   6 to do that if you go for online simulation (that is, the study of a
   7 program), you must say which code starts on which host, with which
   8 parameters. You can also go for offline simulation, i.e. the study of
   9 a trace captured from a past applicative run, as briefly explained
  10 @ref XBT_replay "here".
  11
  12 There is two ways to specify the mapping of your program onto virtual
  13 hosts: either directly from your program (with @ref MSG_process_create
  14 or as in @ref s4u_ex_basics "this S4U example"), or using an external
  15 XML file.  You should really logically separate your application from
  16 the deployment, as it will ease your experimental campain afterward.
  17 How exactly you organize your work remains up to you.
  18
  19 @section deploy_s4u
  20
  21 The following example shows the several ways of doing so in the S4U
  22 interface: @ref examples/s4u/actor-create/s4u_actor-create.cpp.
  23 Associated XML file: @ref examples/s4u/actor-create/s4u_actor-create_d.xml
  24
  25 @section deploy_msg
  26
  27 If you're stuck with the MSG interface, then you should simply use one
  28 of the following functions to start new actors onto your virtual
  29 hosts: @ref MSG_process_create, @ref MSG_process_create_with_arguments
  30 or @ref MSG_process_create_with_environment. These functions are used
  31 in many of the provided example, just grep for them.
  32
  33 @section deploy_xml
  34
  35 This section presents how to deploy from an XML file, as it is
  36 classically done. You will find a huge amount of examples of this in
  37 the @c examples directory.
  38
  39 The deployment file looks just like a @ref platform "platform" file, except that in
  40 this case, only two different tags are used: @c process and @c argument, whereas
  41 the latter is just used to supply additional configuration options to the process; the
  42 order in which the @c argument tags are given is important and depends on the application.
  43
  44 ### The process tag ###
  45
  46 #### Attribute list ####
  47
  48 As already written above, the @c process tag is the tag that defines which host
  49 executes which function (from your application). Hence, the @c host and @c function
  50 attributes are mandatory; however, there are some optional attributes to the process tag. Here is a list of all attributes of this tag:
  51
  52 | Attribute name  | Mandatory | Values                 | Description                                                                                                               |
  53 | --------------- | --------- | ---------------------- | -----------                                                                                                               |
  54 | host            | yes       | String                 | Describes which host will be used to run this process. The host must be defined in the platform file!                     |
  55 | function        | yes       | String                 | Name of a function that will be executed on this host; this function is written in userland code, for instance, C code. Valid values are functions that were registered by MSG_function_register() |
  56 | start_time      | no        | int (Default: -1.0)    | The simulated time when this function will start to be computed.                                                          |
  57 | kill_time       | no        | int (Default: -1.0)    | The simulated time when this function will end to be computed. By default, it stops only when it's done.                  |
  58 | on_failure      | no        | DIE\|RESTART (Default: "DIE")   | What should be done when the process fails.                  |
  59
  60 #### Examples ####
  61
  62 Almost any @ref msg_examples include a deployment file.
  63
  64 ### The argument tag ###
  65
  66 This tag must always be contained by a @c process tag - it doesn't make sense
  67 without it.
  68
  69 The way this works is that the order of arguments must be pre-defined <i>by the user</i>:
  70 It is totally up to you what <i>your</i> code expects as arguments and in which
  71 order. The arguments will be passed to your code (that is: to the function
  72 executed by this process) in the order you declare them.
  73
  74 #### Attribute list ####
  75
  76 | Attribute name  | Mandatory | Values                 | Description                                                                                                               |
  77 | --------------- | --------- | ---------------------- | -----------                                                                                                               |
  78 | value           | yes       | String                 | Contains the value for this parameter |
  79
  80 */