Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Further improvements to the docs
authorMartin Quinson <martin.quinson@loria.fr>
Mon, 1 Oct 2018 00:31:20 +0000 (02:31 +0200)
committerMartin Quinson <martin.quinson@loria.fr>
Mon, 1 Oct 2018 00:36:25 +0000 (02:36 +0200)
- Convert MSG and Java (not the javadoc, only generalities) to Sphinx
- Get rid of Exhale and write the doxygen directives manually.
  - I'm too picky on how things should look
  - ./Build.sh tries to check for missing directives, somehow
- Restore some doc chunks that got lost in MSG when converting to
  msg_legacy.cpp. Initially, I thought that MSG could be strongly
  deprecated, but now I understand that some people are not ready for
  the shift to S4U yet.

22 files changed:
doc/doxygen/java.doc [deleted file]
doc/doxygen/module-msg.doc [deleted file]
docs/Build.sh
docs/ignored_symbols [new file with mode: 0644]
docs/source/Doxyfile
docs/source/app_java.rst [new file with mode: 0644]
docs/source/app_msg.rst [new file with mode: 0644]
docs/source/app_s4u.rst
docs/source/app_smpi.rst
docs/source/conf.py
docs/source/index.rst
docs/source/intro_concepts.rst
docs/source/intro_install.rst
docs/source/introduction.rst
docs/source/scenar_config.rst
examples/s4u/README.rst
include/simgrid/msg.h
src/msg/msg_global.cpp
src/msg/msg_gos.cpp
src/msg/msg_process.cpp
src/msg/msg_task.cpp
tools/cmake/DefinePackages.cmake

diff --git a/doc/doxygen/java.doc b/doc/doxygen/java.doc
deleted file mode 100644 (file)
index d4c273a..0000000
+++ /dev/null
@@ -1,233 +0,0 @@
-/*! @page MSG_Java Java Bindings
-
-@tableofcontents
-
-This section describes jMSG, the Java API to Simgrid. This API mimicks 
-@ref MSG_API "MSG", which is a simple yet somehow realistic interface.
-<b>The full [javadoc](javadoc/index.html) is available.</b>
-
-Most of the documentation of the @ref MSG_API "MSG API" in C applies
-directly to the Java bindings (any divergence is seen as a bug that we
-should fix). MSG structures are mapped to Java objects as expected,
-and the MSG functions are methods in these objects.
-
-@section java_install How to install the Java bindings
-
-This is documented in the @ref install_java Section.
-
-@section java_use How to use the Java bindings
-
-In most cases, you can use the SimGrid bindings as if it was a Java
-library:
-
-~~~~{.sh}
-$ javac -classpath .:path/to/simgrid.jar your/java/Code.java
-$ java -classpath .:path/to/simgrid.jar your.java.Code the/parameter/to/your/code
-~~~~
-
-For example:
-~~~~{.sh}
-$ cd examples/java
-$ java -classpath ../../simgrid.jar:. .:../../simgrid.jar app.pingpong.Main ../platforms/platform.xml 
-~~~~
-
-Any SimGrid simulation (java or not) is usually constituted of several
-kind of actors or processes (classes extending @c Msg.Process) that
-are deployed over the hosts of the virtual platform. So, your code
-should declare these actors, plus a Main class in charge of deploying
-your actors on the platform. Please refer to the examples for details.
-
-@subsection java_use_trouble Troubleshooting
-
-Actually, these bindings are not only implemented in Java. They do use
-the C implementation of SimGrid. This should be transparent as this
-library is directly included in the `simgrid.jar` file but things can
-still go wrong is several ways.
-
-** **Error: library simgrid not found**
-
-This means that the JVM fails to load the native library. You should
-try to rebuild the simgrid.jar file as explained above. If it does not
-help, you can try to use an installed version of the library instead
-of the one included in the jar. For that, specify the path to the
-native library in the `LD_LIBRARY_PATH` variable (or in the
-`DYLD_LIBRARY_PATH` on Mac OSX).
-
-~~~~{.sh}
-$ export SIMGRID_ROOT="$HOME/Install/simgrid/" # change it to the path where you installed the SimGrid library
-$ export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:+$LD_LIBRARY_PATH:}$SIMGRID_ROOT/lib
-~~~~
-
-Add these lines to your `~/.bashrc` file or equivalent to make these
-settings permanent even after a reboot.
-
-** **pthread_create failed**
-
-You reached the amount of threads that can be run on your system. Try
-increasing the thread limits of your operating system.
-
-If you manage to get it working, you could also switch to the Java
-co-routines (see @ref bindings_java_coro_install). Unfortunately,
-nobody used them since a few years, so they may well be broken by now.
-
-** **Other errors**
-
-When using jMSG, your program can crash for 3 main reasons:
-- Your Java part is not good: you'll have a good old java exception thrown,
-  and hence you should be able to correct it by yourself.
-- Our java part is not good: you'll also have a java exception thrown, but
-  we have real doubts this can happen, since the java part is only a JNI
-  binding. The other option is that it crashed because you used incorrectly
-  the MSG API, so this means also you should have an MSGException. It means
-  you should read carefully MSG samples and/or documentation.
-- Something has crashed in the C part. Okay, here comes the tricky
-  thing. It happens mainly for 2 reasons:
-  - When something goes wrong in your simulation, sometimes the C part stops
-    because you used SimGrid incorrectly, and JNI bindings are not fond of that.
-    It means that you'll have something that looks ugly, but you should be able
-    to identify what's going wrong in your code by carefully reading the whole
-    error message
-  - It may happen that the problem comes directly from SimGrid: in this case,
-    the error should be uglier. In that case, you may submit a bug directly to
-    SimGrid.
-
-@section java_coroutines Java bindings on Steroids
-
-<b>THIS SECTION IS SOMEWHAT OBSOLETE</b> because building a JVM
-providing coroutines is probably not possible anymore nowadays. If you
-really need performance for your Java simulation, please contact us.
-
-There is two main motivations to use the coroutine variant of SimGrid
-Java bindings: it's about 5 times faster than the default thread-based
-context factory, and the amount of runnable processes is then only
-limited by the amount of RAM that you have. The drawbacks are that it
-requires a specific and rather experimental JVM to run, and that this
-context factory itself remains a bit experimental so far.
-
-@subsection  bindings_java_coro_install Getting a mlvm JVM
-
-You need to get a patched JVM from [here](http://ssw.jku.at/General/Staff/LS/coro/)
-(many thanks to Lukas Stadler for this work!).
-
-You can either get a prebuilt binary, or recompile your own JVM. Make
-sure to get a coro-simple version, as we don't need to serialize nor
-migrate stacks in SimGrid. You should be able to follow the `README.txt`
-that you'll get in the repository, but here is how we did it, just in
-case. The instructions are given for a debian or Ubuntu box, but I
-think you should manage to convert it to your system quite easily.
-Finally, if you're really stuck, you can get the version compiled by
-Jonathan Rouzaud-Cornabas from his web page. This version is known to
-work with SimGrid for sure!
-http://graal.ens-lyon.fr/~jrouzaud/files/corosimple-linux-amd64-20120914.tgz
-
- -# Install mercurial and some dependencies
-~~~~{.sh}
-sudo apt-get install mercurial ksh libfreetype6-dev libcups2-dev libasound2-dev gawk openjdk-7-jdk libxext-dev libxrender-dev libxtst-dev
-# Grab the forest extension: we need to source-install it
-hg clone https://bitbucket.org/gxti/hgforest hgforest
-~~~~
- -# Configure the mercurial extensions: Edit ~/.hgrc and paste the
-    following lines. Don't forget to change the /path/to/forest.py to
-    point to where you just downloaded the source.
-
-    Forest extension is needed to download the openjdk source code and
-    patches while the mq line is needed to apply the patches. The
-    username is needed at the step "preparing the sources", not sure why.
-~~~~
-[ui]
-username = YouUserameWithoutSpaces
-[extensions]
-forest=/path/to/forest.py
-mq=
-~~~~
- -# Prepare the source code
-~~~~{.sh}
-# create a working directory, and enter it
-mkdir davinci; cd davinci
-
-# Grab the sources
-hg fclone http://hg.openjdk.java.net/hsx/hotspot-comp sources
-# Grab the patches
-hg fclone http://hg.openjdk.java.net/mlvm/mlvm patches
-
-# Link the patch directories into the sources
-bash patches/make/link-patch-dirs.sh sources patches
-# Test wether the previous command worked with
-ls -i patches/hotspot/series sources/hotspot/.hg/patches/series
-# It should display something like the following.
-# (note that both file share the same inode number)
-#  9707849 patches/hotspot/series
-#  9707849 sources/hotspot/.hg/patches/series
-
-# Specify what to compile.
-export davinci=${pwd} guards="buildable testable coro-simple"
-# Apply the patches
-sh patches/make/each-patch-repo.sh hg qselect --reapply $guards `sh $davinci/patches/make/current-release.sh`
-# Check that it understood that you want the patch applied:
-grep -r GLOBAL_GUARDS patches/make/
-# this should display something like the following (maybe amonst other unrelated lines)
-# GLOBAL_GUARDS=buildable testable coro-simple
-# If this does not work, edit patches/make/Makefile,
-#   manually coro-simple to GLOBAL_GUARDS and then
-#   rerun the patches/make/each-patch-repo.sh script as earlier
-
-
-# Finish the setup
-cd patches/make;
-make setup && make force && make && make FORCE_VERSIONS=1 && echo "Sources are properly setup"
-# If this last command failed, check your mercurial config within ~/.hgrc (see above)
-~~~~
- -# Compile it all
-~~~~{.sh}
-unset LD_LIBRARY_PATH
-export ALT_BOOTDIR=/usr/lib/jvm/java-7-openjdk-amd64/
-cd sources
-# Check that everything is fine
-make sanity
-# Go for it (it takes about half an hour on my machine)
-make all
-
-# Check that the coroutine library got compiled in
-ls sources/build/linux-amd64/classes/java/dyn/
-# This should display a bunch of class files. If not, something went wrong, you need to investigate further
-~~~~
-
-@subsection  bindings_java_coro_use Using coroutine contexts
-
-SimGrid Java will automatically switch to the coroutine context
-factory if your JVM support it, so you will just need to execute your
-simulation with the correct JVM. The selected context factory gets
-displayed automatically.
-~~~~{.sh}
-export LD_LIBRARY_PATH=/path/to/simgrid.so:/path/to/libsimgrid-java.so
-cd examples
-$PATH_TO_COROUTINE_JVM/java -classpath .:../simgrid.jar masterslave.Masterslave masterslave/ masterslaveDeployment.xml platform.xml
-~~~~
-
-Note that you may have to adjust the "coro.stacksPerThread"
-configuration option to run large simulations. The default is 100 and
-you want to increase it to run more processes.
-~~~~{.sh}
-$ $PATH_TO_COROUTINE_JVM/java -Dcoro.stacksPerThread=$STACKS_NUMBER -classpath .:../simgrid.jar basic/BasicTest platform.xml basic/basicDeployment.xml
-~~~~
-
-If you reach the point where the creation of new simulated processes
-fail with the message "Can't create coroutine object", you may need to
-increase the relevant system limit with the following command.
-~~~~{.sh}
-sysctl -w vm.max_map_count = 131072
-~~~~
-
-The full story is that each coroutine requires two memory maps, and
-that Linux puts a limit on the total amount of memory maps that each
-process can manage (by default, this limit is often at 65535). Since
-the JVM needs a few dozen of such maps on its own (three maps per
-dynamic library -- check `/proc/the_pid/maps` if you don't believe it),
-this is enough to create over 30,000 simulated processes. But to go
-futher, that limit must be modified.
-
-If you want to make this change permanent on your machine, edit your
-`/etc/sysctl.conf` file. Otherwise, you have to redo it by calling
-sysctl after each reboot.
-
- */
diff --git a/doc/doxygen/module-msg.doc b/doc/doxygen/module-msg.doc
deleted file mode 100644 (file)
index 5f3c420..0000000
+++ /dev/null
@@ -1,105 +0,0 @@
-/**
-@defgroup MSG_API  MSG: Legacy handling of CSP algorithms
-@brief Simple programming environment
-
-
-MSG is a simple API to write algorithms organized with Concurrent
-Sequential Processes (CSP) that interact by exchanging messages. It
-constitutes a convenient simplification of the reality of distributed
-systems. It can be used to build rather realistic simulations, but
-remains simple to use: most unpleasant technical elements can be
-abstracted away rather easily.
-
-@warning MSG used to be the main API of SimGrid 3, but we are
-        currently in the process of releasing SimGrid 4. The
-        tentative release date is Summer 2018. So MSG is frozen and
-        will probably never evolve. If you are starting a new
-        project, you should consider S4U instead. Note that the
-        support for MSG will not be removed from SimGrid before 2020
-        at least.
-
-@section MSG_funct Offered functionalities
-   - @ref msg_simulation
-   - @ref m_process_management
-   - @ref m_host_management
-   - @ref m_task_management
-   - @ref msg_mailbox_management
-   - @ref msg_file
-   - @ref msg_task_usage
-   - @ref msg_VMs
-   - @ref msg_synchro
-   - @ref msg_examples
-
-*/ 
-
-/**
-@defgroup msg_simulation   Main MSG simulation Functions
-@ingroup MSG_API
-@brief How to setup and control your simulation.
-
-The basic workflow is the following (check the @ref msg_examples for
-details).
-
- -# Initialize the library with #MSG_init
- -# Create a platform (usually by parsing a file with
-    #MSG_create_environment)
- -# Register the functions that your processes are supposed to run with
-    #MSG_function_register (and maybe #MSG_function_register_default)
- -# Launch your processes from a deployment file with #MSG_launch_application
- -# Run the simulation with #MSG_main
-*/
-
-/** @defgroup m_process_management Process Management Functions
- *  @ingroup MSG_API
- *  @brief This section describes the process structure of MSG
- *         (#msg_process_t) and the functions for managing it.
- */
-
-/** @defgroup m_host_management Host Management Functions
- *  @ingroup MSG_API
- *  @brief Host structure of MSG
- */
-
-/** @defgroup m_task_management Task Management Functions
- *  @ingroup MSG_API
- *  @brief Task structure of MSG (#msg_task_t) and associated functions. See
- *         @ref msg_task_usage to see how to put the tasks in action.
- */
-
-/** @defgroup msg_mailbox_management Mailbox Management Functions
- *  @ingroup MSG_API
- *  @brief Functions associated to mailboxes.
- */
-
-/** @defgroup msg_task_usage Task Actions
- *  @ingroup MSG_API
- *  @brief This section describes the functions that can be used
- *         by a process to execute, communicate or otherwise handle some task.
- */
-
-/** @defgroup msg_synchro Explicit Synchronization Functions
- *  @ingroup MSG_API
- *  @brief Explicit synchronization mechanisms: semaphores (#msg_sem_t) and friends.
- *
- * In some situations, these things are very helpful to synchronize processes without message exchanges.
- */
-
-/** @defgroup msg_VMs VMs
- *  @ingroup MSG_API
- *  @brief Interface created to mimic IaaS clouds.
- *
- *  With it, you can create virtual machines to put your processes
- *  into, and interact directly with the VMs to manage groups of
- *  processes.
- *
- */
-
-/** @defgroup msg_storage_management Storage Management Functions
- *  @ingroup MSG_API
- *  @brief Storage structure of MSG (#msg_storage_t) and associated functions, inspired from POSIX.
- */
-
-/** @defgroup msg_file File Management Functions
-    @ingroup MSG_API
-    @brief MSG files (#msg_file_t) and associated functions, inspired from POSIX.
-*/
index e39cf57..9bc5a26 100755 (executable)
@@ -16,3 +16,22 @@ cat source/img/graphical-toc.svg \
  | perl -pe 's/(xlink:href="http)/target="_top" $1/' \
  | perl -pe 's/(xlink:href=".*?.html)/target="_top" $1/' \
  > build/html/graphical-toc.svg
