From: Martin Quinson Date: Tue, 13 Dec 2016 10:23:10 +0000 (+0100) Subject: start reformating the manual for the AS -> NetZone transition (ignorable changes) X-Git-Tag: v3_14~56 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/dfe09e5c06ea550bdd21bc6ec3ea1a26d58569ec start reformating the manual for the AS -> NetZone transition (ignorable changes) --- diff --git a/doc/doxygen/application.doc b/doc/doxygen/application.doc index d95ea26f00..a1830815bb 100644 --- a/doc/doxygen/application.doc +++ b/doc/doxygen/application.doc @@ -18,8 +18,8 @@ TBD Virtual Platform (link), but your application have many other ways to interact with the resource. - - The resources are arranged in a hierarchy of *Autonomous Systems*, - with which the application can also interact. The AS knows the + - The resources are arranged in a hierarchy of *Networking Zones*, + with which the application can also interact. The netzone knows the networking path between one resource to another. Speak of mailboxes here? Where if not? diff --git a/doc/doxygen/deployment.doc b/doc/doxygen/deployment.doc index d4d46139e1..38700708ca 100644 --- a/doc/doxygen/deployment.doc +++ b/doc/doxygen/deployment.doc @@ -20,7 +20,7 @@ order in which the @c argument tags are given is important and depends on the ap #### Attribute list #### -%As already written above, the @c process tag is the tag that defines which host +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: diff --git a/doc/doxygen/examples.doc b/doc/doxygen/examples.doc index fa63cedfdb..8718864768 100644 --- a/doc/doxygen/examples.doc +++ b/doc/doxygen/examples.doc @@ -133,7 +133,7 @@ an external description of the deployment. \paragraph MSG_ext_async_Sender Sender function -A host can send an asynchronous message with \c MSG_task_isend(). %As this function is non-blocking, we have to call +A host can send an asynchronous message with \c MSG_task_isend(). As this function is non-blocking, we have to call \c MSG_comm_test() to know if the communication is complete and evenetually destroy it with a call to \c MSG_comm_destroy(). It is also possible to call \c MSG_comm_wait() which provides a shortcut. @@ -150,7 +150,7 @@ A host can send an asynchronous message with \c MSG_task_isend(). %As this funct \paragraph MSG_ext_async_Receiver Receiver function -This function executes tasks when it receives them. %As the receiving is asynchronous, we have to test the completion of +This function executes tasks when it receives them. As the receiving is asynchronous, we have to test the completion of the communication with \c MSG_comm_test() or wait for it with \c MSG_comm_wait(). C style arguments (argc/argv) are interpreted as: diff --git a/doc/doxygen/module-smpi.doc b/doc/doxygen/module-smpi.doc index 83c04692a6..5d4f2ae63f 100644 --- a/doc/doxygen/module-smpi.doc +++ b/doc/doxygen/module-smpi.doc @@ -485,7 +485,7 @@ SimGrid can duplicate and dynamically switch the .data and .bss segments of the ELF process when switching the MPI ranks, allowing each ranks to have its own copy of the global variables. This feature is expected to work correctly on Linux and BSD, so smpirun activates -it by default. %As no copy is involved, performance should not be +it by default. As no copy is involved, performance should not be altered (but memory occupation will be higher). If you want to turn it off, pass \c -no-privatize to smpirun. This may diff --git a/doc/doxygen/options.doc b/doc/doxygen/options.doc index 16cd1a32ba..1cfd2df4c1 100644 --- a/doc/doxygen/options.doc +++ b/doc/doxygen/options.doc @@ -82,7 +82,7 @@ should provide information about all models for all existing resources. - \b storage/model: specify the used storage model (there is currently only one such model - this option is hence only useful for future releases) - \b vm/model: specify the model for virtual machines (there is currently only one such model - this option is hence only useful for future releases) -%As of writing, the following network models are accepted. Over +As of writing, the following network models are accepted. Over the time new models can be added, and some experimental models can be removed; check the values on your simulators for an uptodate information. Note that the CM02 model is described in the research report @@ -249,7 +249,7 @@ deployment of processes on nodes. \subsubsection options_model_network_crosstraffic Simulating cross-traffic -%As of SimGrid v3.7, cross-traffic effects can be taken into account in +As of SimGrid v3.7, cross-traffic effects can be taken into account in analytical simulations. It means that ongoing and incoming communication flows are treated independently. In addition, the LV08 model adds 0.05 of usage on the opposite direction for each new @@ -978,7 +978,7 @@ following cost inside MPI_Send: 5+11*1 \endverbatim -%As 5 is the startup cost and 1 is the cost per byte. +As 5 is the startup cost and 1 is the cost per byte. \note The order of sections can be arbitrary; they will be ordered internally. diff --git a/doc/doxygen/outcomes_logs.doc b/doc/doxygen/outcomes_logs.doc index 669b0e672b..d369083d77 100644 --- a/doc/doxygen/outcomes_logs.doc +++ b/doc/doxygen/outcomes_logs.doc @@ -4,7 +4,7 @@ Using @c printf or @c println to display information is possible, but quickly unpractical, as the logs of all processes get intermixed in -your program's output. %As an answer, the SimGrid logging module allow +your program's output. As an answer, the SimGrid logging module allow you to sort and filter the logs by emitter, by module and by gravity level. diff --git a/doc/doxygen/outcomes_vizu.doc b/doc/doxygen/outcomes_vizu.doc index d8cecd86b5..d8a7ad3267 100644 --- a/doc/doxygen/outcomes_vizu.doc +++ b/doc/doxygen/outcomes_vizu.doc @@ -239,7 +239,7 @@ This option changes the way SimGrid register its platform on the trace file. Normally, the tracing considers all routes (no matter their size) on the platform file to re-create the resource topology. If this option is activated, only the routes with one link are used to -register the topology within an AS. Routes among AS continue to be +register the topology within a netzone. Routes among netzones continue to be traced as usual. \verbatim --cfg=tracing/onelink-only:yes @@ -504,7 +504,7 @@ the beggining and size of the time slice. \subsubsection tracing_viva_graph Hierarchical Graph View -%As stated above (see section \ref tracing_tracing_analyzing), one +As stated above (see section \ref tracing_tracing_analyzing), one possibility to analyze SimGrid traces is to use Viva's graph view with a graph configuration to customize the graph according to the traces. A valid graph configuration (we are using the non-XML Autonomous System (AS), while at the lower level it is named -sub-network, or LAN (local area network). -They are indeed autonomous: routing is defined -(within the limits of his network) by the administrator, and so, those -networks can operate without a connection to other -networks. So-called gateways allow you to go from one network to -another, if such a (physical) connection exists. Every node in one network -that can be directly reached (i.e., without traversing other nodes) from -another network is called a gateway. -Each autonomous system consists of equipment such as cables (network links), -routers and switches as well as computers. - -The structure of the SimGrid platform description relies exactly on the same -concept as a real-life platform (see above). Every resource (computers, -network equipment etc.) belongs to an AS, which can be defined by using the -\ tag. Within an AS, the routing between its elements can be defined -abitrarily. There are several modes for routing, and exactly one mode must be -selected by specifying the routing attribute in the AS tag: +networks, possibly even in other locations. At the upper level, such a +network is called Autonomous System (AS), while at the lower +level it is named sub-network, or LAN (local area network). They are +indeed autonomous: routing is defined (within the limits of his +network) by the administrator, and so, those networks can operate +without a connection to other networks. So-called gateways allow you +to go from one network to another, if such a (physical) connection +exists. Every node in one network that can be directly reached (i.e., +without traversing other nodes) from another network is called a +gateway. Each autonomous system consists of equipment such as cables +(network links), routers and switches as well as computers. + +The structure of the SimGrid platform description relies exactly on +the same concept as a real-life platform (see above). Every resource +(computers, network equipment etc.) belongs to an AS, which can be +defined by using the \ tag. Within an AS, the routing between its +elements can be defined abitrarily. There are several modes for +routing, and exactly one mode must be selected by specifying the +routing attribute in the AS tag: \verbatim @@ -69,18 +68,19 @@ selected by specifying the routing attribute in the AS tag: Other supported values for the routing attribute can be found below, Section \ref pf_raf. -There is also the ```` tag; this tag takes two attributes, ``src`` (source) -and ``dst`` (destination). Both source and destination must be valid identifiers -for routers (these will be introduced later). Contained by the ```` are -network links; these links must be used in order to communicate from the source -to the destination specified in the tag. Hence, a route merely describes +There is also the ```` tag; this tag takes two attributes, +``src`` (source) and ``dst`` (destination). Both source and +destination must be valid identifiers for routers (these will be +introduced later). Contained by the ```` are network links; +these links must be used in order to communicate from the source to +the destination specified in the tag. Hence, a route merely describes how to reach a router from another router. \remark More information and (code-)examples can be found in Section \ref pf_rm. -An AS can also contain itself one or more AS; this allows you to -model the hierarchy of your platform. +An AS can also contain itself one or more AS; this allows you to model +the hierarchy of your platform. ### Within each AS, the following types of resources exist: @@ -92,14 +92,15 @@ router | \ref pf_router | In SimGrid, routers are used to provid link | \ref pf_link | In SimGrid, (network)links define a connection between two or potentially even more resources. Every link has a bandwidth and a latency and may potentially experience congestion. cluster | \ref pf_cluster | In SimGrid, clusters were introduced to model large and homogenous environments. They are not really a resource by themselves - technically, they are only a shortcut, as they will internally set up all the hosts, network and routing for you, i.e., using this resource, one can easily setup thousands of hosts and links in a few lines of code. Each cluster is itself an AS. -%As it is desirable to interconnect these resources, a routing has to be -defined. The AS is supposed to be Autonomous, hence this has to be done at the -AS level. The AS handles two different types of entities (host/router -and AS). However, the user is responsible to define routes between those resources, -otherwise entities will be unconnected and therefore unreachable from other -entities. Although several routing algorithms are built into SimGrid (see -\ref pf_rm), you might encounter a case where you want to define routes -manually (for instance, due to specific requirements of your platform). +As it is desirable to interconnect these resources, a routing has to +be defined. The AS is supposed to be Autonomous, hence this has to be +done at the AS level. The AS handles two different types of entities +(host/router and AS). However, the user is responsible +to define routes between those resources, otherwise entities will be +unconnected and therefore unreachable from other entities. Although +several routing algorithms are built into SimGrid (see \ref pf_rm), +you might encounter a case where you want to define routes manually +(for instance, due to specific requirements of your platform). There are three tags to use: \li ASroute: to define routes between two AS @@ -502,7 +503,7 @@ several other tags that are available only in certain contexts. \subsubsection pf_router <router/> -%As said before, router is used only to give some information +As said before, router is used only to give some information for routing algorithms. So, it does not have any attributes except : #### Attributes #### @@ -1368,7 +1369,7 @@ A route in the \ref pf_routing_model_shortest_path "Shortest-Path routing model" \subsubsection pf_routing_tag_bypassasroute bypassASroute -%As said before, once you choose +As said before, once you choose a model, it (most likely; the constant network model, for example, doesn't) calculates routes for you. But maybe you want to define some of your routes, which will be specific. You may also want to bypass some routes defined in lower level AS at an upper stage: @@ -1405,7 +1406,7 @@ attribute was not given, this route is presumed to be symmetrical. \subsubsection pf_routing_tag_bypassroute bypassRoute -%As said before, once you choose +As said before, once you choose a model, it (most likely; the constant network model, for example, doesn't) calculates routes for you. But maybe you want to define some of your routes, which will be specific. You may also want to bypass some routes defined in lower level AS at an upper stage : @@ -1441,7 +1442,7 @@ and AS_2. If you want to make a host (h1) from AS_1 with another one (h2) from AS_2 then you'll have to proceed as follows: \li First, you have to ensure that a route is defined from h1 to the AS_1's exit gateway and from h2 to AS_2's exit gateway. -\li Then, you'll have to define a route between AS_1 to AS_2. %As those +\li Then, you'll have to define a route between AS_1 to AS_2. As those AS are both resources belonging to AS_Big, then it has to be done at AS_big level. To define such a route, you have to give the source AS (AS_1), the destination AS (AS_2), and their respective @@ -1451,18 +1452,18 @@ and AS_2. If you want to make a host (h1) from AS_1 with another one defined inside AS_Big. If you choose some shortest-path model, this route will be computed automatically. -%As said before, there are mainly 2 tags for routing : +As said before, there are mainly 2 tags for routing : \li ASroute: to define routes between two AS \li route: to define routes between two host/router -%As we are dealing with routes between AS, it means that those we'll +As we are dealing with routes between AS, it means that those we'll have some definition at AS_Big level. Let consider AS_1 contains 1 host, 1 link and one router and AS_2 3 hosts, 4 links and one router. There will be a central router, and a cross-like topology. At the end of the crosses arms, you'll find the 3 hosts and the router that will act as a gateway. We have to define routes inside those two AS. Let say that AS_1 contains full routes, and AS_2 contains some Floyd -routing (as we don't want to bother with defining all routes). %As +routing (as we don't want to bother with defining all routes). As we're using some shortest path algorithms to route into AS_2, we'll then have to define some route to gives some topological information to SimGrid. Here is a file doing it all : diff --git a/doc/doxygen/tutorial.doc b/doc/doxygen/tutorial.doc index 112c3eddfb..42a3bc5286 100644 --- a/doc/doxygen/tutorial.doc +++ b/doc/doxygen/tutorial.doc @@ -78,7 +78,7 @@ interesting questions: - Although an algorithm may be more efficient than another, how does it interfere with other applications? - %As you can see, this very simple setting may need to evolve way + As you can see, this very simple setting may need to evolve way beyond what you initially imagined.
Premature optimization is the root of all evil. -- D.E.Knuth
@@ -165,7 +165,7 @@ cd msg-tuto/src make ~~~~ -%As you can see, there is already a nice Makefile that compiles +As you can see, there is already a nice Makefile that compiles everything for you. Now the tiny example has been compiled and it can be easily run as follows: @@ -429,7 +429,7 @@ void xbt_dynar_shift(xbt_dynar_t const dynar, void *const dst); unsigned long xbt_dynar_length(const xbt_dynar_t dynar); ~~~~ -%As you will soon realize, with such simple mechanisms, simple +As you will soon realize, with such simple mechanisms, simple deadlocks will soon appear. They can easily be removed with a simple polling mechanism, hence the need for the following [function][fn:7]: @@ -438,7 +438,7 @@ simple polling mechanism, hence the need for the following msg_error_t MSG_process_sleep(double nb_sec); ~~~~ -%As you should quickly realize, on the simple previous example, it +As you should quickly realize, on the simple previous example, it will double the throughput of the platform but will be quite ineffective when input size of the tasks is not negligible anymore.