+++ /dev/null
-/*! @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.
-
- */
+++ /dev/null
-/**
-@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.
-*/
| 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
--- /dev/null
+# 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
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
--- /dev/null
+.. _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.
+
--- /dev/null
+.. _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
.. _S4U_doc:
-=================
The S4U Interface
-=================
+#################
.. raw:: html
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
- **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**
.. 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>`
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.
: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>`_
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
smpirun -wrapper valgrind ...other args...
smpirun -wrapper "gdb --args" --cfg=contexts/factory:thread ...other args...
+.. _SMPI_use_colls:
+
................................
Simulating Collective Operations
................................
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
.................................
extensions = [
'sphinx.ext.todo',
'breathe',
- 'exhale',
+# 'exhale',
'hidden_code_block',
+# 'snooze', # must come after exhale
]
todo_include_todos = True
: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>
The SimGrid Community <community.rst>
Frequently Asked Questions <faq.rst>
-.. toctree::
- :maxdepth: 2
- :hidden:
- :caption: API Reference:
-
- API <api/library_root.rst>
-.. 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
------------------------------
Some of these applications enjoy large user communities themselves.
.. LocalWords: SimGrid
+
If you build pre-compiled packages for other distributions, drop us an
email.
+.. _install_java_precompiled:
+
Stable Java Package
^^^^^^^^^^^^^^^^^^^
-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
- **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`
- **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
``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
.. 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
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.
|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
|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
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
.. todo:: add the `ready` example here
Executions on the CPU
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
- **Basic execution:**
The computations done in your program are not reported to the
|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
|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.
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.
|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
|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
``--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.
|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.
|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.
+
/* Copyright (c) 2004-2018. The SimGrid Team. All rights reserved. */
/* This program is free software; you can redistribute it and/or modify it
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();
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);
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);
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 ************************************* */
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);
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;
} 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
/** @} */
/************************** 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.
} 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 *********************************/
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,
/************************** 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);
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);
/* ****************************************************************************************** */
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,
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);
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.
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.
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.
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
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.
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
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.
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
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.
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.
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
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.
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.
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.
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
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
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
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.
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
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)
}
/**
- * @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
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
}
}
-/** @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
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
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.
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.
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
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
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
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.
* @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,
#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
}
/********************************* 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.
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.
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.
*/
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)) {
}
}
-/** @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
*/
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
*/
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
*/
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
*/
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.
*
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)
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.
}
}
-/** @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
*
}
}
-/** @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
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.
*/
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.
*/
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)
{
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)
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().
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
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