+
+
+echo "List of missing references:"
+for f in `(grep '<name>' build/xml/msg_8h.xml; \
+           grep '<name>' build/xml/namespacesimgrid_1_1s4u.xml; \
+          grep '<innerclass refid=' build/xml/namespacesimgrid_1_1s4u.xml) |sed 's/<[^>]*>//g'|sort` 
+do
+
+  if grep $f source/*rst | grep -q '.. doxygen[^::]*:: '"$f"'$' ||
+     grep $f source/*rst | grep -q '.. doxygen[^::]*:: simgrid::[^:]*::[^:]*::'"$f"'$'  ; then :   
+#    echo "$f documented"
+  else 
+    if grep -q $f ignored_symbols ; then : 
+#      echo "$f ignored" # not documented
+    else
+      echo "$f"
+    fi
+  fi
+done
\ No newline at end of file
diff --git a/docs/ignored_symbols b/docs/ignored_symbols
new file mode 100644 (file)
index 0000000..d72c68d
--- /dev/null
@@ -0,0 +1,17 @@
+# Used by Build.sh
+MIN
+MAX
+SG_BEGIN_DECL
+msg_as_t
+MSG_OK
+MSG_HOST_FAILURE
+MSG_TASK_CANCELED
+MSG_TIMEOUT
+MSG_TRANSFER_FAILURE
+sg_msg_Comm
+simdata_task_t
+s_msg_task_t
+MSG_init_nocheck
+intrusive_ptr_release
+intrusive_ptr_add_ref
+get_filtered_netzones_recursive
index 06760f5..d8a862e 100644 (file)
@@ -2,6 +2,8 @@
 INPUT                  = ../../include/simgrid/forward.h
 INPUT                 += ../../include/simgrid/s4u
 INPUT                 += ../../include/simgrid/xbt
+INPUT                 += ../../include/simgrid/msg.h
+INPUT                 += ../../src/msg/
 RECURSIVE              = YES
 
 # What to produce
diff --git a/docs/source/app_java.rst b/docs/source/app_java.rst
new file mode 100644 (file)
index 0000000..067726d
--- /dev/null
@@ -0,0 +1,108 @@
+.. _Java_doc:
+
+=================
+The Java Bindings
+=================
+
+.. raw:: html
+
+   <object id="TOC" data="graphical-toc.svg" width="100%" 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("S4UBox")
+     //elem.style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1";
+   }
+   </script>
+   <br/>
+   <br/>
+
+   
+This section describes jMSG, the Java API to Simgrid. This API mimicks 
+:ref:`MSG <MSG_doc>`, which is a simple yet somehow realistic interface.
+<b>The full [javadoc](javadoc/index.html) is available.</b>
+
+Most of the documentation of the :ref:`MSG API <MSG_doc>` in C applies
+directly to the Java bindings (any divergence is seen as a bug that we
+should fix). MSG structures are mapped to Java objects as expected,
+and the MSG functions are methods in these objects.
+
+How to install the Java bindings
+--------------------------------
+
+The easiest is to use a :ref:`precompiled jarfile <install_java_precompiled>`,
+but some people may prefer to :ref:`compile it from the sources <install_src>`.
+
+
+How to use the Java bindings
+----------------------------
+
+In most cases, you can use the SimGrid bindings as if it was a Java
+library:
+
+.. code-block:: shell
+
+   $ javac -classpath .:path/to/simgrid.jar your/java/Code.java
+   $ java -classpath .:path/to/simgrid.jar your.java.Code the/parameter/to/your/code
+
+For example:
+
+.. code-block:: shell
+
+   $ cd examples/java
+   $ java -classpath ../../simgrid.jar:. .:../../simgrid.jar app.pingpong.Main ../platforms/platform.xml 
+
+Any SimGrid simulation (java or not) is usually constituted of several
+kind of actors or processes (classes extending @c Msg.Process) that
+are deployed over the hosts of the virtual platform. So, your code
+should declare these actors, plus a Main class in charge of deploying
+your actors on the platform. Please refer to the examples for details.
+
+Troubleshooting
+---------------
+
+Actually, these bindings are not only implemented in Java. They do use
+the C implementation of SimGrid. This should be transparent as this
+library is directly included in the ``simgrid.jar`` file but things can
+still go wrong is several ways.
+
+Error: library simgrid not found
+................................
+
+This means that the JVM fails to load the native library. If you use a
+precompiled jarfile, please report this bug.
+
+If you built it yourself, you can try to use an installed version of
+the library instead of the one included in the jar. For that, add the
+path to the native library into the ``LD_LIBRARY_PATH`` variable (or in
+the ``DYLD_LIBRARY_PATH`` on Mac OSX).
+
+pthread_create failed
+.....................
+
+You reached the amount of threads that can be run on your system. Try
+increasing the thread limits of your operating system.
+
+Other errors
+............
+
+When using jMSG, your program can crash for 3 main reasons:
+
+- Your Java part is not good: you'll have a good old java exception thrown,
+  and hence you should be able to correct it by yourself.
+- Our java part is not good: you'll also have a java exception thrown, but
+  we have real doubts this can happen, since the java part is only a JNI
+  binding. The other option is that it crashed because you used incorrectly
+  the MSG API, so this means also you should have an MSGException. It means
+  you should read carefully MSG samples and/or documentation.
+- Something has crashed in the C part. Okay, here comes the tricky
+  thing. It happens mainly for 2 reasons:
+  
+  - When something goes wrong in your simulation, sometimes the C part stops
+    because you used SimGrid incorrectly, and JNI bindings are not fond of that.
+    It means that you'll have something that looks ugly, but you should be able
+    to identify what's going wrong in your code by carefully reading the whole
+    error message
+  - It may happen that the problem comes directly from SimGrid: in this case,
+    the error should be uglier. In that case, you may submit a bug directly to
+    SimGrid.
+
diff --git a/docs/source/app_msg.rst b/docs/source/app_msg.rst
new file mode 100644 (file)
index 0000000..e3ca7e7
--- /dev/null
@@ -0,0 +1,288 @@
+.. _MSG_doc:
+
+====================================
+The MSG Interface (legacy interface)
+====================================
+
+.. raw:: html
+
+   <object id="TOC" data="graphical-toc.svg" width="100%" 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("S4UBox")
+     //elem.style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1";
+   }
+   </script>
+   <br/>
+   <br/>
+
+MSG is a simple API to write algorithms organized with Concurrent
+Sequential Processes (CSP) that interact by exchanging messages. It
+constitutes a convenient simplification of the reality of distributed
+systems. It can be used to build rather realistic simulations, but
+remains simple to use: most unpleasant technical elements can be
+abstracted away rather easily.
+
+.. warning::
+
+   MSG used to be the main API of SimGrid 3, but we are currently in
+   the process of releasing SimGrid 4. So MSG is frozen and will
+   probably never evolve. If you are starting a new project, you
+   should consider S4U instead. Note that the support for MSG will not
+   be removed from SimGrid before 2020 at least.
+
+Main MSG Functions
+------------------
+
+The basic workflow is the following:
+
+ - Initialize the library with :c:macro:`MSG_init`
+ - Create a platform (usually by parsing a file with :cpp:func:`MSG_create_environment`)
+ - Register the functions that your processes are supposed to run with
+   :cpp:func:`MSG_function_register` (and maybe :cpp:func:`MSG_function_register_default`) 
+ - Launch your processes from a deployment file with :cpp:func:`MSG_launch_application`
+ - Run the simulation with :cpp:func:`MSG_main`
+
+.. doxygenenum:: msg_error_t
+
+.. doxygenfunction:: MSG_config
+.. doxygenfunction:: MSG_create_environment
+.. doxygenfunction:: MSG_function_register
+.. doxygenfunction:: MSG_function_register_default
+.. doxygenfunction:: MSG_get_clock
+.. doxygenfunction:: MSG_get_sent_msg
+.. doxygendefine:: MSG_init
+.. doxygenfunction:: MSG_launch_application
+.. doxygenfunction:: MSG_main
+.. doxygenfunction:: MSG_set_function
+
+Process Management Functions
+----------------------------
+
+This describes the process structure :cpp:type:`msg_process_t` and the functions for managing it.
+
+.. doxygentypedef:: msg_process_t
+.. doxygenfunction:: MSG_process_attach
+.. doxygenfunction:: MSG_process_auto_restart_set
+.. doxygenfunction:: MSG_process_create
+.. doxygenfunction:: MSG_process_create_with_arguments
+.. doxygenfunction:: MSG_process_create_with_environment
+.. doxygenfunction:: MSG_process_create_from_stdfunc
+.. doxygenfunction:: MSG_process_daemonize
+.. doxygenfunction:: MSG_process_detach
+.. doxygenfunction:: MSG_processes_as_dynar
+.. doxygenfunction:: MSG_process_from_PID
+.. doxygenfunction:: MSG_process_get_data
+.. doxygenfunction:: MSG_process_get_host
+.. doxygenfunction:: MSG_process_get_name
+.. doxygenfunction:: MSG_process_get_number
+.. doxygenfunction:: MSG_process_get_PID
+.. doxygenfunction:: MSG_process_get_PPID
+.. doxygenfunction:: MSG_process_get_properties
+.. doxygenfunction:: MSG_process_get_property_value
+.. doxygenfunction:: MSG_process_get_smx_ctx
+.. doxygenfunction:: MSG_process_is_suspended
+.. doxygenfunction:: MSG_process_join
+.. doxygenfunction:: MSG_process_kill
+.. doxygenfunction:: MSG_process_killall
+.. doxygenfunction:: MSG_process_migrate
+.. doxygenfunction:: MSG_process_on_exit
+.. doxygenfunction:: MSG_process_ref
+.. doxygenfunction:: MSG_process_restart
+.. doxygenfunction:: MSG_process_resume
+.. doxygenfunction:: MSG_process_self
+.. doxygenfunction:: MSG_process_self_name
+.. doxygenfunction:: MSG_process_self_PID
+.. doxygenfunction:: MSG_process_self_PPID
+.. doxygenfunction:: MSG_process_set_data
+.. doxygenfunction:: MSG_process_set_data_cleanup
+.. doxygenfunction:: MSG_process_set_kill_time
+.. doxygenfunction:: MSG_process_sleep
+.. doxygenfunction:: MSG_process_suspend
+.. doxygenfunction:: MSG_process_unref
+.. doxygenfunction:: MSG_process_yield
+
+Host Management Functions
+-------------------------
+
+.. doxygentypedef:: msg_host_t
+.. doxygenfunction:: MSG_host_by_name
+.. doxygenfunction:: MSG_get_host_by_name
+.. doxygenfunction:: MSG_get_host_number
+.. doxygenfunction:: MSG_host_get_attached_storage_lists
+.. doxygenfunction:: MSG_host_get_core_number
+.. doxygenfunction:: MSG_host_get_data
+.. doxygenfunction:: MSG_host_get_mounted_storage_list
+.. doxygenfunction:: MSG_host_get_name
+.. doxygenfunction:: MSG_host_get_nb_pstates
+.. doxygenfunction:: MSG_host_get_power_peak_at
+.. doxygenfunction:: MSG_host_get_process_list
+.. doxygenfunction:: MSG_host_get_properties
+.. doxygenfunction:: MSG_host_get_property_value
+.. doxygenfunction:: MSG_host_get_pstate
+.. doxygenfunction:: MSG_host_get_speed
+.. doxygenfunction:: MSG_host_is_off
+.. doxygenfunction:: MSG_host_is_on
+.. doxygenfunction:: MSG_host_off
+.. doxygenfunction:: MSG_host_on
+.. doxygenfunction:: MSG_hosts_as_dynar
+.. doxygenfunction:: MSG_host_self
+.. doxygenfunction:: MSG_host_set_data
+.. doxygenfunction:: MSG_host_set_property_value
+.. doxygenfunction:: MSG_host_set_pstate
+
+Task Management Functions
+-------------------------
+
+Task structure of MSG :cpp:type:`msg_task_t` and associated functions.
+
+.. doxygentypedef:: msg_task_t
+.. doxygendefine:: MSG_TASK_UNINITIALIZED
+
+.. doxygenfunction:: MSG_parallel_task_create
+.. doxygenfunction:: MSG_parallel_task_execute
+.. doxygenfunction:: MSG_parallel_task_execute_with_timeout
+.. doxygenfunction:: MSG_task_cancel
+.. doxygenfunction:: MSG_task_create
+.. doxygenfunction:: MSG_task_destroy
+.. doxygenfunction:: MSG_task_dsend
+.. doxygenfunction:: MSG_task_dsend_bounded
+.. doxygenfunction:: MSG_task_execute
+.. doxygenfunction:: MSG_task_get_bytes_amount
+.. doxygenfunction:: MSG_task_get_category
+.. doxygenfunction:: MSG_task_get_data
+.. doxygenfunction:: MSG_task_get_flops_amount
+.. doxygenfunction:: MSG_task_get_name
+.. doxygenfunction:: MSG_task_get_remaining_communication
+.. doxygenfunction:: MSG_task_get_remaining_work_ratio
+.. doxygenfunction:: MSG_task_get_sender
+.. doxygenfunction:: MSG_task_get_source
+.. doxygenfunction:: MSG_task_irecv
+.. doxygenfunction:: MSG_task_irecv_bounded
+.. doxygenfunction:: MSG_task_isend
+.. doxygenfunction:: MSG_task_isend_bounded
+.. doxygenfunction:: MSG_task_listen
+.. doxygenfunction:: MSG_task_listen_from
+.. doxygenfunction:: MSG_task_receive
+.. doxygenfunction:: MSG_task_receive_bounded
+.. doxygenfunction:: MSG_task_receive_ext
+.. doxygenfunction:: MSG_task_receive_ext_bounded
+.. doxygenfunction:: MSG_task_receive_with_timeout
+.. doxygenfunction:: MSG_task_receive_with_timeout_bounded
+.. doxygenfunction:: MSG_task_recv
+.. doxygenfunction:: MSG_task_recv_bounded
+.. doxygenfunction:: MSG_task_send
+.. doxygenfunction:: MSG_task_send_bounded
+.. doxygenfunction:: MSG_task_send_with_timeout
+.. doxygenfunction:: MSG_task_send_with_timeout_bounded
+.. doxygenfunction:: MSG_task_set_bound
+.. doxygenfunction:: MSG_task_set_bytes_amount
+.. doxygenfunction:: MSG_task_set_category
+.. doxygenfunction:: MSG_task_set_copy_callback
+.. doxygenfunction:: MSG_task_set_data
+.. doxygenfunction:: MSG_task_set_flops_amount
+.. doxygenfunction:: MSG_task_set_name
+.. doxygenfunction:: MSG_task_set_priority
+
+                  
+Mailbox Management Functions
+----------------------------
+
+.. doxygenfunction:: MSG_mailbox_set_async
+
+Communications
+--------------
+
+.. doxygentypedef:: msg_comm_t
+
+.. doxygenfunction:: MSG_comm_destroy
+.. doxygenfunction:: MSG_comm_get_status
+.. doxygenfunction:: MSG_comm_get_task
+.. doxygenfunction:: MSG_comm_test
+.. doxygenfunction:: MSG_comm_testany
+.. doxygenfunction:: MSG_comm_wait
+.. doxygenfunction:: MSG_comm_waitall
+.. doxygenfunction:: MSG_comm_waitany
+
+Explicit Synchronization Functions
+----------------------------------
+
+Explicit synchronization mechanisms: semaphores (:cpp:type:`msg_sem_t`) and friends.
+
+In some situations, these things are very helpful to synchronize processes without message exchanges.
+
+Barriers
+........
+
+.. doxygentypedef:: msg_bar_t
+.. doxygenfunction:: MSG_barrier_destroy
+.. doxygenfunction:: MSG_barrier_init
+.. doxygenfunction:: MSG_barrier_wait
+
+Semaphores
+..........
+                    
+.. doxygentypedef:: msg_sem_t
+.. doxygenfunction:: MSG_sem_acquire
+.. doxygenfunction:: MSG_sem_acquire_timeout
+.. doxygenfunction:: MSG_sem_destroy
+.. doxygenfunction:: MSG_sem_get_capacity
+.. doxygenfunction:: MSG_sem_init
+.. doxygenfunction:: MSG_sem_release
+.. doxygenfunction:: MSG_sem_would_block
+
+Virtual Machines
+----------------
+
+This interface mimics IaaS clouds.
+With it, you can create virtual machines to put your processes
+into, and interact directly with the VMs to manage groups of
+processes.
+
+.. doxygentypedef:: msg_vm_t
+.. doxygenfunction:: MSG_vm_create
+.. doxygenfunction:: MSG_vm_create_core
+.. doxygenfunction:: MSG_vm_create_multicore
+.. doxygenfunction:: MSG_vm_destroy
+.. doxygenfunction:: MSG_vm_get_name
+.. doxygenfunction:: MSG_vm_get_pm
+.. doxygenfunction:: MSG_vm_get_ramsize
+.. doxygenfunction:: MSG_vm_is_created
+.. doxygenfunction:: MSG_vm_is_running
+.. doxygenfunction:: MSG_vm_is_suspended
+.. doxygenfunction:: MSG_vm_resume
+.. doxygenfunction:: MSG_vm_set_bound
+.. doxygenfunction:: MSG_vm_set_ramsize
+.. doxygenfunction:: MSG_vm_shutdown
+.. doxygenfunction:: MSG_vm_start
+.. doxygenfunction:: MSG_vm_suspend
+
+Storage Management Functions
+----------------------------
+Storage structure of MSG (:cpp:type:`msg_storage_t`) and associated functions, inspired from POSIX.
+
+.. doxygentypedef:: msg_storage_t
+.. doxygenfunction:: MSG_storage_get_by_name
+.. doxygenfunction:: MSG_storage_get_data
+.. doxygenfunction:: MSG_storage_get_host
+.. doxygenfunction:: MSG_storage_get_name
+.. doxygenfunction:: MSG_storage_get_properties
+.. doxygenfunction:: MSG_storage_get_property_value
+.. doxygenfunction:: MSG_storage_read
+.. doxygenfunction:: MSG_storages_as_dynar
+.. doxygenfunction:: MSG_storage_set_data
+.. doxygenfunction:: MSG_storage_set_property_value
+.. doxygenfunction:: MSG_storage_write
+
+Zone Management Functions
+-------------------------
+Network Zone (:cpp:class:`msg_file_t`) and associated functions.
+
+.. doxygentypedef:: msg_netzone_t
+.. doxygenfunction:: MSG_zone_get_by_name
+.. doxygenfunction:: MSG_zone_get_hosts
+.. doxygenfunction:: MSG_zone_get_name
+.. doxygenfunction:: MSG_zone_get_property_value
+.. doxygenfunction:: MSG_zone_get_root
+.. doxygenfunction:: MSG_zone_get_sons
+.. doxygenfunction:: MSG_zone_set_property_value
index 8d4ec2b..71da01b 100644 (file)
@@ -1,8 +1,7 @@
 .. _S4U_doc:
 
-=================
 The S4U Interface
-=================
+#################
 
 .. raw:: html
 
@@ -31,16 +30,13 @@ the old symbols.
 If you want an API that will never ever evolve in the future, you
 should use the deprecated MSG API instead. 
 
--------------
 Main Concepts
--------------
+*************
 
 A typical SimGrid simulation is composed of several |Actors|_, that
 execute user-provided functions. The actors have to explicitly use the
-S4U interface to express their
-:ref:`computation <exhale_class_classsimgrid_1_1s4u_1_1Exec>`,
-:ref:`communication <exhale_class_classsimgrid_1_1s4u_1_1Comm>`,
-:ref:`disk usage <exhale_class_classsimgrid_1_1s4u_1_1Io>`,
+S4U interface to express their :ref:`computation <API_s4u_Exec>`,
+:ref:`communication <API_s4u_Comm>`, :ref:`disk usage <API_s4u_Io>`,
 and other |Activities|_, so that they get reflected within the
 simulator. These activities take place on resources such as |Hosts|_,
 |Links|_ and |Storages|_. SimGrid predicts the time taken by each
@@ -68,42 +64,42 @@ functions to simplify the code of actors.
 
 - **Global Classes**
 
-  - :ref:`class s4u::Actor <exhale_class_classsimgrid_1_1s4u_1_1Actor>`:
+  - :ref:`class s4u::Actor <API_s4u_Actor>`:
     Active entities executing your application.
-  - :ref:`class s4u::Engine <exhale_class_classsimgrid_1_1s4u_1_1Engine>`
+  - :ref:`class s4u::Engine <API_s4u_Engine>`
     Simulation engine (singleton).
-  - :ref:`class s4u::Mailbox <exhale_class_classsimgrid_1_1s4u_1_1Mailbox>`
+  - :ref:`class s4u::Mailbox <API_s4u_Mailbox>`
     Communication rendez-vous.
 
 - **Platform Elements**
 
-  - :ref:`class s4u::Host <exhale_class_classsimgrid_1_1s4u_1_1Host>`:
+  - :ref:`class s4u::Host <API_s4u_Host>`:
     Actor location, providing computational power.
-  - :ref:`class s4u::Link <exhale_class_classsimgrid_1_1s4u_1_1Link>`
+  - :ref:`class s4u::Link <API_s4u_Link>`
     Interconnecting hosts.
-  - :ref:`class s4u::NetZone <exhale_class_classsimgrid_1_1s4u_1_1NetZone>`:
+  - :ref:`class s4u::NetZone <API_s4u_NetZone>`:
     Sub-region of the platform, containing resources (Hosts, Links, etc).
-  - :ref:`class s4u::Storage <exhale_class_classsimgrid_1_1s4u_1_1Storage>`
+  - :ref:`class s4u::Storage <API_s4u_Storage>`
     Resource on which actors can write and read data.
-  - :ref:`class s4u::VirtualMachine <exhale_class_classsimgrid_1_1s4u_1_1VirtualMachine>`:
+  - :ref:`class s4u::VirtualMachine <API_s4u_VirtualMachine>`:
     Execution containers that can be moved between Hosts.
 
-- **Activities** (:ref:`class s4u::Activity <exhale_class_classsimgrid_1_1s4u_1_1Activity>`):
+- **Activities** (:ref:`class s4u::Activity <API_s4u_Activity>`):
   The things that actors can do on resources
 
-  - :ref:`class s4u::Comm <exhale_class_classsimgrid_1_1s4u_1_1Comm>`
+  - :ref:`class s4u::Comm <API_s4u_Comm>`
     Communication activity, started on Mailboxes and consuming links.
-  - :ref:`class s4u::Exec <exhale_class_classsimgrid_1_1s4u_1_1Exec>`
+  - :ref:`class s4u::Exec <API_s4u_Exec>`
     Computation activity, started on Host and consuming CPU resources.
-  - :ref:`class s4u::Io <exhale_class_classsimgrid_1_1s4u_1_1Io>`
+  - :ref:`class s4u::Io <API_s4u_Io>`
     I/O activity, started on and consumming Storages.
 
 - **Synchronization Mechanisms**: Classical IPC that actors can use
 
-  - :ref:`class s4u::Barrier <exhale_class_classsimgrid_1_1s4u_1_1Barrier>`
-  - :ref:`class s4u::ConditionVariable <exhale_class_classsimgrid_1_1s4u_1_1ConditionVariable>`
-  - :ref:`class s4u::Mutex <exhale_class_classsimgrid_1_1s4u_1_1Mutex>`
-  - :ref:`class s4u::Semaphore <exhale_class_classsimgrid_1_1s4u_1_1Semaphore>`
+  - :ref:`class s4u::Barrier <API_s4u_Barrier>`
+  - :ref:`class s4u::ConditionVariable <API_s4u_ConditionVariable>`
+  - :ref:`class s4u::Mutex <API_s4u_Mutex>`
+  - :ref:`class s4u::Semaphore <API_s4u_Semaphore>`
 
 
 .. |Actors| replace:: **Actors**
@@ -146,18 +142,16 @@ functions to simplify the code of actors.
 
 .. include:: ../../examples/s4u/README.rst
 
-----------
 Activities
-----------
+**********
 
 Activities represent the actions that consume a resource, such as a
-:ref:`s4u::Comm <exhale_class_classsimgrid_1_1s4u_1_1Comm>` that
-consumes the *transmiting power* of :ref:`s4u::Link
-<exhale_class_classsimgrid_1_1s4u_1_1Link>` resources.
+:ref:`s4u::Comm <API_s4u_Comm>` that consumes the *transmiting power* of
+:ref:`s4u::Link <API_s4u_Link>` resources.
 
-.......................
+=======================
 Asynchronous Activities
-.......................
+=======================
 
 Every activity can be either **blocking** or **asynchronous**. For
 example, :cpp:func:`s4u::Mailbox::put() <simgrid::s4u::Mailbox::put>`
@@ -181,13 +175,13 @@ Finally, to wait at most until a specified time limit, use
 
 Every kind of activities can be asynchronous:
 
-  - :ref:`s4u::CommPtr <exhale_class_classsimgrid_1_1s4u_1_1Comm>` are created with 
+  - :ref:`s4u::CommPtr <API_s4u_Comm>` are created with 
     :cpp:func:`s4u::Mailbox::put_async() <simgrid::s4u::Mailbox::put_async>` and
     :cpp:func:`s4u::Mailbox::get_async() <simgrid::s4u::Mailbox::get_async>`.
-  - :ref:`s4u::IoPtr <exhale_class_classsimgrid_1_1s4u_1_1Io>` are created with 
+  - :ref:`s4u::IoPtr <API_s4u_Io>` are created with 
     :cpp:func:`s4u::Storage::read_async() <simgrid::s4u::Storage::read_async>` and
     :cpp:func:`s4u::Storage::write_async() <simgrid::s4u::Storage::write_async>`.    
-  - :ref:`s4u::ExecPtr <exhale_class_classsimgrid_1_1s4u_1_1Exec>` are created with
+  - :ref:`s4u::ExecPtr <API_s4u_Exec>` are created with
     :cpp:func:`s4u::Host::exec_async() <simgrid::s4u::Host::exec_async>`.
   - In the future, it will become possible to have asynchronous IPC
     such as asynchronous mutex lock requests.
@@ -216,17 +210,16 @@ with
    :dedent: 4
 
 
-.....................
+=====================
 Activities Life cycle
-.....................
+=====================
 
 Sometimes, you want to change the setting of an activity before it even starts. 
 
 .. todo:: write this section
 
------------------
 Memory Management
------------------
+*****************
 
 For sake of simplicity, we use `RAII
 <https://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization>`_
@@ -251,3 +244,209 @@ Here is a little example:
      mutex->unlock(); 
   
    } // The mutex gets automatically freed because the only existing reference gets out of scope
+
+API Reference
+*************
+
+.. _API_s4u_Activity:
+
+=============
+s4u::Activity
+=============
+
+.. doxygenclass:: simgrid::s4u::Activity
+   :members:
+   :protected-members:
+   :undoc-members:
+
+.. _API_s4u_Actor:
+
+==========
+s4u::Actor
+==========
+
+.. doxygentypedef:: ActorPtr
+
+.. doxygenclass:: simgrid::s4u::Actor
+   :members:
+   :protected-members:
+   :undoc-members:
+
+.. _API_s4u_Barrier:
+
+============
+s4u::Barrier
+============
+
+.. doxygentypedef:: BarrierPtr
+
+.. doxygenclass:: simgrid::s4u::Barrier
+   :members:
+   :protected-members:
+   :undoc-members:
+
+.. _API_s4u_Comm:
+
+=========
+s4u::Comm
+=========
+
+.. doxygentypedef:: CommPtr
+
+.. doxygenclass:: simgrid::s4u::Comm
+   :members:
+   :protected-members:
+   :undoc-members:
+
+.. _API_s4u_ConditionVariable:
+
+======================
+s4u::ConditionVariable
+======================
+
+.. doxygentypedef:: ConditionVariablePtr
+
+.. doxygenclass:: simgrid::s4u::ConditionVariable
+   :members:
+   :protected-members:
+   :undoc-members:
+
+.. _API_s4u_Engine:
+
+===========
+s4u::Engine
+===========
+
+.. doxygenclass:: simgrid::s4u::Engine
+   :members:
+   :protected-members:
+   :undoc-members:
+
+.. _API_s4u_Exec:
+
+=========
+s4u::Exec
+=========
+
+.. doxygentypedef:: ExecPtr
+
+.. doxygenclass:: simgrid::s4u::Exec
+   :members:
+   :protected-members:
+   :undoc-members:
+
+.. _API_s4u_Host:
+
+=========
+s4u::Host
+=========
+
+.. doxygenclass:: simgrid::s4u::Host
+   :members:
+   :protected-members:
+   :undoc-members:
+
+.. _API_s4u_Io:
+
+=======
+s4u::Io
+=======
+
+.. doxygentypedef:: IoPtr
+
+.. doxygenclass:: simgrid::s4u::Io
+   :members:
+   :protected-members:
+   :undoc-members:
+
+.. _API_s4u_Link:
+
+=========
+s4u::Link
+=========
+
+.. doxygenclass:: simgrid::s4u::Link
+   :members:
+   :protected-members:
+   :undoc-members:
+
+.. _API_s4u_Mailbox:
+
+============
+s4u::Mailbox
+============
+
+.. doxygentypedef:: MailboxPtr
+
+.. doxygenclass:: simgrid::s4u::Mailbox
+   :members:
+   :protected-members:
+   :undoc-members:
+
+.. _API_s4u_Mutex:
+
+==========
+s4u::Mutex
+==========
+
+.. doxygentypedef:: MutexPtr
+
+.. doxygenclass:: simgrid::s4u::Mutex
+   :members:
+   :protected-members:
+   :undoc-members:
+
+.. _API_s4u_NetZone:
+
+============
+s4u::NetZone
+============
+
+.. doxygenclass:: simgrid::s4u::NetZone
+   :members:
+   :protected-members:
+   :undoc-members:
+
+.. _API_s4u_Semaphore:
+
+==============
+s4u::Semaphore
+==============
+
+.. doxygentypedef:: SemaphorePtr
+
+.. doxygenclass:: simgrid::s4u::Semaphore
+   :members:
+   :protected-members:
+   :undoc-members:
+
+.. _API_s4u_Storage:
+
+============
+s4u::Storage
+============
+
+.. doxygenclass:: simgrid::s4u::Storage
+   :members:
+   :protected-members:
+   :undoc-members:
+
+.. _API_s4u_VirtualMachine:
+
+===================
+s4u::VirtualMachine
+===================
+
+.. doxygenclass:: simgrid::s4u::VirtualMachine
+   :members:
+   :protected-members:
+   :undoc-members:
+
+.. _API_s4u_this_actor:
+
+=========================
+namespace s4u::this_actor
+=========================
+
+
+.. doxygennamespace:: simgrid::s4u::this_actor
index 53e0f23..ade7f20 100644 (file)
@@ -98,6 +98,8 @@ usual.
    smpirun -wrapper valgrind ...other args...
    smpirun -wrapper "gdb --args" --cfg=contexts/factory:thread ...other args...
 
+.. _SMPI_use_colls:
+
 ................................   
 Simulating Collective Operations
 ................................
@@ -493,6 +495,8 @@ marker. If you really miss a feature, please get in touch with us: we
 can guide you though the SimGrid code to help you implementing it, and
 we'd be glad to integrate your contribution to the main project.
 
+.. _SMPI_what_globals:
+
 .................................
 Privatization of global variables
 .................................
index a70134e..350b49c 100644 (file)
@@ -50,8 +50,9 @@ release = u'3.21'
 extensions = [
     'sphinx.ext.todo',
     'breathe',
-    'exhale',
+#    'exhale',
     'hidden_code_block',
+#    'snooze', # must come after exhale
 ]
 
 todo_include_todos = True
index b2276d9..c5f5185 100644 (file)
@@ -21,9 +21,14 @@ Welcome to SimGrid's documentation!
    :caption: User Manual:
 
       Introduction <introduction.rst>
+         Main Concepts <intro_concepts.rst>
+         Installing SimGrid <intro_install.rst>
+         Start your Own Project <intro_yours.rst>
       Describing your Application <application.rst>
          The S4U Interface <app_s4u.rst>
          The SMPI Interface <app_smpi.rst>
+         The MSG Interface <app_msg.rst>
+         The Java Bindings <app_java.rst>
       Describing the Simulated Platform <platform.rst>
       Describing the Experimental Scenario <scenario.rst>
          Configuring SimGrid <scenar_config.rst>
@@ -33,9 +38,3 @@ Welcome to SimGrid's documentation!
       The SimGrid Community <community.rst>
       Frequently Asked Questions <faq.rst>
 
-.. toctree::
-   :maxdepth: 2
-   :hidden:
-   :caption: API Reference:
-
-            API <api/library_root.rst>
index b33ab77..a952fc2 100644 (file)
@@ -1,37 +1,5 @@
-.. First introduction
-
-What is SimGrid
-===============
-
-SimGrid is a framework to simulate distributed computer systems.
-
-It can be used to either assess abstract algorithms or to profile and
-debug real distributed applications.  SimGrid enables studies in the
-domains of (data-)Grids, IaaS Clouds, Clusters, High Performance
-Computing, Volunteer Computing, and Peer-to-Peer systems.
-
-Technically speaking, SimGrid is a library. It is neither a graphical
-interface nor a command-line simulator running user scripts. The
-interaction with SimGrid is done by writing programs with the exposed
-functions to build your own simulator.
-
-SimGrid is a Free Software distributed under the LGPLv3 license. You are
-thus welcome to use it as you wish or even to modify and distribute
-your version (provided that your version is as free as ours). It also
-means that SimGrid is developed by a vivid community of users and
-developers. We hope that you will come and join us!
-
-SimGrid is the result of almost 20 years of research from several
-groups, both in France and in the U.S.A. It benefited of many funding
-from various research bodies, including the ANR, Inria, CNRS,
-University of Lorraine, University of Hawai'i at Manoa, ENS Rennes, and
-many others. Many thanks to our generous sponsors!
-
-SimGrid is a powerful tool, but its learning curve can be rather
-steep. This manual will hopefully help and guide you to the features
-you want to use. Please report any issue that you see in this manual,
-including typos or unclear elements. You can even propose changes by
-clicking on the "Edit on GitLab" button at the top of every page.
+Main Concepts
+=============
 
 Typical Study based on SimGrid
 ------------------------------
@@ -266,3 +234,4 @@ key-value pair storage library developed at University of Zurich).
 Some of these applications enjoy large user communities themselves.
 
 ..  LocalWords:  SimGrid
+
index ea1761a..e441110 100644 (file)
@@ -25,6 +25,8 @@ On Debian or Ubuntu, simply type:
 If you build pre-compiled packages for other distributions, drop us an
 email.
 
+.. _install_java_precompiled:
+
 Stable Java Package
 ^^^^^^^^^^^^^^^^^^^
 
index 1699548..d6bbd68 100644 (file)
@@ -1,8 +1,33 @@
-Introduction
-************
+What is SimGrid
+***************
 
-.. include:: intro_concepts.rst
+SimGrid is a framework to simulate distributed computer systems.
 
-.. include:: intro_install.rst
+It can be used to either assess abstract algorithms or to profile and
+debug real distributed applications.  SimGrid enables studies in the
+domains of (data-)Grids, IaaS Clouds, Clusters, High Performance
+Computing, Volunteer Computing, and Peer-to-Peer systems.
+
+Technically speaking, SimGrid is a library. It is neither a graphical
+interface nor a command-line simulator running user scripts. The
+interaction with SimGrid is done by writing programs with the exposed
+functions to build your own simulator.
+
+SimGrid is a Free Software distributed under the LGPLv3 license. You are
+thus welcome to use it as you wish or even to modify and distribute
+your version (provided that your version is as free as ours). It also
+means that SimGrid is developed by a vivid community of users and
+developers. We hope that you will come and join us!
+
+SimGrid is the result of almost 20 years of research from several
+groups, both in France and in the U.S.A. It benefited of many funding
+from various research bodies, including the ANR, Inria, CNRS,
+University of Lorraine, University of Hawai'i at Manoa, ENS Rennes, and
+many others. Many thanks to our generous sponsors!
+
+SimGrid is a powerful tool, but its learning curve can be rather
+steep. This manual will hopefully help and guide you to the features
+you want to use. Please report any issue that you see in this manual,
+including typos or unclear elements. You can even propose changes by
+clicking on the "Edit on GitLab" button at the top of every page.
 
-.. include:: intro_yours.rst
index e12daa2..192a96c 100644 (file)
@@ -136,7 +136,7 @@ Existing Configuration Items
 
 - **surf/precision:** :ref:`cfg=surf/precision`
 
-- **For collective operations of SMPI,** please refer to Section :ref:`options_index_smpi_coll`
+- **For collective operations of SMPI,** please refer to Section :ref:`cfg=smpi/coll-selector`
 - **smpi/async-small-thresh:** :ref:`cfg=smpi/async-small-thresh`
 - **smpi/bw-factor:** :ref:`cfg=smpi/bw-factor`
 - **smpi/coll-selector:** :ref:`cfg=smpi/coll-selector`
@@ -171,13 +171,6 @@ Existing Configuration Items
 
 - **vm/model:** :ref:`options_model_select`
 
-.. _options_index_smpi_coll:
-
-Index of SMPI collective algorithms options
-
-.. TODO:: All available collective algorithms will be made available
-          via the ``smpirun --help-coll`` command.
-
 .. _options_model:
 
 Configuring the Platform Models
@@ -1238,6 +1231,9 @@ Each collective operation can be manually selected with a
 ``smpi/collective_name:algo_name``. Available algorithms are listed in
 :ref:`SMPI_use_colls`.
 
+.. TODO:: All available collective algorithms will be made available
+          via the ``smpirun --help-coll`` command.
+
 .. _cfg=smpi/iprobe:
 
 Inject constant times for MPI_Iprobe
index a1f2bf4..9293cb5 100644 (file)
@@ -9,9 +9,8 @@
 .. documentation, but it should remain readable directly.
 
 
-------------
 S4U Examples
-------------
+************
 
 SimGrid comes with an extensive set of examples, documented on this
 page. Most of them only demonstrate one single feature, with some
@@ -28,13 +27,13 @@ A good way to bootstrap your own project is to copy and combine some
 of the provided examples to constitute the skeleton of what you plan
 to simulate.
 
-...........................
+===========================
 Actors: the Active Entities
-...........................
+===========================
 
 
 Starting and Stoping Actors
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------
 
   - **Creating actors:**
     Most actors are started from the deployment XML file, but there is other methods.
@@ -59,7 +58,7 @@ Starting and Stoping Actors
     |br| `examples/s4u/actor-daemon/s4u-actor-daemon.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-daemon/s4u-actor-daemon.cpp>`_
     
 Inter-Actors Interactions
-^^^^^^^^^^^^^^^^^^^^^^^^^
+-------------------------
 
   - **Suspend and Resume actors:**    
     Actors can be suspended and resumed during their executions thanks
@@ -84,7 +83,7 @@ Inter-Actors Interactions
     |br| `examples/s4u/actor-yield/s4u-actor-yield.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-yield/s4u-actor-yield.cpp>`_
 
 Traces Replay as a Workload
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------
 
 This section details how to run trace-driven simulations. It is very
 handy when you want to test an algorithm or protocol that only react
@@ -112,12 +111,12 @@ also the tesh files in the example directories for details.
     primitives (open, read, close).
     |br| `examples/s4u/replay-storage/s4u-replay-storage.cpp  <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/replay-storage/s4u-replay-storage.cpp>`_
 
-..........................
+==========================
 Activities: what Actors do
-..........................
+==========================
 
 Communications on the Network
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------------
 
  - **Basic asynchronous communications:**
    Illustrates how to have non-blocking communications, that are
@@ -142,7 +141,7 @@ Communications on the Network
 .. todo:: add the `ready` example here
    
 Executions on the CPU
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
 
   - **Basic execution:**
     The computations done in your program are not reported to the
@@ -178,7 +177,7 @@ Executions on the CPU
     |br| `examples/s4u/exec-ptask/s4u-exec-ptask.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/exec-ptask/s4u-exec-ptask.cpp>`_
 
 I/O on Disks and Files
-^^^^^^^^^^^^^^^^^^^^^^
+----------------------
 
 SimGrid provides two levels of abstraction to interact with the
 simulated storages. At the simplest level, you simply create read and
@@ -205,7 +204,7 @@ result in short reads and short write, as in reality.
     |br| `examples/s4u/io-file-remote/s4u-io-file-remote.cpp  <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/io-file-remote/s4u-io-file-remote.cpp>`_
 
 Classical synchronization objects
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------------
 
  - **Mutex:**
    Shows how to use simgrid::s4u::Mutex synchronization objects.
@@ -215,9 +214,9 @@ Classical synchronization objects
    Shows how to use simgrid::s4u::Barrier synchronization objects.
    |br| `examples/s4u/synchro-barrier/s4u-synchro-barrier.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/synchro-barrier/s4u-synchro-barrier.cpp>`_
 
-.............................
-Interacting with the platform
-.............................
+=============================
+Interacting with the Platform
+=============================
 
  - **Retrieving the list of hosts matching a given criteria:**
    Shows how to filter the actors that match a given criteria.
@@ -239,9 +238,9 @@ Interacting with the platform
    |br| `examples/s4u/platform-properties/s4u-platform-properties_d.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/platform-properties/s4u-platform-properties_d.xml>`_
    |br| `examples/platforms/prop.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/prop.xml>`_
 
-.................
+=================
 Energy Simulation
-.................
+=================
 
   - **Describing the energy profiles in the platform:**
     This platform file contains the energy profile of each links and
@@ -266,9 +265,9 @@ Energy Simulation
     |br| `examples/s4u/energy-boot/platform_boot.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/energy-boot/platform_boot.xml>`_
     |br| `examples/s4u/energy-boot/s4u-energy-boot.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/energy-boot/s4u-energy-boot.cpp>`_
 
-.......................
+=======================
 Tracing and Visualizing
-.......................
+=======================
 
 Tracing can be activated by various configuration options which
 are illustrated in these example. See also the 
@@ -283,9 +282,9 @@ options to see the task executions:
     ``--cfg=tracing:yes --cfg=tracing/categorized:yes``
     |br| `examples/s4u/trace-platform/s4u-trace-platform.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/trace-platform/s4u-trace-platform.cpp>`_
 
-........................
+========================
 Larger SimGrid Examplars
-........................
+========================
 
 This section contains application examples that are somewhat larger
 than the previous examples.
@@ -312,7 +311,7 @@ than the previous examples.
     |br| `examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp>`_
     
 Data diffusion
-^^^^^^^^^^^^^^
+--------------
 
   - **Bit Torrent:** 
     Classical protocol for Peer-to-Peer data diffusion.
@@ -323,7 +322,7 @@ Data diffusion
     |br| `examples/s4u/app-chainsend/s4u-app-chainsend.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/app-chainsend/s4u-app-chainsend.cpp>`_
 
 Distributed Hash Tables (DHT)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------------
 
   - **Chord Protocol** 
     One of the most famous DHT protocol.
index 154c195..1df82a2 100644 (file)
@@ -1,3 +1,4 @@
+
 /* Copyright (c) 2004-2018. The SimGrid Team. All rights reserved.          */
 
 /* This program is free software; you can redistribute it and/or modify it
@@ -39,10 +40,13 @@ typedef simgrid::msg::Comm sg_msg_Comm;
 typedef struct msg_Comm sg_msg_Comm;
 #endif
 
-SG_BEGIN_DECL()
+#ifdef __cplusplus
+extern "C" {
+#endif
 
 /* *************************** Network Zones ******************************** */
 #define msg_as_t msg_netzone_t /* portability macro */
