X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/d89d9da3b19df5523db58584607c0c6a2859d7ab..3fb312ce54ba8cfa3f14bba64aa5f5a6f0299970:/doc/doxygen/deployment.doc
diff --git a/doc/doxygen/deployment.doc b/doc/doxygen/deployment.doc
index 7168ff3a65..b4d96cad94 100644
--- a/doc/doxygen/deployment.doc
+++ b/doc/doxygen/deployment.doc
@@ -1,67 +1,124 @@
/*! @page deployment Deploy the simulation
-@section dep_over Overview
-
-When you want to simulate the behavior of your code with SimGrid, you need
-to tell SimGrid exactly what code (that you wrote) is supposed to be run by which host - so you need to assign
-processes/functions to hosts. The hosts in question here are the hosts of your platform model; see Section @ref platform for details on how to set one up.
-
-This assignment of the form @c code -> @c host is what the deployment file is all about, which will
-be discussed briefly here.
-
-@note
- You can bypass the deployment file by hardcoding it in your user code, at least when you're using
- MSG.
-
-The deployment file looks just like a @ref platform "platform" file, except that in
-this case, only two different tags are used: @c process and @c argument, whereas
-the latter is just used to supply additional configuration options to the process; the
-order in which the @c argument tags are given is important and depends on the application.
-
-### The process tag ###
-
-#### Attribute list ####
-
-%As already written above, the @c process tag is the tag that defines which host
-executes which function (from your application). Hence, the @c host and @c function
-attributes are mandatory; however, there are some optional attributes to the process tag. Here is a list of all attributes of this tag:
-
-| Attribute name | Mandatory | Values | Description |
-| --------------- | --------- | ---------------------- | ----------- |
-| host | yes | String | Describes which host will be used to run this process. The host must be defined in the platform file! |
-| 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() |
-| start_time | no | int (Default: -1.0) | The simulated time when this function will start to be computed. |
-| 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. |
-| on_failure | no | DIE\|RESTART (Default: "DIE") | What should be done when the process fails. |
-
-#### An example ####
-
-A complete example including a @ref MSG_ext_ms_application "deployment file" can be found
-in the Section @ref msg_ex_basics "MSG basics".
-
-See also files such as @c examples/msg/masterslave/deployment_masterslave.xml.
-
-### The argument tag ###
-
-This tag must always be contained by a @c process tag - it doesn't make sense
-without it.
-
-The way this works is that the order of arguments must be pre-defined by the user:
-It is totally up to you what your code expects as arguments and in which
-order. The arguments will be passed to your code (that is: to the function
-executed by this process) in the order you declare them.
-
-#### Attribute list ####
-
-| Attribute name | Mandatory | Values | Description |
-| --------------- | --------- | ---------------------- | ----------- |
-| value | yes | String | Contains the value for this parameter |
-
-#### An example ####
-
-A complete example including a @ref MSG_ext_ms_application "deployment file" can be found
-in the Section @ref msg_ex_basics "MSG basics".
-
-See also files such as @c examples/msg/masterslave/deployment_masterslave.xml.
+@tableofcontents
+
+Once you've specified your @ref platform "virtual platform" and the
+@ref application "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
+@ref XBT_replay "here".
+
+There is two ways to specify the mapping of your program onto virtual
+hosts: either directly from your program (with @ref MSG_process_create
+or as in @ref s4u_ex_basics "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.
+
+@section deploy_s4u Deployment with S4U
+
+The following example shows the several ways of doing so in the S4U
+interface: @ref examples/s4u/actor-create/s4u_actor-create.cpp.
+Associated XML file: @ref examples/s4u/actor-create/s4u_actor-create_d.xml
+
+@section deploy_msg 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: @ref MSG_process_create, @ref MSG_process_create_with_arguments
+or @ref MSG_process_create_with_environment. These functions are used
+in many of the provided example, just grep for them.
+
+@section deploy_xml 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 @ref platform "platform" file,
+with only 3 tags used:
+
+ - @c <actor> starts a new actor on a given host;
+ - @c <argument> passes a given argument in the argv of an actor
+ (the list of arguments is ordered);
+ - @c <prop> adds a property to the actor.
+
+@subsection deploy_xml_ex Examples
+
+To make them easy to find, almost all deployment files in the archive
+are named @c ***_d_xml.
+
+@verbatim
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+@endverbatim
+
+@subsection deploy_xml_actor 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
+@c host and @c 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 @ref deploy_xml_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). |
+
+@subsection deploy_xml_argument The argument tag
+
+This tag (which must be enclosed in a @c <actor> tag) adds a
+new string to the parameter list received by your actor (either its @c
+argv array in MSG or its @c 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 |
+
+@subsection deploy_xml_prop The prop tag
+
+This tag (which must be enclosed in a @c <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 |
+
+@subsection deploy_xml_functions 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).
*/