- Change the introduction on Routing to make it more self-contained.
- Move the Routing part to a specific page, as it's an advanced topic about platforms.
- Fix the formating of some examples
- Fix the formating of \beginrst blocks in doxygen
- Document the <disk> tag a bit, as well as the filesystem plugin
- Remove the doc about storage from the doxygen doc to be converted
- Document Engine with autodoxy
- Document the C API of Engine and Actor
- Teach autodoxy to produce the doc of C functions (that don't have '::' in their name)
- Teach find_missing to rant about undocumented C functions
@ref msg_file ; access functions are organized as a POSIX-like
interface.
-@subsubsection pf_sto_conc Storage - Main Concepts
-
-The storage facilities implemented in SimGrid help to model (and account for)
-storage devices, such as tapes, hard-drives, CD or DVD devices etc.
-A typical situation is depicted in the figure below:
-
-@image html ./webcruft/storage_sample_scenario.png
-@image latex ./webcruft/storage_sample_scenario.png "storage_sample_scenario" width=@textwidth
-
-In this figure, two hosts called Bob and Alice are interconnected via a network
-and each host is physically attached to a disk; it is not only possible for each host to
-mount the disk they are attached to directly, but they can also mount disks
-that are in a remote location. In this example, Bob mounts Alice's disk remotely
-and accesses the storage via the network.
-
-SimGrid provides 3 different entities that can be used to model setups
-that include storage facilities:
-
-Entity name | Description
---------------- | -----------
-@ref pf_storage_entity_storage_type "storage_type" | Defines a template for a particular kind of storage (such as a hard-drive) and specifies important features of the storage, such as capacity, performance (read/write), contents, ... Different models of hard-drives use different storage_types (because the difference between an SSD and an HDD does matter), as they differ in some specifications (e.g., different sizes or read/write performance).
-@ref pf_tag_storage "storage" | Defines an actual instance of a storage type (disk, RAM, ...); uses a ``storage_type`` template (see line above) so that you don't need to re-specify the same details over and over again.
-@ref pf_tag_mount "mount" | Must be wrapped by a @ref pf_tag_host tag; declares which storage(s) this host has mounted and where (i.e., the mountpoint).
-
-
-@anchor pf_storage_content_file
-### %Storage Content File ###
-
-In order to assess exactly how much time is spent reading from the storage,
-SimGrid needs to know what is stored on the storage device (identified by distinct (file-)name, like in a file system)
-and what size this content has.
-
-@note
- The content file is never changed by the simulation; it is parsed once
- per simulation and kept in memory afterwards. When the content of the
- storage changes, only the internal SimGrid data structures change.
-
-@anchor pf_storage_content_file_structure
-#### Structure of a %Storage Content File ####
-
-Here is an excerpt from two storage content file; if you want to see the whole file, check
-the file ``examples/platforms/content/storage_content.txt`` that comes with the
-SimGrid source code.
-
-SimGrid essentially supports two different formats: UNIX-style filepaths should
-follow the well known format:
-
-@verbatim
-/lib/libsimgrid.so.3.6.2 12710497
-/bin/smpicc 918
-/bin/smpirun 7292
-/bin/smpif2c 1990
-/bin/simgrid_update_xml 5018
-/bin/graphicator 66986
-/bin/simgrid-colorizer 2993
-/bin/smpiff 820
-/bin/tesh 356434
-@endverbatim
-
-Windows filepaths, unsurprisingly, use the windows style:
-
-@verbatim
-@Windows@avastSS.scr 41664
-@Windows@bfsvc.exe 75264
-@Windows@bootstat.dat 67584
-@Windows@CoreSingleLanguage.xml 31497
-@Windows@csup.txt 12
-@Windows@dchcfg64.exe 335464
-@Windows@dcmdev64.exe 93288
-@endverbatim
-
-@note
- The different file formats come at a cost; in version 3.12 (and most likely
- in later versions, too), copying files from windows-style storages to unix-style
- storages (and vice versa) is not supported.
-
-@anchor pf_storage_content_file_create
-#### Generate a %Storage Content File ####
-
-If you want to generate a storage content file based on your own filesystem (or at least a filesystem you have access to),
-try running this command (works only on unix systems):
-
-@verbatim
-find . -type f -exec ls -1s --block=1 {} @; 2>/dev/null | awk '{ print $2 " " $1}' > ./content.txt
-@endverbatim
-
-@subsubsection pf_storage_entities The Storage Entities
-
-These are the entities that you can use in your platform files to include
-storage in your model. See also the list of our @ref pf_storage_example_files "example files";
-these might also help you to get started.
-
-@anchor pf_storage_entity_storage_type
-#### @<storage_type@> ####
-
-Attribute name | Mandatory | Values | Description
---------------- | --------- | ------ | -----------
-id | yes | string | Identifier of this storage_type; used when referring to it
-model | no | string | In the future, this will allow one to change the performance model to use
-size | yes | string | Specifies the amount of available storage space; you can specify storage like "500GiB" or "500GB" if you want. (TODO add a link to all the available abbreviations)
-content | yes | string | Path to a @ref pf_storage_content_file "Storage Content File" on your system. This file must exist.
-
-This tag must contain some predefined model properties, specified via the <model_prop> tag. Here is a list,
-see below for an example:
-
-Property id | Mandatory | Values | Description
---------------- | --------- | ------ | -----------
-Bwrite | yes | string | Bandwidth for write access; in B/s (but you can also specify e.g. "30MBps")
-Bread | yes | string | Bandwidth for read access; in B/s (but you can also specify e.g. "30MBps")
-
-@note
- A storage_type can also contain the <b><prop></b> tag. The <prop> tag allows you
- to associate additional information to this <storage_type> and follows the
- attribute/value schema; see the example below. You may want to use it to give information to
- the tool you use for rendering your simulation, for example.
-
-Here is a complete example for the ``storage_type`` tag:
-@verbatim
-<storage_type id="single_HDD" size="4000">
- <model_prop id="Bwrite" value="30MBps" />
- <model_prop id="Bread" value="100MBps" />
- <prop id="Brand" value="Western Digital" />
-</storage_type>
-@endverbatim
-
-@subsubsection pf_tag_storage <storage>
-
-Attributes | Mandatory | Values | Description
--------------- | --------- | ------ | -----------
-id | yes | string | Identifier of this ``storage``; used when referring to it
-typeId | yes | string | Here you need to refer to an already existing @ref pf_storage_entity_storage_type "@<storage_type@>"; the storage entity defined by this tag will then inherit the properties defined there.
-attach | yes | string | Name of a host (see Section @ref pf_tag_host) to which this storage is <i>physically</i> attached to (e.g., a hard drive in a computer)
-content | no | string | When specified, overwrites the content attribute of @ref pf_storage_entity_storage_type "@<storage_type@>"
-
-Here are two examples:
-
-@verbatim
- <storage id="Disk1" typeId="single_HDD" attach="bob" />
-
- <storage id="Disk2" typeId="single_SSD"
- content="content/win_storage_content.txt" />
-@endverbatim
-
-The first example is straightforward: A disk is defined and called "Disk1"; it is
-of type "single_HDD" (shown as an example of @ref pf_storage_entity_storage_type "@<storage_type@>" above) and attached
-to a host called "bob" (the definition of this host is omitted here).
-
-The second storage is called "Disk2", is still of the same type as Disk1 but
-now specifies a new content file (so the contents will be different from Disk1)
-and the filesystem uses the windows style; finally, it is attached to a second host,
-called alice (which is again not defined here).
-
-@subsubsection pf_tag_mount <mount>
-
-| Attribute | Mandatory | Values | Description |
-| ----------- | ----------- | -------- | ------------- |
-| id | yes | string | Refers to a @ref pf_tag_storage "<storage>" entity that will be mounted on that computer |
-| name | yes | string | Path/location to/of the logical reference (mount point) of this disk
-
-This tag must be enclosed by a @ref pf_tag_host tag. It then specifies where the mountpoint of a given storage device (defined by the ``id`` attribute)
-is; this location is specified by the ``name`` attribute.
-
-Here is a simple example, taken from the file ``examples/platform/storage.xml``:
-
-@verbatim
- <storage_type id="single_SSD" size="500GiB">
- <model_prop id="Bwrite" value="60MBps" />
- <model_prop id="Bread" value="200MBps" />
- </storage_type>
-
- <storage id="Disk2" typeId="single_SSD"
- content="content/win_storage_content.txt"
- attach="alice" />
- <storage id="Disk4" typeId="single_SSD"
- content="content/small_content.txt"
- attach="denise"/>
-
- <host id="alice" speed="1Gf">
- <mount storageId="Disk2" name="c:"/>
- </host>
-
- <host id="denise" speed="1Gf">
- <mount storageId="Disk2" name="c:"/>
- <mount storageId="Disk4" name="/home"/>
- </host>
-@endverbatim
-
-This example is quite interesting, as the same device, called "Disk2", is mounted by
-two hosts at the same time! Note, however, that the host called ``alice`` is actually
-attached to this storage, as can be seen in the @ref pf_tag_storage "<storage>"
-tag. This means that ``denise`` must access this storage through the network, but SimGrid automatically takes
-care of that for you.
-
-Furthermore, this example shows that ``denise`` has mounted two storages with different
-filesystem types (unix and windows). In general, a host can mount as many storage devices as
-required.
-
-@note
- Again, the difference between ``attach`` and ``mount`` is simply that
- an attached storage is always physically inside (or connected to) that machine;
- for instance, a USB stick is attached to one and only one machine (where it's plugged-in)
- but it can only be mounted on others, as mounted storage can also be a remote location.
-
-###### Example files #####
-
-@verbinclude example_filelist_xmltag_mount
-
-@subsubsection pf_storage_example_files Example files
-
-Several examples were already discussed above; if you're interested in full examples,
-check the the following platforms:
-
-1. ``examples/platforms/storage.xml``
-2. ``examples/platforms/remote_io.xml``
-
-If you're looking for some examplary C code, you may find the source code
-available in the directory ``examples/msg/io/`` useful.
-
-@subsubsection pf_storage_examples_modelling Modelling different situations
-
-The storage functionality of SimGrid is type-agnostic, that is, the implementation
-does not presume any type of storage, such as HDDs/SSDs, RAM,
-CD/DVD devices, USB sticks etc.
-
-This allows the user to apply the simulator for a wide variety of scenarios; one
-common scenario would be the access of remote RAM.
-
-#### Modelling the access of remote RAM ####
-
-How can this be achieved in SimGrid? Let's assume we have a setup where three hosts
-(HostA, HostB, HostC) need to access remote RAM:
-
-@verbatim
- Host A
- /
-RAM -- Host B
- @
- Host C
-@endverbatim
-
-An easy way to model this scenario is to setup and define the RAM via the
-@ref pf_tag_storage "storage" and @ref pf_storage_entity_storage_type "storage type"
-entities and attach it to a remote dummy host; then, every host can have their own links
-to this host (modelling for instance certain scenarios, such as PCIe ...)
-
-@verbatim
- Host A
- /
-RAM - Dummy -- Host B
- @
- Host C
-@endverbatim
-
-Now, if read from this storage, the host that mounts this storage
-communicates to the dummy host which reads from RAM and
-sends the information back.
-
@section pf_routing Routing
'build/xml/classsimgrid_1_1s4u_1_1Mutex.xml',
'build/xml/classsimgrid_1_1s4u_1_1NetZone.xml',
'build/xml/classsimgrid_1_1s4u_1_1Semaphore.xml',
- 'build/xml/classsimgrid_1_1s4u_1_1VirtualMachine.xml'
+ 'build/xml/classsimgrid_1_1s4u_1_1VirtualMachine.xml',
+ 'build/xml/actor_8h.xml',
+ 'build/xml/engine_8h.xml',
+ 'build/xml/vm_8h.xml'
]
python_modules = [
doxy_vars = {} # {classname: [names]}
# find the declarations in the XML files
-for arg in xml_files[:3]:
+for arg in xml_files:
if arg[-4:] != '.xml':
print ("Argument '{}' does not end with '.xml'".format(arg))
continue
- print("Parse file {}".format(arg))
+ #print("Parse file {}".format(arg))
tree = ET.parse(arg)
for elem in tree.findall(".//compounddef"):
- if elem.attrib["prot"] != "public":
- continue
- if "compoundname" in elem:
- raise Exception("Compound {} has no 'compoundname' child tag.".format(elem))
- compoundname = elem.find("compoundname").text
- #print ("compoundname {}".format(compoundname))
+ if elem.attrib["kind"] == "class":
+ if elem.attrib["prot"] != "public":
+ continue
+ if "compoundname" in elem:
+ raise Exception("Compound {} has no 'compoundname' child tag.".format(elem))
+ compoundname = elem.find("compoundname").text
+ #print ("compoundname {}".format(compoundname))
+ elif elem.attrib["kind"] == "file":
+ compoundname = ""
+ else:
+ print("Element {} is of kind {}".format(elem.attrib["id"], elem.attrib["kind"]))
+
for member in elem.findall('.//memberdef'):
if member.attrib["prot"] != "public":
continue
kind = member.attrib["kind"]
name = member.find("name").text
+ #print("kind:{} compoundname:{} name:{}".format( kind,compoundname, name))
if kind == "variable":
if compoundname not in doxy_vars:
doxy_vars[compoundname] = []
if name not in doxy_funs[compoundname]:
doxy_funs[compoundname][name] = []
doxy_funs[compoundname][name].append(args)
+ elif kind == "friend":
+ pass # Ignore friendship
else:
print ("member {}::{} is of kind {}".format(compoundname, name, kind))
if "(" in line:
(line, args) = line.split('(', 1)
args = "({}".format(args)
- (klass, obj) = line.rsplit('::', 1)
+ if '::' in line:
+ (klass, obj) = line.rsplit('::', 1)
+ else:
+ (klass, obj) = ("", line)
if klass not in doxy_funs:
print("Warning: {} documented, but class {} not found in doxygen.".format(line, klass))
continue
if obj not in doxy_funs[klass]:
- print("Warning: Object {} documented but not found in {}".format(line, klass))
+ print("Warning: Object '{}' documented but not found in '{}'".format(line, klass))
+# for obj in doxy_funs[klass]:
+# print(" found: {}::{}".format(klass, obj))
elif len(doxy_funs[klass][obj])==1:
del doxy_funs[klass][obj]
elif args not in doxy_funs[klass][obj]:
print("Warning: Function {}{} not found in {}".format(obj, args, klass))
else:
-# print("Found {} in {}".format(line, klass))
+ #print("Found {} in {}".format(line, klass))
doxy_funs[klass][obj].remove(args)
if len(doxy_funs[klass][obj]) == 0:
del doxy_funs[klass][obj]
get_filtered_netzones_recursive
simgrid::s4u::Storage
simgrid::s4u::Activity_T
+simgrid::s4u::Engine::get_storage_count
+simgrid::s4u::Engine::storage_by_name
+simgrid::s4u::Engine::storage_by_name_or_null
\ No newline at end of file
CREATE_SUBDIRS = NO # Mandatory for exhale
# Allow for rst directives and advanced functions e.g. grid tables
-ALIASES = "beginrst=\verbatim "
+ALIASES = "beginrst=\verbatim embed:rst"
ALIASES += "endrst=\endverbatim"
# Enable preprocessing and related preprocessor necessities
meaning that the list of traversed links from A to B is the same as
from B to A. Explicitly define non-symmetrical routes if you prefer.
+The last thing you must know on SimGrid platform files is that the
+root tag must be :ref:`pf_tag_platform`. If the ``version`` attribute
+does not match what SimGrid expects, you will be hinted to use to the
+``simgrid_update_xml`` utility to update your file.
+
Cluster with a Crossbar
-----------------------
--- /dev/null
+.. raw:: html
+
+ <object id="TOC" data="graphical-toc.svg" type="image/svg+xml"></object>
+ <script>
+ window.onload=function() { // Wait for the SVG to be loaded before changing it
+ var elem=document.querySelector("#TOC").contentDocument.getElementById("RoutingBox")
+ elem.style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1;stroke:#000000;stroke-width:0.35277778;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1";
+ }
+ </script>
+ <br/>
+ <br/>
+
+.. _platform_routing:
+
+Defining a Routing
+##################
+
+Networking zones (:ref:`pf_tag_zone`) are an advanced concept used to factorize the description
+to reduce the size of your platform on disk and in memory. Then, when
+a host wants to communicate with another host belonging to the same
+zone, it is the zone's duty to find the list of links that are
+involved in the communication. In the above examples, since we use
+``routing="Full"``, all routes must be explicitly given using the
+:ref:`pf_tag_route` and :ref:`pf_tag_link_ctn` tags (this :ref:`routing
+model <pf_rm>` is both simple and inefficient :) It is OK to not
+specify each and every route between hosts, as long as you do not try
+to start a communication on any of the missing routes during your
+simulation.
+
+Any zone may contain sub-zones, allowing for a hierarchical
+decomposition of the platform. Routing can be made more efficient (as the
+inter-zone routing gets factored with :ref:`pf_tag_zoneroute`), and
+allows you to have more than one routing model in your platform. For
+example, you can have a coordinate-based routing for the WAN parts
+of your platforms, a full routing within each datacenter, and a highly
+optimized routing within each cluster of the datacenter. In this
+case, determining the route between two given hosts gets :ref:`routing_basics`
+"somewhat more complex" but SimGrid still computes
+these routes for you in a time- and space-efficient manner.
+Here is an illustration of these concepts:
+
+.. image:: img/zone_hierarchy.png
+
+Circles represent processing units and squares represent network
+routers. Bold lines represent communication links. The zone "AS2" models the core of a national network interconnecting a
+small flat cluster (AS4) and a larger hierarchical cluster (AS5), a
+subset of a LAN (AS6), and a set of peers scattered around the world
+(AS7).
+
+.. todo:: Add more examples, such as the cloud example described in
+ previous paragraph
+
elem.style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1;stroke:#000000;stroke-width:0.35277778;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1";
}
</script>
- <br/>
- <br/>
+ <br />
+ <br />
You can extend SimGrid without modifying it, thanks to our plugin
mechanism. This page describes how to write your own plugin, and
.. _plugin_host_energy:
-Host Energy Plugin
-==================
+Host Energy
+===========
.. doxygengroup:: Plugin_host_energy
+
+
.. _plugin_link_energy:
-Link Energy Plugin
-==================
+Link Energy
+===========
.. doxygengroup:: Plugin_link_energy
+
+
.. _plugin_host_load:
-Host Load Plugin
-================
+Host Load
+=========
.. doxygengroup:: Plugin_host_load
+
+
+.. _plugin_filesystem:
+
+File System
+===========
+
+.. doxygengroup:: Plugin_filesystem
+
+
.. LocalWords: SimGrid
+
-------------------------------------------------------------------------------
+.. _pf_tag_disk:
+
+<disk>
+------
+
+SimGrid can simulate the time it takes to read or write data on disk, even if the stored data is not made persistent in
+any way by SimGrid. This means that your application will correctly be slowed down when doing simulated I/O, but there
+is no way to get the data stored this way.
+
+We decided to not model anything beyond raw access in SimGrid because we believe that there is not single way of doing so.
+We provide an example model of file system as a plugin, (sparsely) documented in :ref:`plugin_filesystem`.
+
+**Parent tags:** :ref:`pf_tag_host` |br|
+**Children tags:** :ref:`pf_tag_prop` |br|
+**Attributes:**
+
+:``id``: A name of your choice (must be unique on this host).
+:``read_bw``: Read bandwidth for this disk. You must specify a unit as follows.
+
+ **Units in bytes and powers of 2** (1 KiBps = 1,024 Bps):
+ Bps, KiBps, MiBps, GiBps, TiBps, PiBps, or EiBps. |br|
+ **Units in bits and powers of 2** (1 Bps = 8 bps):
+ bps, Kibps, Mibps, Gibps, Tibps, Pibps, or Eibps. |br|
+ **Units in bytes and powers of 10** (1 KBps = 1,000 Bps):
+ Bps, KBps, MBps, GBps, TBps, PBps, or EBps. |br|
+ **Units in bits and powers of 10:**
+ bps, Kbps, Mbps, Gbps, Tbps, Pbps, or Ebps.
+
+:``write_bw``: Write bandwidth for this disk. You must specify a unit as for the read bandwidth.
+
+.. code-block:: xml
+
+ <host id="alice" speed="1Gf">
+ <disk id="Disk1" read_bw="200MBps" write_bw="80MBps">
+ <!-- you can add properties for anything you want: they are not used by SimGrid -->
+ <prop id="content" value="storage/content/small_content.txt"/>
+ </disk>
+ <prop id="ram" value="100B" />
+ </host>
+
+-------------------------------------------------------------------------------
+
.. _pf_tag_config:
<config>
# classname or method name
return True
- (obj, meth) = self.fullname.rsplit('::', 1)
+ if '::' in self.fullname:
+ (obj, meth) = self.fullname.rsplit('::', 1)
+ prefix = './/compoundname[text()="{:s}"]/../sectiondef[@kind="public-func" or @kind="public-static-func"]'.format(obj)
+ obj = "{:s}::".format(obj)
+ else:
+ meth = self.fullname
+ prefix = './'
+ obj = ''
- xpath_query_noparam = ('.//compoundname[text()="{:s}"]/../sectiondef[@kind="public-func" or @kind="public-static-func"]'
- '/memberdef[@kind="function"]/name[text()="{:s}"]/..').format(obj, meth)
+ xpath_query_noparam = ('{:s}/memberdef[@kind="function"]/name[text()="{:s}"]/..').format(prefix, meth)
xpath_query = ""
-# print("fullname {}".format(self.fullname))
if self.argsstring != None:
- xpath_query = ('.//compoundname[text()="{:s}"]/../sectiondef[@kind="public-func" or @kind="public-static-func"]'
- '/memberdef[@kind="function" and argsstring/text()="{:s}"]/name[text()="{:s}"]/..').format(obj,self.argsstring,meth)
+ xpath_query = ('{:s}/memberdef[@kind="function" and argsstring/text()="{:s}"]/name[text()="{:s}"]/..').format(prefix,self.argsstring,meth)
else:
xpath_query = xpath_query_noparam
match = get_doxygen_root().xpath(xpath_query)
if self.argsstring != None:
candidates = get_doxygen_root().xpath(xpath_query_noparam)
if len(candidates) == 1:
- logger.warning("[autodoxy] Using method '{}::{}{}' instead of '{}::{}{}'. You may want to drop your specification of the signature, or to fix it."
+ logger.warning("[autodoxy] Using method '{}{}{}' instead of '{}{}{}'. You may want to drop your specification of the signature, or to fix it."
.format(obj, meth, candidates[0].find('argsstring').text, obj, meth, self.argsstring))
self.object = candidates[0]
return True
- logger.warning("[autodoxy] WARNING: Could not find method {}::{}{}".format(obj, meth, self.argsstring))
+ logger.warning("[autodoxy] WARNING: Could not find method {}{}{}".format(obj, meth, self.argsstring))
for cand in candidates:
- logger.warning("[autodoxy] WARNING: Existing candidate: {}::{}{}".format(obj, meth, cand.find('argsstring').text))
+ logger.warning("[autodoxy] WARNING: Existing candidate: {}{}{}".format(obj, meth, cand.find('argsstring').text))
else:
- logger.warning("[autodoxy] WARNING: could not find method {}::{} in Doxygen files".format(obj, meth))
+ logger.warning("[autodoxy] WARNING: could not find method {}{} in Doxygen files\nQuery: {}".format(obj, meth, xpath_query))
return False
self.object = match[0]
return True
class Actor
==============
+.. autodoxyclass:: simgrid::s4u::Actor
+
.. doxygentypedef:: ActorPtr
.. doxygentypedef:: aid_t
-.. autodoxyclass:: simgrid::s4u::Actor
-
Creating actors
---------------
.. group-tab:: C++
+ .. code:: C++
+
+ #include <simgrid/s4u/Engine.hpp>
+
.. autodoxymethod:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, const std::function< void()> &code)
.. autodoxymethod:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, F code)
.. autodoxymethod:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, F code, Args... args)
.. group-tab:: Python
+ .. code:: Python
+
+ from simgrid import Actor
+
.. automethod:: simgrid.Actor.create
+ .. group-tab:: C
+
+ .. code:: C
+
+ #include <simgrid/actor.h>
+
+ .. autodoxymethod:: sg_actor_init(const char *name, sg_host_t host)
+ .. autodoxymethod:: sg_actor_start(sg_actor_t actor, xbt_main_func_t code, int argc, char **argv)
+
+ .. autodoxymethod:: ::sg_actor_attach(const char *name, void *data, sg_host_t host, xbt_dict_t properties)
+ .. autodoxymethod:: ::sg_actor_detach()
+
+ .. autodoxymethod:: sg_actor_ref(sg_actor_t actor)
+ .. autodoxymethod:: sg_actor_unref(sg_actor_t actor)
+
Searching specific actors
-------------------------
.. automethod:: simgrid.Actor.by_pid
.. automethod:: simgrid.Actor.self
+ .. group-tab:: C
+
+ .. autodoxymethod:: sg_actor_by_PID(aid_t pid)
+ .. autodoxymethod:: sg_actor_self()
+
Querying info about actors
--------------------------
.. autoattribute:: simgrid.Actor.pid
.. autoattribute:: simgrid.Actor.ppid
+ .. group-tab:: C
+
+ .. autodoxymethod:: sg_actor_get_name(sg_actor_t actor)
+ .. autodoxymethod:: sg_actor_get_PID(sg_actor_t actor)
+ .. autodoxymethod:: sg_actor_get_PPID(sg_actor_t actor)
+ .. autodoxymethod:: sg_actor_get_properties(sg_actor_t actor)
+ .. autodoxymethod:: sg_actor_get_property_value(sg_actor_t actor, const char *name)
+
+ .. autodoxymethod:: sg_actor_get_host(sg_actor_t actor)
+ .. autodoxymethod:: sg_actor_set_host(sg_actor_t actor, sg_host_t host)
+
+ .. autodoxymethod:: sg_actor_data(const_sg_actor_t actor)
+ .. autodoxymethod:: sg_actor_data_set(sg_actor_t actor, void *userdata)
+
Suspending and resuming actors
------------------------------
.. automethod:: simgrid.Actor.suspend
.. automethod:: simgrid.Actor.is_suspended
+ .. group-tab:: C
+
+ .. autodoxymethod:: sg_actor_suspend(sg_actor_t actor)
+ .. autodoxymethod:: sg_actor_resume(sg_actor_t actor)
+ .. autodoxymethod:: sg_actor_is_suspended(sg_actor_t actor)
+
Specifying when actors should terminate
---------------------------------------
.. automethod:: simgrid.Actor.daemonize
.. automethod:: simgrid.Actor.is_daemon
+ .. group-tab:: C
+
+ .. autodoxymethod:: sg_actor_kill(sg_actor_t actor)
+ .. autodoxymethod:: sg_actor_kill_all()
+ .. autodoxymethod:: sg_actor_set_kill_time(sg_actor_t actor, double kill_time)
+
+ .. autodoxymethod:: sg_actor_restart(sg_actor_t actor)
+ .. autodoxymethod:: sg_actor_daemonize(sg_actor_t actor)
+
+.. _API_s4u_Actor_end:
+
Reacting to the end of actors
-----------------------------
.. automethod:: simgrid.Actor.join
+ .. group-tab:: C
+
+ .. autodoxymethod:: sg_actor_join(sg_actor_t actor, double timeout)
+ .. autodoxymethod:: sg_actor_set_auto_restart(sg_actor_t actor, int auto_restart)
+
Signals
-------
Simulation Engine
====================
-.. doxygenclass:: simgrid::s4u::Engine
- :members:
- :protected-members:
- :undoc-members:
+.. autodoxyclass:: simgrid::s4u::Engine
+
+Initialization
+--------------
+
+.. tabs::
+
+ .. group-tab:: C++
+
+ .. autodoxymethod:: simgrid::s4u::Engine::Engine(int *argc, char **argv)
+ .. autodoxymethod:: simgrid::s4u::Engine::is_initialized()
+ .. autodoxymethod:: simgrid::s4u::Engine::shutdown()
+ .. autodoxymethod:: simgrid::s4u::Engine::set_config(const std::string &str)
+
+ .. autodoxymethod:: simgrid::s4u::Engine::load_deployment(const std::string &deploy)
+ .. autodoxymethod:: simgrid::s4u::Engine::load_platform(const std::string &platf)
+ .. autodoxymethod:: simgrid::s4u::Engine::register_actor(const std::string &name)
+ .. autodoxymethod:: simgrid::s4u::Engine::register_actor(const std::string &name, F code)
+ .. autodoxymethod:: simgrid::s4u::Engine::register_default(int(*code)(int, char **))
+ .. autodoxymethod:: simgrid::s4u::Engine::register_function(const std::string &name, int(*code)(int, char **))
+ .. autodoxymethod:: simgrid::s4u::Engine::register_function(const std::string &name, void(*code)(std::vector< std::string >))
+
+ .. group-tab:: Python
+
+ .. automethod:: simgrid.Engine.load_deployment
+ .. automethod:: simgrid.Engine.load_platform
+ .. automethod:: simgrid.Engine.register_actor
+
+ .. group-tab:: C
+
+ .. autodoxymethod:: simgrid_init
+
+ .. autodoxymethod:: simgrid_load_deployment
+ .. autodoxymethod:: simgrid_load_platform
+ .. autodoxymethod:: simgrid_register_default
+ .. autodoxymethod:: simgrid_register_function
+
+Run the simulation
+------------------
+
+.. tabs::
+
+ .. group-tab:: C++
+
+ .. autodoxymethod:: simgrid::s4u::Engine::get_clock()
+ .. autodoxymethod:: simgrid::s4u::Engine::run()
+
+ .. group-tab:: Python
+
+ .. automethod:: simgrid.Engine.get_clock
+ .. automethod:: simgrid.Engine.run
+
+ .. group-tab:: C
+
+ .. autodoxymethod:: simgrid_get_clock
+ .. autodoxymethod:: simgrid_run
+
+Retrieving actors
+-----------------
+
+.. tabs::
+
+ .. group-tab:: C++
+
+ .. autodoxymethod:: simgrid::s4u::Engine::get_actor_count()
+ .. autodoxymethod:: simgrid::s4u::Engine::get_all_actors()
+ .. autodoxymethod:: simgrid::s4u::Engine::get_filtered_actors(const std::function< bool(ActorPtr)> &filter)
+
+ .. group-tab:: C
+
+ .. autodoxymethod:: simgrid_get_actor_count()
+
+Retrieving hosts
+----------------
+
+.. tabs::
+
+ .. group-tab:: C++
+
+ .. autodoxymethod:: simgrid::s4u::Engine::get_all_hosts()
+ .. autodoxymethod:: simgrid::s4u::Engine::get_host_count()
+ .. autodoxymethod:: simgrid::s4u::Engine::get_filtered_hosts(const std::function< bool(Host *)> &filter)
+ .. autodoxymethod:: simgrid::s4u::Engine::host_by_name(const std::string &name)
+ .. autodoxymethod:: simgrid::s4u::Engine::host_by_name_or_null(const std::string &name)
+
+ .. group-tab:: Python
+
+ .. automethod:: simgrid.Engine.get_all_hosts
+
+Retrieving links
+----------------
+
+.. tabs::
+
+ .. group-tab:: C++
+
+ .. autodoxymethod:: simgrid::s4u::Engine::get_all_links()
+ .. autodoxymethod:: simgrid::s4u::Engine::get_link_count()
+ .. autodoxymethod:: simgrid::s4u::Engine::get_filtered_links
+ .. autodoxymethod:: simgrid::s4u::Engine::link_by_name(const std::string &name)
+ .. autodoxymethod:: simgrid::s4u::Engine::link_by_name_or_null(const std::string &name)
+
+Interacting with the routing
+----------------------------
+
+.. tabs::
+
+ .. group-tab:: C++
+
+ .. autodoxymethod:: simgrid::s4u::Engine::get_all_netpoints()
+ .. autodoxymethod:: simgrid::s4u::Engine::get_filtered_netzones()
+ .. autodoxymethod:: simgrid::s4u::Engine::get_instance()
+ .. autodoxymethod:: simgrid::s4u::Engine::get_netzone_root()
+ .. autodoxymethod:: simgrid::s4u::Engine::netpoint_by_name_or_null(const std::string &name)
+ .. autodoxymethod:: simgrid::s4u::Engine::netzone_by_name_or_null(const std::string &name)
+ .. autodoxymethod:: simgrid::s4u::Engine::set_netzone_root(NetZone *netzone)
+
+Signals
+-------
+
+.. tabs::
+
+ .. group-tab:: C++
+
+ .. autodoxyvar:: simgrid::s4u::Engine::on_deadlock
+ .. autodoxyvar:: simgrid::s4u::Engine::on_platform_created
+ .. autodoxyvar:: simgrid::s4u::Engine::on_platform_creation
+ .. autodoxyvar:: simgrid::s4u::Engine::on_simulation_end
+ .. autodoxyvar:: simgrid::s4u::Engine::on_time_advance
.. _API_s4u_Mailbox:
:protected-members:
:undoc-members:
+.. autodoxymethod:: sg_vm_create_core
+.. autodoxymethod:: sg_vm_create_multicore
+.. autodoxymethod:: sg_vm_get_name
+.. autodoxymethod:: sg_vm_get_pm
+.. autodoxymethod:: sg_vm_is_created
+.. autodoxymethod:: sg_vm_is_running
+.. autodoxymethod:: sg_vm_is_suspended
+.. autodoxymethod:: sg_vm_start
+.. autodoxymethod:: sg_vm_suspend
+.. autodoxymethod:: sg_vm_resume
+.. autodoxymethod:: sg_vm_shutdown
+.. autodoxymethod:: sg_vm_destroy
.. _API_s4u_Activity:
C API Reference
***************
-==============
-Main functions
-==============
-
-.. doxygenfunction:: simgrid_init
-.. doxygenfunction:: simgrid_get_clock
-.. doxygenfunction:: simgrid_load_deployment
-.. doxygenfunction:: simgrid_load_platform
-.. doxygenfunction:: simgrid_register_default
-.. doxygenfunction:: simgrid_register_function
-.. doxygenfunction:: simgrid_run
-
==================
Condition Variable
==================
Describing the Simulated Platform <platform.rst>
Examples <Platform_Examples.rst>
Modeling Hints <platform_howtos.rst>
+ Defining a Routing <Platform_Routing.rst>
XML Reference <XML_Reference.rst>
Describing the Experimental Setup <Experimental_Setup.rst>
Configuring SimGrid <Configuring_SimGrid.rst>
the :ref:`lua bindings <platform_lua>` (it is not yet possible to do so in
python or directly in C++).
-We understand that writing a complex platform description can be tricky, we thus included
-:ref:`many examples <platform_examples>` in the archive. This
-documentation also contains some :ref:`hints and howtos <howto>`, as well
-as the full :ref:`XML reference guide <platform_reference>`.
-
-
-Any simulated platform must contain **basic elements**, such as hosts, links, disks, etc. SimGrid gives you a great
-liberty when defining the **routing of your platform**, i.e., the network path taken between each pair of hosts.
+Any simulated platform must contain **basic elements**, such as
+:ref:`pf_tag_host`, :ref:`pf_tag_link`, :ref:`pf_tag_disk`, and similar.
+SimGrid makes no assumption about the **routing of your platform**, so you must declare
+explicitly the network path taken between each pair of hosts.
+This can be done through a flat list of :ref:`pf_tag_route` for each pair of hosts (routes
+are symmetrical by default), or you may use the advanced concept of :ref:`networking zone <platform_routing>`
+to efficiently express the routing of your platform.
Finally, you may also describe an **experimental scenario**, with qualitative (e.g., bandwidth variations representing
an external load) and qualitative (e.g., representing how some elements fail and restart over time) changes.
-
-First Example
-*************
-
-Imagine you want to describe a little platform with three hosts,
-interconnected as follows:
-
-.. image:: /tuto_smpi/3hosts.png
- :align: center
-
-This can be done with the following platform file, that considers the
-simulated platform as a graph of hosts and network links.
-
-.. literalinclude:: /tuto_smpi/3hosts.xml
- :language: xml
-
-The most important elements are the basic ones: :ref:`pf_tag_host`,
-:ref:`pf_tag_link`, and similar. Then come the routes between any pair
-of hosts, that are given explicitly with :ref:`pf_tag_route` (routes
-are symmetrical by default). Any host must be given a computational
-speed (in flops) while links must be given a latency (in seconds) and
-a bandwidth (in bytes per second). Note that you can write 1Gflops
-instead of 1000000000flops, and similar.
-
-Every platform element must be located within a given **networking
-zone** . Zones are in
-charge of the routing, see below.
-
-The last thing you must know on SimGrid platform files is that the
-root tag must be :ref:`pf_tag_platform`. If the ``version`` attribute
-does not match what SimGrid expects, you will be hinted to use to the
-``simgrid_update_xml`` utility to update your file.
-
-
-Defining a Routing
-******************
-
-Networking zones (:ref:`pf_tag_zone`) are used to factorize the description
-to reduce the size of your platform on disk and in memory. Then, when
-a host wants to communicate with another host belonging to the same
-zone, it is the zone's duty to find the list of links that are
-involved in the communication. In the above examples, since we use
-``routing="Full"``, all routes must be explicitly given using the
-:ref:`pf_tag_route` and :ref:`pf_tag_link_ctn` tags (this :ref:`routing
-model <pf_rm>` is both simple and inefficient :) It is OK to not
-specify each and every route between hosts, as long as you do not try
-to start a communication on any of the missing routes during your
-simulation.
-
-Any zone may contain sub-zones, allowing for a hierarchical
-decomposition of the platform. Routing can be made more efficient (as the
-inter-zone routing gets factored with :ref:`pf_tag_zoneroute`), and
-allows you to have more than one routing model in your platform. For
-example, you can have a coordinate-based routing for the WAN parts
-of your platforms, a full routing within each datacenter, and a highly
-optimized routing within each cluster of the datacenter. In this
-case, determining the route between two given hosts gets :ref:`routing_basics`
-"somewhat more complex" but SimGrid still computes
-these routes for you in a time- and space-efficient manner.
-Here is an illustration of these concepts:
-
-.. image:: img/zone_hierarchy.png
-
-Circles represent processing units and squares represent network
-routers. Bold lines represent communication links. The zone "AS2" models the core of a national network interconnecting a
-small flat cluster (AS4) and a larger hierarchical cluster (AS5), a
-subset of a LAN (AS6), and a set of peers scattered around the world
-(AS7).
-
-.. todo:: Add more examples, such as the cloud example described in
- previous paragraph
-
-Performance Profiles and Churn
-******************************
+The most efficient way to learn about platform description is to look at the
+:ref:`many examples <platform_examples>` included in the archive and described
+in the next section. This documentation also contains some :ref:`hints and
+howtos <howto>`, as well as the full :ref:`XML reference guide
+<platform_reference>`.
.. LocalWords: SimGrid
-.. _platform:
-
.. raw:: html
<object id="TOC" data="graphical-toc.svg" type="image/svg+xml"></object>
.. code-block:: xml
- <host id="A" speed="1Gf"/>
- <host id="B" speed="1Gf"/>
+ <host id="A" speed="1Gf" />
+ <host id="B" speed="1Gf" />
- <link id="link1" latency="10ms" bandwidth="1Mbps"/>
+ <link id="link1" latency="10ms" bandwidth="1Mbps" />
- <route src="A" dst="B>
- <link_ctn id="link1/>
+ <route src="A" dst="B">
+ <link_ctn id="link1" />
</route>
If host `A` sends `100kB` (a hundred kilobytes) to host `B`, one could expect
.. example-tab:: examples/platforms/energy_platform.xml
+.. _s4u_ex_disk_io:
+
I/O on Disks and Files
----------------------
void sg_actor_set_auto_restart(sg_actor_t actor, int auto_restart);
XBT_PUBLIC void sg_actor_daemonize(sg_actor_t actor);
+#ifndef DOXYGEN
XBT_ATTRIB_DEPRECATED_v329("Please use sg_actor_set_host() instead") XBT_PUBLIC
void sg_actor_migrate(sg_actor_t process, sg_host_t host);
+#endif
XBT_PUBLIC void sg_actor_set_host(sg_actor_t actor, sg_host_t host);
XBT_PUBLIC void sg_actor_join(sg_actor_t actor, double timeout);
/** Creates a new platform, including hosts, links, and the routing table.
*
- * \rst
+ * \beginrst
* See also: :ref:`platform`.
* \endrst
*/
XBT_PUBLIC void simgrid_load_platform(const char* filename);
/** Load a deployment file and launch the actors that it contains
*
- * \rst
+ * \beginrst
* See also: :ref:`deploy`.
* \endrst
*/
#include <map>
#include <memory>
#include <string>
-#endif
+#endif /* C++ */
// C interface
////////////////
namespace s4u {
/** @brief A simulated file
+ * @addtogroup Plugin_filesystem
*
* Used to simulate the time it takes to access to a file, but does not really store any information.
*
namespace simgrid {
namespace s4u {
-/** \beginrst An actor is an independent stream of execution in your distributed application.
+/** An actor is an independent stream of execution in your distributed application.
+ *
+ * \beginrst
* It is located on a (simulated) :cpp:class:`host <simgrid::s4u::Host>`, but can interact
* with the whole simulated platform.
*
namespace s4u {
/** @brief Simulation engine
*
- * This class is an interface to the simulation engine.
+ * This is a singleton containing all the main functions of the simulation.
*/
class XBT_PUBLIC Engine {
public:
/** Constructor, taking the command line parameters of your main function */
explicit Engine(int* argc, char** argv);
- /** Currently, only one instance is allowed to exist. This is why you can't copy or move it */
+ /* Currently, only one instance is allowed to exist. This is why you can't copy or move it */
+#ifndef DOXYGEN
Engine(const Engine&) = delete;
Engine(Engine&&) = delete;
-
~Engine();
+#endif
+
/** Finalize the default engine and all its dependencies */
static void shutdown();
- /** @brief Run the simulation after initialization */
+ /** Run the simulation after initialization */
void run();
/** @brief Retrieve the simulation time (in seconds) */
std::vector<ActorPtr> get_all_actors();
std::vector<ActorPtr> get_filtered_actors(const std::function<bool(ActorPtr)>& filter);
+#ifndef DOXYGEN
size_t get_storage_count();
std::vector<Storage*> get_all_storages();
Storage* storage_by_name(const std::string& name);
Storage* storage_by_name_or_null(const std::string& name);
+#endif
std::vector<kernel::routing::NetPoint*> get_all_netpoints();
kernel::routing::NetPoint* netpoint_by_name_or_null(const std::string& name);
XBT_LOG_NEW_DEFAULT_SUBCATEGORY(s4u_file, s4u, "S4U files");
int sg_storage_max_file_descriptors = 1024;
+/** @defgroup plugin_filesystem
+ @beginrst
+
+ @endrst
+ */
+
+
namespace simgrid {
namespace s4u {
simgrid::xbt::Extension<Disk, FileSystemDiskExt> FileSystemDiskExt::EXTENSION_ID;
}
/** @brief Write into a file (local or remote)
+ * @ingroup plugin_filesystem
*
* @param size of the file to write
* @return the number of bytes successfully write or -1 if an error occurred
}
/* **************************** Public interface *************************** */
+/** @brief Initialize the file system plugin.
+ @ingroup plugin_filesystem
+
+ @beginrst
+ See the examples in :ref:`s4u_ex_disk_io`.
+ @endrst
+ */
void sg_storage_file_system_init()
{
sg_storage_max_file_descriptors = 1024;
delete fd;
}
+/** Retrieves the path to the file
+ * @ingroup plugin_filesystem
+ */
const char* sg_file_get_name(sg_file_t fd)
{
xbt_assert((fd != nullptr), "Invalid file descriptor");
return fd->get_path();
}
+/** Retrieves the size of the file
+ * @ingroup plugin_filesystem
+ */
sg_size_t sg_file_get_size(sg_file_t fd)
{
return fd->size();
fd->dump();
}
+/** Retrieves the user data associated with the file
+ * @ingroup plugin_filesystem
+ */
void* sg_file_get_data(sg_file_t fd)
{
return fd->get_data();
}
+/** Changes the user data associated with the file
+ * @ingroup plugin_filesystem
+ */
void sg_file_set_data(sg_file_t fd, void* data)
{
fd->set_data(data);
}
/**
- * @brief Set the file position indicator in the sg_file_t by adding offset bytes
- * to the position specified by origin (either SEEK_SET, SEEK_CUR, or SEEK_END).
+ * @brief Set the file position indicator in the sg_file_t by adding offset bytes to the position specified by origin (either SEEK_SET, SEEK_CUR, or SEEK_END).
+ * @ingroup plugin_filesystem
*
* @param fd : file object that identifies the stream
* @param offset : number of bytes to offset from origin
/**
* @brief Copy a file to another location on a remote host.
+ * @ingroup plugin_filesystem
+ *
* @param file : the file to move
* @param host : the remote host where the file has to be copied
* @param fullpath : the complete path destination on the remote host
/**
* @brief Move a file to another location on a remote host.
+ * @ingroup plugin_filesystem
+ *
* @param file : the file to move
* @param host : the remote host where the file has to be moved
* @param fullpath : the complete path destination on the remote host
/** @defgroup plugin_host_energy
@beginrst
+
This is the energy plugin, enabling to account not only for computation time, but also for the dissipated energy in the
simulated platform.
-To activate this plugin, first call :cpp:func:`sg_host_energy_plugin_init()` before your :cpp:func:`MSG_init()`, and then use
-:cpp:func:`MSG_host_get_consumed_energy()` to retrieve the consumption of a given host.
+To activate this plugin, first call :cpp:func:`sg_host_energy_plugin_init()` before your :cpp:func:`MSG_init()`, and
+then use :cpp:func:`MSG_host_get_consumed_energy()` to retrieve the consumption of a given host.
When the host is on, this energy consumption naturally depends on both the current CPU load and the host energy profile.
According to our measurements, the consumption is somehow linear in the amount of cores at full speed, with an
-abnormality when all the cores are idle. The full details are in `our scientific paper <https://hal.inria.fr/hal-01523608>`_
-on that topic.
+abnormality when all the cores are idle. The full details are in `our scientific paper
+<https://hal.inria.fr/hal-01523608>`_ on that topic.
As a result, our energy model takes 4 parameters:
- - ``Idle`` wattage (i.e., instantaneous consumption in Watt) when your host is up and running, but without anything to do.
+ - ``Idle`` wattage (i.e., instantaneous consumption in Watt) when your host is up and running, but without anything to
+do.
- ``Epsilon`` wattage when all cores are at 0 or epsilon%, but not in Idle state.
- ``AllCores`` wattage when all cores of the host are at 100%.
- ``Off`` wattage when the host is turned off.
</table>
To change the pstate of a given CPU, use the following functions:
-:cpp:func:`MSG_host_get_nb_pstates()`, :cpp:func:`simgrid::s4u::Host::set_pstate()`, :cpp:func:`MSG_host_get_power_peak_at()`.
+:cpp:func:`MSG_host_get_nb_pstates()`, :cpp:func:`simgrid::s4u::Host::set_pstate()`,
+:cpp:func:`MSG_host_get_power_peak_at()`.
.. raw:: html
/** @ingroup plugin_host_energy
* @brief Enable host energy plugin
- * @details Enable energy plugin to get joules consumption of each cpu. Call this function before #MSG_init().
+ * @details Enable energy plugin to get joules consumption of each cpu. Call this function before loading your platform.
*/
void sg_host_energy_plugin_init()
{
The second property means that when your host is turned off, it will dissipate only 10 Watts (please note that these
values are arbitrary).
- To simulate the energy-related elements, first call the simgrid#energy#sg_link_energy_plugin_init() before your
- #MSG_init(),
+ To simulate the energy-related elements, first call the sg_link_energy_plugin_init() before loading the platform
and then use the following function to retrieve the consumption of a given link: sg_link_get_consumed_energy().
*/
/** @ingroup plugin_link_energy
* @brief Enable energy plugin
* @details Enable energy plugin to get joules consumption of each cpu. You should call this function before
- * #MSG_init().
+ * loading your platform.
*/
void sg_link_energy_plugin_init()
{
}
/** @brief Immediately kills all processes within the given VM.
- * Any memory that they allocated will be leaked, unless you used #MSG_process_on_exit().
*
- * No extra delay occurs. If you want to simulate this too, you want to use a #MSG_process_sleep().
+ @beginrst
+
+ The memory allocated by these actors is leaked, unless you used :cpp:func:`simgrid::s4u::Actor::on_exit`.
+
+ @endrst
+ *
+ * No extra delay occurs by default. You may let your actor sleep by a specific amount to simulate any extra delay that you want.
*/
void sg_vm_shutdown(sg_vm_t vm)
{