+
 typedef sg_netzone_t msg_netzone_t;
 
 XBT_PUBLIC msg_netzone_t MSG_zone_get_root();
@@ -54,16 +58,33 @@ XBT_PUBLIC void MSG_zone_set_property_value(msg_netzone_t zone, const char* name
 XBT_PUBLIC void MSG_zone_get_hosts(msg_netzone_t zone, xbt_dynar_t whereto);
 
 /* ******************************** Hosts ************************************ */
+/** @brief Host datatype.
+ *
+ * A <em>location</em> (or <em>host</em>) is any possible place where a process may run. Thus it is represented as a
+ * <em>physical resource with computing capabilities</em>, some <em>mailboxes</em> to enable running process to
+ * communicate with remote ones, and some <em>private data</em> that can be only accessed by local process.
+ */
 typedef sg_host_t msg_host_t;
 
-XBT_PUBLIC size_t MSG_get_host_number();
+/** @brief Finds a msg_host_t using its name. */
 XBT_PUBLIC sg_host_t MSG_get_host_by_name(const char* name);
+/** @brief Finds a msg_host_t using its name. */
 XBT_PUBLIC sg_host_t MSG_host_by_name(const char* name);
 
+/** @brief Returns the amount of host found in the platform */
+XBT_PUBLIC size_t MSG_get_host_number();
+/** @brief Returns a dynar with all existing hosts
+ *
+ * The host order in the returned array is generally different from the host creation/declaration order in the XML
+ * platform (we use a hash table internally).
+ */
 XBT_PUBLIC xbt_dynar_t MSG_hosts_as_dynar();
 
+/** @brief Returns the name of this host */
 XBT_PUBLIC const char* MSG_host_get_name(sg_host_t host);
+/** @brief Returns the user data of this host */
 XBT_PUBLIC void* MSG_host_get_data(sg_host_t host);
+/** @brief Sets the user data of this host */
 XBT_PUBLIC void MSG_host_set_data(sg_host_t host, void* data);
 XBT_PUBLIC xbt_dict_t MSG_host_get_mounted_storage_list(sg_host_t host);
 XBT_PUBLIC xbt_dynar_t MSG_host_get_attached_storage_lists(sg_host_t host);
@@ -73,7 +94,17 @@ XBT_PUBLIC int MSG_host_get_core_number(sg_host_t host);
 XBT_PUBLIC int MSG_host_get_nb_pstates(sg_host_t host);
 XBT_PUBLIC int MSG_host_get_pstate(sg_host_t host);
 XBT_PUBLIC void MSG_host_set_pstate(sg_host_t host, int pstate);
+/** @brief Start the host if it is off
+ *
+ * See also #MSG_host_is_on() and #MSG_host_is_off() to test the current state of the host and @ref SURF_plugin_energy
+ * for more info on DVFS.
+ */
 XBT_PUBLIC void MSG_host_on(sg_host_t h);
+/** @brief Stop the host if it is on
+ *
+ * See also #MSG_host_is_on() and #MSG_host_is_off() to test the current state of the host and @ref SURF_plugin_energy
+ * for more info on DVFS.
+ */
 XBT_PUBLIC void MSG_host_off(sg_host_t h);
 XBT_PUBLIC int MSG_host_is_on(sg_host_t h);
 XBT_PUBLIC int MSG_host_is_off(sg_host_t h);
@@ -82,6 +113,7 @@ XBT_PUBLIC const char* MSG_host_get_property_value(sg_host_t host, const char* n
 XBT_PUBLIC void MSG_host_set_property_value(sg_host_t host, const char* name, const char* value);
 XBT_PUBLIC void MSG_host_get_process_list(sg_host_t host, xbt_dynar_t whereto);
 
+/** @brief Return the location on which the current process is executed */
 XBT_PUBLIC sg_host_t MSG_host_self();
 
 /* ******************************** VMs ************************************* */
@@ -130,6 +162,12 @@ typedef sg_actor_t msg_process_t;
 
 XBT_PUBLIC int MSG_process_get_PID(msg_process_t process);
 XBT_PUBLIC int MSG_process_get_PPID(msg_process_t process);
+/** @brief Return a #msg_process_t from its PID.
+ *
+ * Note that the PID are uniq in the whole simulation, not only on a given host.
+ *
+ * @returns NULL if no host is found
+ */
 XBT_PUBLIC sg_actor_t MSG_process_from_PID(int pid);
 XBT_PUBLIC const char* MSG_process_get_name(msg_process_t process);
 XBT_PUBLIC sg_host_t MSG_process_get_host(msg_process_t process);
@@ -142,21 +180,38 @@ XBT_PUBLIC void MSG_process_suspend(msg_process_t process);
 XBT_PUBLIC void MSG_process_resume(msg_process_t process);
 XBT_PUBLIC int MSG_process_is_suspended(msg_process_t process);
 XBT_PUBLIC void MSG_process_restart(msg_process_t process);
+/** @brief Sets the "auto-restart" flag of the process.
+ *
+ * If the flag is set, the process will be automatically restarted when its host comes back up.
+ */
 XBT_PUBLIC void MSG_process_auto_restart_set(msg_process_t process, int auto_restart);
+/** @brief Indicates that this process should not prevent the simulation from ending
+ *
+ * SimGrid simulations run until all non-daemon processes are stopped.
+ */
 XBT_PUBLIC void MSG_process_daemonize(msg_process_t process);
+/** @brief Imediately changes the host on which this process runs */
 XBT_PUBLIC void MSG_process_migrate(msg_process_t process, msg_host_t host);
+/** @brief Wait for the completion of a #msg_process_t.
+ *
+ * @param process the process to wait for
+ * @param timeout wait until the process is over, or the timeout occurs
+ */
 XBT_PUBLIC void MSG_process_join(msg_process_t process, double timeout);
+/** @brief Kills a process */
 XBT_PUBLIC void MSG_process_kill(msg_process_t process);
+/** @brief Kill all running process */
 XBT_PUBLIC void MSG_process_killall();
+/** @breif Specifies the time at which the process should be automatically killed */
 XBT_PUBLIC void MSG_process_set_kill_time(msg_process_t process, double kill_time);
+/** @brief Yield the current actor; let the other actors execute first */
 XBT_PUBLIC void MSG_process_yield();
 
-/**
- * @brief @brief Communication action.
- * @ingroup msg_task_usage
+/** @brief Object representing an ongoing communication between processes.
  *
- * Object representing an ongoing communication between processes. Such beast is usually obtained by using
- * #MSG_task_isend, #MSG_task_irecv or friends.
+ * \rst
+ * Such beast is usually obtained by using :cpp:func:`MSG_task_isend`, :cpp:func:`MSG_task_irecv` or friends.
+ * \endrst
  */
 typedef sg_msg_Comm* msg_comm_t;
 
@@ -173,18 +228,16 @@ typedef struct msg_task {
 } s_msg_task_t;
 
 /** @brief Task datatype.
-    @ingroup m_task_management
-
-    A <em>task</em> may then be defined by a <em>computing
-    amount</em>, a <em>message size</em> and some <em>private
   data</em>.
+ *
+ *  Since most scheduling algorithms rely on a concept of task  that can be either <em>computed</em> locally or
+ *  <em>transferred</em> on another processor, it seems to be the right level of abstraction for our purposes.
+ *  A <em>task</em> may then be defined by a <em>computing amount</em>, a <em>message size</em> and
*  some <em>private data</em>.
  */
 
 typedef struct msg_task* msg_task_t;
 
-/** @brief Default value for an uninitialized #msg_task_t.
-    @ingroup m_task_management
-*/
+/** @brief Default value for an uninitialized #msg_task_t. */
 #define MSG_TASK_UNINITIALIZED NULL
 
 /** @brief Return code of most MSG functions
@@ -205,6 +258,14 @@ typedef enum {
 /** @} */
 
 /************************** Global ******************************************/
+/** @brief set a configuration variable
+ *
+ * Do --help on any simgrid binary to see the list of currently existing configuration variables, and see Section @ref
+ * options.
+ *
+ * Example:
+ * MSG_config("host/model","ptask_L07");
+ */
 XBT_PUBLIC void MSG_config(const char* key, const char* value);
 /** @ingroup msg_simulation
  *  @brief Initialize the MSG internal data.
@@ -223,15 +284,35 @@ XBT_PUBLIC void MSG_config(const char* key, const char* value);
   } while (0)
 
 XBT_PUBLIC void MSG_init_nocheck(int* argc, char** argv);
+/** @brief Launch the MSG simulation */
 XBT_PUBLIC msg_error_t MSG_main();
+/** @brief Registers the main function of a process in a global table.
+ *
+ * This table is then used by #MSG_launch_application.
+ * @param name the reference name of the function.
+ * @param code the function (must have the same prototype than the main function of any C program: int ..(int argc, char
+ * *argv[]))
+ */
 XBT_PUBLIC void MSG_function_register(const char* name, xbt_main_func_t code);
+/** @brief Registers a code function as being the default value.
+ *
+ * This function will get used by MSG_launch_application() when there is no registered function of the requested name
+ * in.
+ *
+ * @param code the function (must have the same prototype than the main function of any C program: int ..(int argc, char
+ * *argv[]))
+ */
 XBT_PUBLIC void MSG_function_register_default(xbt_main_func_t code);
+/** @brief Creates a new platform, including hosts, links and the routing_table */
 XBT_PUBLIC void MSG_create_environment(const char* file);
+/** @brief Creates the application described in the provided file */
 XBT_PUBLIC void MSG_launch_application(const char* file);
-/*Bypass the parser */
+/** @brief register functions bypassing the parser */
 XBT_PUBLIC void MSG_set_function(const char* host_id, const char* function_name, xbt_dynar_t arguments);
 
+/** @brief A clock (in second). */
 XBT_PUBLIC double MSG_get_clock();
+/** @brief Returns the amount of messages sent since the simulation start */
 XBT_PUBLIC unsigned long int MSG_get_sent_msg();
 
 /************************** Process handling *********************************/
@@ -322,6 +403,12 @@ XBT_PUBLIC int MSG_comm_waitany(xbt_dynar_t comms);
 XBT_PUBLIC msg_task_t MSG_comm_get_task(msg_comm_t comm);
 XBT_PUBLIC msg_error_t MSG_comm_get_status(msg_comm_t comm);
 
+/** @brief Check if there is a communication going on in a mailbox.
+ *
+ * @param alias the name of the mailbox to be considered
+ *
+ * @return Returns 1 if there is a communication, 0 otherwise
+ */
 XBT_PUBLIC int MSG_task_listen(const char* alias);
 XBT_PUBLIC msg_error_t MSG_task_send_with_timeout(msg_task_t task, const char* alias, double timeout);
 XBT_PUBLIC msg_error_t MSG_task_send_with_timeout_bounded(msg_task_t task, const char* alias, double timeout,
@@ -334,11 +421,12 @@ XBT_PUBLIC const char* MSG_task_get_category(msg_task_t task);
 
 /************************** Mailbox handling ************************************/
 
-/* @brief MSG_mailbox_set_async - set a mailbox as eager
- * Sets the mailbox to a permanent receiver mode. Messages sent to this mailbox will then be sent just after the send
- * is issued, without waiting for the corresponding receive.
+/* @brief set a mailbox in eager mode.
+ * All messages sent to this mailbox will be transferred to the receiver without waiting for the receive call.
+ * The receive call will still be necessary to use the received data.
+ * If there is a need to receive some messages asynchronously, and some not, two different mailboxes should be used.
+ *
  * This call should be done before issuing any receive, and on the receiver's side only
- * @param alias    The alias of the mailbox to modify.
  */
 XBT_PUBLIC void MSG_mailbox_set_async(const char* alias);
 
@@ -356,9 +444,13 @@ XBT_PUBLIC int MSG_sem_get_capacity(msg_sem_t sem);
 XBT_PUBLIC void MSG_sem_destroy(msg_sem_t sem);
 XBT_PUBLIC int MSG_sem_would_block(msg_sem_t sem);
 
+/** @brief Opaque type representing a barrier identifier */
 typedef sg_bar_t msg_bar_t;
+/** @brief Initializes a barier, with count elements */
 XBT_PUBLIC msg_bar_t MSG_barrier_init(unsigned int count);
+/** @brief Destroys barrier */
 XBT_PUBLIC void MSG_barrier_destroy(msg_bar_t bar);
+/** @brief Performs a barrier already initialized */
 XBT_PUBLIC int MSG_barrier_wait(msg_bar_t bar);
 
 /* ****************************************************************************************** */
@@ -367,7 +459,9 @@ XBT_PUBLIC smx_context_t
 XBT_ATTRIB_DEPRECATED_v323("MSG_process_get_smx_ctx is deprecated. Please contact us if you need it.")
 MSG_process_get_smx_ctx(msg_process_t process);
 
-SG_END_DECL()
+#ifdef __cplusplus
+}
+#endif
 
 #ifdef __cplusplus
 XBT_PUBLIC msg_process_t MSG_process_create_from_stdfunc(std::string name, std::function<void()> code, void* data,
index 06c261a..22dfa7c 100644 (file)
@@ -55,15 +55,6 @@ void MSG_init_nocheck(int *argc, char **argv) {
     atexit(MSG_exit);
 }
 
-/** @ingroup msg_simulation
- * @brief set a configuration variable
- *
- * Do --help on any simgrid binary to see the list of currently existing configuration variables, and see Section @ref
- * options.
- *
- * Example:
- * MSG_config("host/model","ptask_L07");
- */
 void MSG_config(const char *key, const char *value){
   xbt_assert(msg_global,"ERROR: Please call MSG_init() before using MSG_config()");
   simgrid::config::set_as_string(key, value);
index 3c8121b..d393195 100644 (file)
@@ -13,7 +13,7 @@
 
 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(msg_gos, msg, "Logging specific to MSG (gos)");
 
-/** @ingroup msg_task_usage
+/**
  * @brief Executes a task and waits for its termination.
  *
  * This function is used for describing the behavior of a process. It takes only one parameter.
@@ -25,7 +25,7 @@ msg_error_t MSG_task_execute(msg_task_t task)
   return MSG_parallel_task_execute(task);
 }
 
-/** @ingroup msg_task_usage
+/**
  * @brief Executes a parallel task and waits for its termination.
  *
  * @param task a #msg_task_t to execute on the location on which the process is running.
@@ -98,7 +98,7 @@ msg_error_t MSG_parallel_task_execute_with_timeout(msg_task_t task, double timeo
   return status;
 }
 
-/** @ingroup msg_task_usage
+/**
  * @brief Sleep for the specified number of seconds
  *
  * Makes the current process sleep until @a time seconds have elapsed.
@@ -130,7 +130,7 @@ msg_error_t MSG_process_sleep(double nb_sec)
   return status;
 }
 
-/** @ingroup msg_task_usage
+/**
  * @brief Receives a task from a mailbox.
  *
  * This is a blocking function, the execution flow will be blocked until the task is received. See #MSG_task_irecv
@@ -148,7 +148,7 @@ msg_error_t MSG_task_receive(msg_task_t * task, const char *alias)
   return MSG_task_receive_with_timeout(task, alias, -1);
 }
 
-/** @ingroup msg_task_usage
+/**
  * @brief Receives a task from a mailbox at a given rate.
  *
  * @param task a memory location for storing a #msg_task_t.
@@ -169,7 +169,7 @@ msg_error_t MSG_task_receive_bounded(msg_task_t * task, const char *alias, doubl
   return MSG_task_receive_with_timeout_bounded(task, alias, -1, rate);
 }
 
-/** @ingroup msg_task_usage
+/**
  * @brief Receives a task from a mailbox with a given timeout.
  *
  * This is a blocking function with a timeout, the execution flow will be blocked until the task is received or the
@@ -189,7 +189,7 @@ msg_error_t MSG_task_receive_with_timeout(msg_task_t * task, const char *alias,
   return MSG_task_receive_ext(task, alias, timeout, nullptr);
 }
 
-/** @ingroup msg_task_usage
+/**
  * @brief Receives a task from a mailbox with a given timeout and at a given rate.
  *
  * @param task a memory location for storing a #msg_task_t.
@@ -211,7 +211,7 @@ msg_error_t MSG_task_receive_with_timeout_bounded(msg_task_t * task, const char
   return MSG_task_receive_ext_bounded(task, alias, timeout, nullptr, rate);
 }
 
-/** @ingroup msg_task_usage
+/**
  * @brief Receives a task from a mailbox from a specific host with a given timeout.
  *
  * This is a blocking function with a timeout, the execution flow will be blocked until the task is received or the
@@ -233,7 +233,7 @@ msg_error_t MSG_task_receive_ext(msg_task_t * task, const char *alias, double ti
   return MSG_task_receive_ext_bounded(task, alias, timeout, host, -1.0);
 }
 
-/** @ingroup msg_task_usage
+/**
  * @brief Receives a task from a mailbox from a specific host with a given timeout  and at a given rate.
  *
  * @param task a memory location for storing a #msg_task_t.
@@ -333,7 +333,7 @@ static inline msg_comm_t MSG_task_isend_internal(msg_task_t task, const char* al
   return comm;
 }
 
-/** @ingroup msg_task_usage
+/**
  * @brief Sends a task on a mailbox.
  *
  * This is a non blocking function: use MSG_comm_wait() or MSG_comm_test() to end the communication.
@@ -347,7 +347,7 @@ msg_comm_t MSG_task_isend(msg_task_t task, const char *alias)
   return MSG_task_isend_internal(task, alias, nullptr, 0);
 }
 
-/** @ingroup msg_task_usage
+/**
  * @brief Sends a task on a mailbox with a maximum rate
  *
  * This is a non blocking function: use MSG_comm_wait() or MSG_comm_test() to end the communication. The maxrate
@@ -364,7 +364,7 @@ msg_comm_t MSG_task_isend_bounded(msg_task_t task, const char *alias, double max
   return MSG_task_isend_internal(task, alias, nullptr, 0);
 }
 
-/** @ingroup msg_task_usage
+/**
  * @brief Sends a task on a mailbox.
  *
  * This is a non blocking detached send function.
@@ -385,7 +385,7 @@ void MSG_task_dsend(msg_task_t task, const char *alias, void_f_pvoid_t cleanup)
   xbt_assert(comm == nullptr);
 }
 
-/** @ingroup msg_task_usage
+/**
  * @brief Sends a task on a mailbox with a maximal rate.
  *
  * This is a non blocking detached send function.
@@ -414,7 +414,7 @@ void MSG_task_dsend_bounded(msg_task_t task, const char *alias, void_f_pvoid_t c
   MSG_task_dsend(task, alias, cleanup);
 }
 
-/** @ingroup msg_task_usage
+/**
  * @brief Starts listening for receiving a task from an asynchronous communication.
  *
  * This is a non blocking function: use MSG_comm_wait() or MSG_comm_test() to end the communication.
@@ -428,7 +428,7 @@ msg_comm_t MSG_task_irecv(msg_task_t *task, const char *name)
   return MSG_task_irecv_bounded(task, name, -1.0);
 }
 
-/** @ingroup msg_task_usage
+/**
  * @brief Starts listening for receiving a task from an asynchronous communication at a given rate.
  *
  * The rate parameter can be used to receive a task with a limited
@@ -460,7 +460,7 @@ msg_comm_t MSG_task_irecv_bounded(msg_task_t *task, const char *name, double rat
   return comm;
 }
 
-/** @ingroup msg_task_usage
+/**
  * @brief Checks whether a communication is done, and if yes, finalizes it.
  * @param comm the communication to test
  * @return 'true' if the communication is finished
@@ -494,7 +494,7 @@ int MSG_comm_test(msg_comm_t comm)
   return finished;
 }
 
-/** @ingroup msg_task_usage
+/**
  * @brief This function checks if a communication is finished.
  * @param comms a vector of communications
  * @return the position of the finished communication if any
@@ -546,17 +546,13 @@ int MSG_comm_testany(xbt_dynar_t comms)
   return finished_index;
 }
 
-/** @ingroup msg_task_usage
- * @brief Destroys a communication.
- * @param comm the communication to destroy.
- */
+/** @brief Destroys the provided communication. */
 void MSG_comm_destroy(msg_comm_t comm)
 {
   delete comm;
 }
 
-/** @ingroup msg_task_usage
- * @brief Wait for the completion of a communication.
+/** @brief Wait for the completion of a communication.
  *
  * It takes two parameters.
  * @param comm the communication to wait.
@@ -588,8 +584,7 @@ msg_error_t MSG_comm_wait(msg_comm_t comm, double timeout)
   return comm->status;
 }
 
-/** @ingroup msg_task_usage
- * @brief This function is called by a sender and permit to wait for each communication
+/** @brief This function is called by a sender and permit to wait for each communication
  *
  * @param comm a vector of communication
  * @param nb_elem is the size of the comm vector
@@ -601,8 +596,7 @@ void MSG_comm_waitall(msg_comm_t * comm, int nb_elem, double timeout)
     MSG_comm_wait(comm[i], timeout);
 }
 
-/** @ingroup msg_task_usage
- * @brief This function waits for the first communication finished in a list.
+/** @brief This function waits for the first communication finished in a list.
  * @param comms a vector of communications
  * @return the position of the first finished communication
  * (but it may have failed, use MSG_comm_get_status() to know its status)
@@ -654,7 +648,6 @@ int MSG_comm_waitany(xbt_dynar_t comms)
 }
 
 /**
- * @ingroup msg_task_usage
  * @brief Returns the error (if any) that occurred during a finished communication.
  * @param comm a finished communication
  * @return the status of the communication, or #MSG_OK if no error occurred
@@ -665,8 +658,7 @@ msg_error_t MSG_comm_get_status(msg_comm_t comm) {
   return comm->status;
 }
 
-/** @ingroup msg_task_usage
- * @brief Get a task (#msg_task_t) from a communication
+/** @brief Get a task (#msg_task_t) from a communication
  *
  * @param comm the communication where to get the task
  * @return the task from the communication
@@ -698,7 +690,7 @@ void MSG_comm_copy_data_from_SIMIX(smx_activity_t synchro, void* buff, size_t bu
   }
 }
 
-/** @ingroup msg_task_usage
+/**
  * @brief Sends a task to a mailbox
  *
  * This is a blocking function, the execution flow will be blocked until the task is sent (and received on the other
@@ -717,7 +709,7 @@ msg_error_t MSG_task_send(msg_task_t task, const char *alias)
   return MSG_task_send_with_timeout(task, alias, -1);
 }
 
-/** @ingroup msg_task_usage
+/**
  * @brief Sends a task to a mailbox with a maximum rate
  *
  * This is a blocking function, the execution flow will be blocked until the task is sent. The maxrate parameter allows
@@ -741,7 +733,7 @@ msg_error_t MSG_task_send_bounded(msg_task_t task, const char *alias, double max
   return MSG_task_send(task, alias);
 }
 
-/** @ingroup msg_task_usage
+/**
  * @brief Sends a task to a mailbox with a timeout
  *
  * This is a blocking function, the execution flow will be blocked until the task is sent or the timeout is achieved.
@@ -804,7 +796,7 @@ msg_error_t MSG_task_send_with_timeout(msg_task_t task, const char *alias, doubl
   return ret;
 }
 
-/** @ingroup msg_task_usage
+/**
  * @brief Sends a task to a mailbox with a timeout and with a maximum rate
  *
  * This is a blocking function, the execution flow will be blocked until the task is sent or the timeout is achieved.
@@ -828,7 +820,7 @@ msg_error_t MSG_task_send_with_timeout_bounded(msg_task_t task, const char *alia
   return MSG_task_send_with_timeout(task, alias, timeout);
 }
 
-/** @ingroup msg_task_usage
+/**
  * @brief Look if there is a communication on a mailbox and return the PID of the sender process.
  *
  * @param alias the name of the mailbox to be considered
@@ -848,7 +840,7 @@ int MSG_task_listen_from(const char *alias)
   return MSG_process_get_PID(static_cast<msg_task_t>(comm->src_buff)->simdata->sender);
 }
 
-/** @ingroup msg_task_usage
+/**
  * @brief Sets the tracing category of a task.
  *
  * This function should be called after the creation of a MSG task, to define the category of that task. The
@@ -868,8 +860,7 @@ void MSG_task_set_category (msg_task_t task, const char *category)
   TRACE_msg_set_task_category (task, category);
 }
 
-/** @ingroup msg_task_usage
- *
+/**
  * @brief Gets the current tracing category of a task.
  *
  * @param task the task to be considered
index 590bd24..643e190 100644 (file)
@@ -50,20 +50,17 @@ smx_actor_t MSG_process_create_from_SIMIX(std::string name, simgrid::simix::Acto
   return p == nullptr ? nullptr : p->get_impl();
 }
 
-/** @ingroup m_process_management
- * @brief Creates and runs a new #msg_process_t.
+/** @brief Creates and runs a new #msg_process_t.
  *
  * Does exactly the same as #MSG_process_create_with_arguments but without providing standard arguments
  * (@a argc, @a argv, @a start_time, @a kill_time).
- * @sa MSG_process_create_with_arguments
  */
 msg_process_t MSG_process_create(const char *name, xbt_main_func_t code, void *data, msg_host_t host)
 {
   return MSG_process_create_with_environment(name == nullptr ? "" : name, code, data, host, 0, nullptr, nullptr);
 }
 
-/** @ingroup m_process_management
- * @brief Creates and runs a new #msg_process_t.
+/** @brief Creates and runs a new #msg_process_t.
 
  * A constructor for #msg_process_t taking four arguments and returning the corresponding object. The structure (and
  * the corresponding thread) is created, and put in the list of ready process.
@@ -78,8 +75,6 @@ msg_process_t MSG_process_create(const char *name, xbt_main_func_t code, void *d
  * @param host the location where the new process is executed.
  * @param argc first argument passed to @a code
  * @param argv second argument passed to @a code
- * @see msg_process_t
- * @return The new corresponding object.
  */
 
 msg_process_t MSG_process_create_with_arguments(const char *name, xbt_main_func_t code, void *data, msg_host_t host,
index 1ae4117..7a51afd 100644 (file)
@@ -7,14 +7,6 @@
 #include "src/simix/smx_private.hpp"
 #include <algorithm>
 
-/** @addtogroup m_task_management
- *
- *  Since most scheduling algorithms rely on a concept of task  that can be either <em>computed</em> locally or
- *  <em>transferred</em> on another processor, it seems to be the right level of abstraction for our purposes.
- *  A <em>task</em> may then be defined by a <em>computing amount</em>, a <em>message size</em> and
- *  some <em>private data</em>.
- */
-
 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(msg_task, msg, "Logging specific to MSG (task)");
 
 void s_simdata_task_t::reportMultipleUse() const
@@ -32,8 +24,7 @@ void s_simdata_task_t::reportMultipleUse() const
 }
 
 /********************************* Task **************************************/
-/** @ingroup m_task_management
- * @brief Creates a new #msg_task_t.
+/** @brief Creates a new #msg_task_t.
  *
  * A constructor for #msg_task_t taking four arguments and returning the corresponding object.
  * @param name a name for the object. It is for user-level information and can be nullptr.
@@ -65,8 +56,7 @@ msg_task_t MSG_task_create(const char *name, double flop_amount, double message_
   return task;
 }
 
-/** @ingroup m_task_management
- * @brief Creates a new #msg_task_t (a parallel one....).
+/** @brief Creates a new #msg_task_t (a parallel one....).
  *
  * A constructor for #msg_task_t taking six arguments and returning the corresponding object.
  * @param name a name for the object. It is for user-level information and can be nullptr.
@@ -105,8 +95,7 @@ msg_task_t MSG_parallel_task_create(const char *name, int host_nb, const msg_hos
   return task;
 }
 
-/** @ingroup m_task_management
- * @brief Return the user data of a #msg_task_t.
+/** @brief Return the user data of a #msg_task_t.
  *
  * This function checks whether @a task is a valid pointer and return the user data associated to @a task if possible.
  */
@@ -125,8 +114,7 @@ void MSG_task_set_data(msg_task_t task, void *data)
   task->data = data;
 }
 
-/** @ingroup m_task_management
- * @brief Sets a function to be called when a task has just been copied.
+/** @brief Sets a function to be called when a task has just been copied.
  * @param callback a callback function
  */
 void MSG_task_set_copy_callback(void (*callback) (msg_task_t task, msg_process_t sender, msg_process_t receiver)) {
@@ -140,8 +128,7 @@ void MSG_task_set_copy_callback(void (*callback) (msg_task_t task, msg_process_t
   }
 }
 
-/** @ingroup m_task_management
- * @brief Return the sender of a #msg_task_t.
+/** @brief Return the sender of a #msg_task_t.
  *
  * This functions returns the #msg_process_t which sent this task
  */
@@ -150,8 +137,7 @@ msg_process_t MSG_task_get_sender(msg_task_t task)
   return task->simdata->sender;
 }
 
-/** @ingroup m_task_management
- * @brief Return the source of a #msg_task_t.
+/** @brief Return the source of a #msg_task_t.
  *
  * This functions returns the #msg_host_t from which this task was sent
  */
@@ -160,8 +146,7 @@ msg_host_t MSG_task_get_source(msg_task_t task)
   return task->simdata->source;
 }
 
-/** @ingroup m_task_management
- * @brief Return the name of a #msg_task_t.
+/** @brief Return the name of a #msg_task_t.
  *
  * This functions returns the name of a #msg_task_t as specified on creation
  */
@@ -170,8 +155,7 @@ const char *MSG_task_get_name(msg_task_t task)
   return task->name;
 }
 
-/** @ingroup m_task_management
- * @brief Sets the name of a #msg_task_t.
+/** @brief Sets the name of a #msg_task_t.
  *
  * This functions allows to associate a name to a task
  */
@@ -180,8 +164,7 @@ void MSG_task_set_name(msg_task_t task, const char *name)
   task->name = xbt_strdup(name);
 }
 
