From 9d026a0f5fbecfb0a4ca1e3b740f55ddb3932092 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Tue, 2 Jul 2019 23:50:21 +0200 Subject: [PATCH] doc: Migrate Deploying_your_Application to RST --- ChangeLog | 1 + doc/doxygen/deployment.doc | 135 --------------------- docs/source/Deploying_your_Application.rst | 115 ++++++++++++++++++ docs/source/XML_Reference.rst | 4 +- docs/source/img/graphical-toc.svg | 16 +-- docs/source/index.rst | 1 + examples/s4u/README.rst | 1 + tools/cmake/DefinePackages.cmake | 2 +- 8 files changed, 130 insertions(+), 145 deletions(-) delete mode 100644 doc/doxygen/deployment.doc create mode 100644 docs/source/Deploying_your_Application.rst diff --git a/ChangeLog b/ChangeLog index 7659918a0b..a92e66e74f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -4,6 +4,7 @@ SimGrid (3.23.1) NOT RELEASED YET (v3.24 expected September 23. 7:50 UTC) Documentation: - Nicer introduction page. + - Migrate the "Deploy your application" page to the new doc. - Move Java as a subtree of MSG. General: diff --git a/doc/doxygen/deployment.doc b/doc/doxygen/deployment.doc deleted file mode 100644 index beee64f493..0000000000 --- a/doc/doxygen/deployment.doc +++ /dev/null @@ -1,135 +0,0 @@ -/*! @page deployment Deploy the simulation - -@tableofcontents - -\htmlonly -
-\endhtmlonly -\htmlinclude graphical-toc.svg -\htmlonly -
- -\endhtmlonly - -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_actors_start "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). - -*/ diff --git a/docs/source/Deploying_your_Application.rst b/docs/source/Deploying_your_Application.rst new file mode 100644 index 0000000000..525d7e3539 --- /dev/null +++ b/docs/source/Deploying_your_Application.rst @@ -0,0 +1,115 @@ +.. _deploy: + +Deploying your Application +========================== + +.. raw:: html + + + +
+
+ +There is several ways to deploy the :ref:`application ` you want to +study on your :ref:`simulated platform `, i.e. to specify which actor +should be started on which host. You can do so directly in your program (as +shown in :ref:`these examples `), or using an XML deployment +file. Unless you have a good reason, you should keep your application appart +from the deployment as it will :ref:`ease your experimental campain afterward +`. + +Deploying actors from XML is easy: it only involves 3 tags: :ref:`pf_tag_actor`, +:ref:`pf_tag_argument`, and :ref:`pf_tag_prop`. They must be placed in an +encompassing :ref:`pf_tag_platform`. Here is a first example (search in the +archive for files named ``???_d.xml`` for more): + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + +------------------------------------------------------------------------------- + +.. _pf_tag_actor: + + +-------- + +This tag starts a new actor executing the given function on a given host. + + +**Parent tags:** :ref:`pf_tag_platform` (only in deployment files) |br| +**Children tags:** :ref:`pf_tag_argument`, :ref:`pf_tag_prop` |br| +**Attributes:** + +:``host``: Host on which this actor should be started (mandatory). +:``function``: Code to execute. + + That function must be registered beforehand + with :cpp:func:`simgrid::s4u::Engine::register_actor` or + with :cpp:func:`simgrid::s4u::Engine::register_function`. + + If you are stuck with MSG, use :cpp:func:`MSG_process_create`, + :cpp:func:`MSG_process_create_with_arguments` or + :cpp:func:`MSG_process_create_with_environment`. + + There is nothing to do in Java, as SimGrid uses introspection abilities to + retrieve the classes from their names. You must then use the full class name + (including the package name) in your XML file. + +:``start_time``: Useful to delay the start of your actor. + + -1 starts the actor immediately. +:``kill_time``: Time at which the actor should be killed. + + -1 means that the actor should not be killed automatically. +:``on_failure``: What to do when the actor's host is turned off and back on. + + Either ``DIE`` (default -- don't restart the actor) or ``RESTART`` + +------------------------------------------------------------------------------- + +.. _pf_tag_argument: + + +---------- + +Add a parameter to the actor, to its args vector. Naturally, the semantic of +these parameters completely depend on your program. + + +**Parent tags:** :ref:`pf_tag_actor` |br| +**Children tags:** none |br| +**Attributes:** + +:``value``: The string to add to the actor's args vector. + +.. |br| raw:: html + +
diff --git a/docs/source/XML_Reference.rst b/docs/source/XML_Reference.rst index 87a71812be..694931905b 100644 --- a/docs/source/XML_Reference.rst +++ b/docs/source/XML_Reference.rst @@ -267,6 +267,7 @@ and a download link. :``id``: Name of the host. Must be unique on the whole platform. :``speed``: Computational power (in flop/s). + If you use DVFS, provide a comma-separated list of values for each pstate (see :ref:`howto_dvfs`). :``bw_in``: Bandwidth of the private downstream link, along with its unit. See :ref:`pf_tag_link`. @@ -298,7 +299,8 @@ and a download link. **Parent tags:** none (this is the root tag of every file) |br| **Children tags:** :ref:`pf_tag_config` (must come first), :ref:`pf_tag_cluster`, :ref:`pf_tag_cabinet`, :ref:`pf_tag_peer`, -:ref:`pf_tag_zone`, :ref:`pf_tag_trace`, :ref:`pf_tag_trace_connect` |br| +:ref:`pf_tag_zone`, :ref:`pf_tag_trace`, :ref:`pf_tag_trace_connect`, or +:ref:`pf_tag_actor` in :ref:`deployment ` files.|br| **Attributes:** :``version``: Version of the DTD, describing the whole XML format. diff --git a/docs/source/img/graphical-toc.svg b/docs/source/img/graphical-toc.svg index eead0aac53..83d6fe7558 100644 --- a/docs/source/img/graphical-toc.svg +++ b/docs/source/img/graphical-toc.svg @@ -25,8 +25,8 @@ inkscape:pageopacity="0.0" inkscape:pageshadow="2" inkscape:zoom="2.8" - inkscape:cx="205.77445" - inkscape:cy="161.83279" + inkscape:cx="24.34588" + inkscape:cy="160.40421" inkscape:document-units="mm" inkscape:current-layer="layer1" showgrid="true" @@ -2300,7 +2300,7 @@ image/svg+xml - + @@ -6208,7 +6208,7 @@ id="tspan2827" /> @@ -6453,17 +6453,17 @@ MPI Legacy CodeReal MPI Code diff --git a/docs/source/index.rst b/docs/source/index.rst index 91da4d3c0f..023bb91c4a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -79,6 +79,7 @@ of every page. Bugs in the code should be reported    XML Reference Describing the Experimental Setup    Configuring SimGrid +    Deploying your Application The SimGrid Models    ns-3 as a SimGrid model Simulation Outcomes diff --git a/examples/s4u/README.rst b/examples/s4u/README.rst index f11fc88fc1..e332ab6783 100644 --- a/examples/s4u/README.rst +++ b/examples/s4u/README.rst @@ -31,6 +31,7 @@ to simulate. Actors: the Active Entities =========================== +.. _s4u_ex_actors: Starting and Stoping Actors --------------------------- diff --git a/tools/cmake/DefinePackages.cmake b/tools/cmake/DefinePackages.cmake index bbffae4702..903bafc148 100644 --- a/tools/cmake/DefinePackages.cmake +++ b/tools/cmake/DefinePackages.cmake @@ -836,7 +836,6 @@ set(DOC_SOURCES doc/Layout.xml doc/doxygen/FAQ.doc - doc/doxygen/deployment.doc doc/doxygen/inside.doc doc/doxygen/inside_tests.doc doc/doxygen/inside_cmake.doc @@ -895,6 +894,7 @@ set(DOC_SOURCES docs/source/app_smpi.rst docs/source/community.rst docs/source/Configuring_SimGrid.rst + doc/doxygen/Deploying_your_Application.rst docs/source/Experimental_Setup.rst docs/source/index.rst docs/source/Introduction.rst -- 2.20.1