-/** @ingroup m_task_management
- * @brief Destroy a #msg_task_t.
+/** @brief Destroy a #msg_task_t.
  *
  * Destructor for #msg_task_t. Note that you should free user data, if any, @b before calling this function.
  *
@@ -208,8 +191,7 @@ msg_error_t MSG_task_destroy(msg_task_t task)
   return MSG_OK;
 }
 
-/** @ingroup m_task_usage
- * @brief Cancel a #msg_task_t.
+/** @brief Cancel a #msg_task_t.
  * @param task the task to cancel. If it was executed or transfered, it stops the process that were working on it.
  */
 msg_error_t MSG_task_cancel(msg_task_t task)
@@ -226,8 +208,7 @@ msg_error_t MSG_task_cancel(msg_task_t task)
   return MSG_OK;
 }
 
-/** @ingroup m_task_management
- * @brief Returns a value in ]0,1[ that represent the task remaining work
+/** @brief Returns a value in ]0,1[ that represent the task remaining work
  *    to do: starts at 1 and goes to 0. Returns 0 if not started or finished.
  *
  * It works for either parallel or sequential tasks.
@@ -244,8 +225,7 @@ double MSG_task_get_remaining_work_ratio(msg_task_t task) {
   }
 }
 
-/** @ingroup m_task_management
- * @brief Returns the amount of flops that remain to be computed
+/** @brief Returns the amount of flops that remain to be computed
  *
  * The returned value is initially the cost that you defined for the task, then it decreases until it reaches 0
  *
@@ -263,8 +243,7 @@ double MSG_task_get_flops_amount(msg_task_t task) {
   }
 }
 
-/** @ingroup m_task_management
- * @brief set the computation amount needed to process a task #msg_task_t.
+/** @brief set the computation amount needed to process a task #msg_task_t.
  *
  * @warning If the computation is ongoing (already started and not finished),
  * it is not modified by this call. Moreover, after its completion, the ongoing execution with set the flops_amount to
@@ -275,8 +254,7 @@ void MSG_task_set_flops_amount(msg_task_t task, double flops_amount)
   task->simdata->flops_amount = flops_amount;
 }
 
-/** @ingroup m_task_management
- * @brief set the amount data attached with a task #msg_task_t.
+/** @brief set the amount data attached with a task #msg_task_t.
  *
  * @warning If the transfer is ongoing (already started and not finished), it is not modified by this call.
  */
@@ -285,8 +263,7 @@ void MSG_task_set_bytes_amount(msg_task_t task, double data_size)
   task->simdata->bytes_amount = data_size;
 }
 
-/** @ingroup m_task_management
- * @brief Returns the total amount received by a task #msg_task_t.
+/** @brief Returns the total amount received by a task #msg_task_t.
  *        If the communication does not exist it will return 0.
  *        So, if the communication has FINISHED or FAILED it returns zero.
  */
@@ -296,8 +273,7 @@ double MSG_task_get_remaining_communication(msg_task_t task)
   return task->simdata->comm->remains();
 }
 
-/** @ingroup m_task_management
- * @brief Returns the size of the data attached to a task #msg_task_t.
+/** @brief Returns the size of the data attached to a task #msg_task_t.
  */
 double MSG_task_get_bytes_amount(msg_task_t task)
 {
@@ -305,8 +281,7 @@ double MSG_task_get_bytes_amount(msg_task_t task)
   return task->simdata->bytes_amount;
 }
 
-/** @ingroup m_task_management
- * @brief Changes the priority of a computation task. This priority doesn't affect the transfer rate. A priority of 2
+/** @brief Changes the priority of a computation task. This priority doesn't affect the transfer rate. A priority of 2
  *        will make a task receive two times more cpu power than the other ones.
  */
 void MSG_task_set_priority(msg_task_t task, double priority)
@@ -316,8 +291,7 @@ void MSG_task_set_priority(msg_task_t task, double priority)
     simcall_execution_set_priority(task->simdata->compute, task->simdata->priority);
 }
 
-/** @ingroup m_task_management
- * @brief Changes the maximum CPU utilization of a computation task.
+/** @brief Changes the maximum CPU utilization of a computation task.
  *        Unit is flops/s.
  *
  * For VMs, there is a pitfall. Please see MSG_vm_set_bound().
index 75684f4..64480a6 100644 (file)
@@ -871,8 +871,6 @@ set(DOC_SOURCES
   doc/doxygen/inside_doxygen.doc
   doc/doxygen/inside_extending.doc
   doc/doxygen/inside_release.doc
-  doc/doxygen/java.doc
-  doc/doxygen/module-msg.doc
   doc/doxygen/module-sd.doc
   doc/doxygen/module-simix.doc
   doc/doxygen/module-surf.doc
@@ -911,7 +909,10 @@ set(DOC_SOURCES
   docs/source/img/smpi_simgrid_alltoall_pair_16.png
   docs/source/img/smpi_simgrid_alltoall_ring_16.png
 
+  docs/ignored_symbols
   docs/source/application.rst
+  docs/source/app_java.rst
+  docs/source/app_msg.rst
   docs/source/app_s4u.rst
   docs/source/app_smpi.rst
   docs/source/index.rst