From: Martin Quinson Date: Mon, 1 Oct 2018 00:31:20 +0000 (+0200) Subject: Further improvements to the docs X-Git-Tag: v3_21~23 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/f04cb933da95f9df2da6d58a72a7b1da12582f7d Further improvements to the docs - 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. --- diff --git a/doc/doxygen/java.doc b/doc/doxygen/java.doc deleted file mode 100644 index d4c273adcf..0000000000 --- a/doc/doxygen/java.doc +++ /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. -The full [javadoc](javadoc/index.html) is available. - -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 - -THIS SECTION IS SOMEWHAT OBSOLETE 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 index 5f3c420730..0000000000 --- a/doc/doxygen/module-msg.doc +++ /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. -*/ diff --git a/docs/Build.sh b/docs/Build.sh index e39cf57904..9bc5a2610f 100755 --- a/docs/Build.sh +++ b/docs/Build.sh @@ -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 '' build/xml/msg_8h.xml; \ + grep '' build/xml/namespacesimgrid_1_1s4u.xml; \ + grep ']*>//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 index 0000000000..d72c68d560 --- /dev/null +++ b/docs/ignored_symbols @@ -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 diff --git a/docs/source/Doxyfile b/docs/source/Doxyfile index 06760f5260..d8a862e310 100644 --- a/docs/source/Doxyfile +++ b/docs/source/Doxyfile @@ -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 index 0000000000..067726db60 --- /dev/null +++ b/docs/source/app_java.rst @@ -0,0 +1,108 @@ +.. _Java_doc: + +================= +The Java Bindings +================= + +.. raw:: html + + + +
+
+ + +This section describes jMSG, the Java API to Simgrid. This API mimicks +:ref:`MSG `, which is a simple yet somehow realistic interface. +The full [javadoc](javadoc/index.html) is available. + +Most of the documentation of the :ref:`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. + +How to install the Java bindings +-------------------------------- + +The easiest is to use a :ref:`precompiled jarfile `, +but some people may prefer to :ref:`compile it from the sources `. + + +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 index 0000000000..e3ca7e7b50 --- /dev/null +++ b/docs/source/app_msg.rst @@ -0,0 +1,288 @@ +.. _MSG_doc: + +==================================== +The MSG Interface (legacy interface) +==================================== + +.. raw:: html + + + +
+
+ +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 diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index 8d4ec2be63..71da01bb93 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -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 `, -:ref:`communication `, -:ref:`disk usage `, +S4U interface to express their :ref:`computation `, +:ref:`communication `, :ref:`disk usage `, 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 `: + - :ref:`class s4u::Actor `: Active entities executing your application. - - :ref:`class s4u::Engine ` + - :ref:`class s4u::Engine ` Simulation engine (singleton). - - :ref:`class s4u::Mailbox ` + - :ref:`class s4u::Mailbox ` Communication rendez-vous. - **Platform Elements** - - :ref:`class s4u::Host `: + - :ref:`class s4u::Host `: Actor location, providing computational power. - - :ref:`class s4u::Link ` + - :ref:`class s4u::Link ` Interconnecting hosts. - - :ref:`class s4u::NetZone `: + - :ref:`class s4u::NetZone `: Sub-region of the platform, containing resources (Hosts, Links, etc). - - :ref:`class s4u::Storage ` + - :ref:`class s4u::Storage ` Resource on which actors can write and read data. - - :ref:`class s4u::VirtualMachine `: + - :ref:`class s4u::VirtualMachine `: Execution containers that can be moved between Hosts. -- **Activities** (:ref:`class s4u::Activity `): +- **Activities** (:ref:`class s4u::Activity `): The things that actors can do on resources - - :ref:`class s4u::Comm ` + - :ref:`class s4u::Comm ` Communication activity, started on Mailboxes and consuming links. - - :ref:`class s4u::Exec ` + - :ref:`class s4u::Exec ` Computation activity, started on Host and consuming CPU resources. - - :ref:`class s4u::Io ` + - :ref:`class s4u::Io ` I/O activity, started on and consumming Storages. - **Synchronization Mechanisms**: Classical IPC that actors can use - - :ref:`class s4u::Barrier ` - - :ref:`class s4u::ConditionVariable ` - - :ref:`class s4u::Mutex ` - - :ref:`class s4u::Semaphore ` + - :ref:`class s4u::Barrier ` + - :ref:`class s4u::ConditionVariable ` + - :ref:`class s4u::Mutex ` + - :ref:`class 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 ` that -consumes the *transmiting power* of :ref:`s4u::Link -` resources. +:ref:`s4u::Comm ` that consumes the *transmiting power* of +:ref:`s4u::Link ` resources. -....................... +======================= Asynchronous Activities -....................... +======================= Every activity can be either **blocking** or **asynchronous**. For example, :cpp:func:`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 ` are created with + - :ref:`s4u::CommPtr ` are created with :cpp:func:`s4u::Mailbox::put_async() ` and :cpp:func:`s4u::Mailbox::get_async() `. - - :ref:`s4u::IoPtr ` are created with + - :ref:`s4u::IoPtr ` are created with :cpp:func:`s4u::Storage::read_async() ` and :cpp:func:`s4u::Storage::write_async() `. - - :ref:`s4u::ExecPtr ` are created with + - :ref:`s4u::ExecPtr ` are created with :cpp:func:`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 `_ @@ -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 diff --git a/docs/source/app_smpi.rst b/docs/source/app_smpi.rst index 53e0f23a74..ade7f20ccd 100644 --- a/docs/source/app_smpi.rst +++ b/docs/source/app_smpi.rst @@ -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 ................................. diff --git a/docs/source/conf.py b/docs/source/conf.py index a70134e48d..350b49c27f 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -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 diff --git a/docs/source/index.rst b/docs/source/index.rst index b2276d9edc..c5f5185586 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -21,9 +21,14 @@ Welcome to SimGrid's documentation! :caption: User Manual: Introduction +    Main Concepts +    Installing SimGrid +    Start your Own Project Describing your Application    The S4U Interface    The SMPI Interface +    The MSG Interface +    The Java Bindings Describing the Simulated Platform Describing the Experimental Scenario    Configuring SimGrid @@ -33,9 +38,3 @@ Welcome to SimGrid's documentation! The SimGrid Community Frequently Asked Questions -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: API Reference: - - API diff --git a/docs/source/intro_concepts.rst b/docs/source/intro_concepts.rst index b33ab776a2..a952fc2f71 100644 --- a/docs/source/intro_concepts.rst +++ b/docs/source/intro_concepts.rst @@ -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 + diff --git a/docs/source/intro_install.rst b/docs/source/intro_install.rst index ea1761a860..e441110377 100644 --- a/docs/source/intro_install.rst +++ b/docs/source/intro_install.rst @@ -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 ^^^^^^^^^^^^^^^^^^^ diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index 1699548d3c..d6bbd689aa 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst @@ -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 diff --git a/docs/source/scenar_config.rst b/docs/source/scenar_config.rst index e12daa23b8..192a96c52e 100644 --- a/docs/source/scenar_config.rst +++ b/docs/source/scenar_config.rst @@ -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 diff --git a/examples/s4u/README.rst b/examples/s4u/README.rst index a1f2bf4c46..9293cb5ecf 100644 --- a/examples/s4u/README.rst +++ b/examples/s4u/README.rst @@ -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 `_ 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 `_ 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 `_ -.......................... +========================== 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 `_ 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 `_ 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 `_ -............................. -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 `_ |br| `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 `_ |br| `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 `_ -........................ +======================== 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 `_ 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 `_ Distributed Hash Tables (DHT) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------------------------- - **Chord Protocol** One of the most famous DHT protocol. diff --git a/include/simgrid/msg.h b/include/simgrid/msg.h index 154c19510d..1df82a2f52 100644 --- a/include/simgrid/msg.h +++ b/include/simgrid/msg.h @@ -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 location (or host) is any possible place where a process may run. Thus it is represented as a + * physical resource with computing capabilities, some mailboxes to enable running process to + * communicate with remote ones, and some private data 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 task may then be defined by a computing - amount, a message size and some private - data. + * + * Since most scheduling algorithms rely on a concept of task that can be either computed locally or + * transferred on another processor, it seems to be the right level of abstraction for our purposes. + * A task may then be defined by a computing amount, a message size and + * some private data. */ 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 code, void* data, diff --git a/src/msg/msg_global.cpp b/src/msg/msg_global.cpp index 06c261a777..22dfa7ca65 100644 --- a/src/msg/msg_global.cpp +++ b/src/msg/msg_global.cpp @@ -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); diff --git a/src/msg/msg_gos.cpp b/src/msg/msg_gos.cpp index 3c8121b2d3..d393195b8f 100644 --- a/src/msg/msg_gos.cpp +++ b/src/msg/msg_gos.cpp @@ -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(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 diff --git a/src/msg/msg_process.cpp b/src/msg/msg_process.cpp index 590bd240ab..643e190fa3 100644 --- a/src/msg/msg_process.cpp +++ b/src/msg/msg_process.cpp @@ -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, diff --git a/src/msg/msg_task.cpp b/src/msg/msg_task.cpp index 1ae411724b..7a51afd370 100644 --- a/src/msg/msg_task.cpp +++ b/src/msg/msg_task.cpp @@ -7,14 +7,6 @@ #include "src/simix/smx_private.hpp" #include -/** @addtogroup m_task_management - * - * Since most scheduling algorithms rely on a concept of task that can be either computed locally or - * transferred on another processor, it seems to be the right level of abstraction for our purposes. - * A task may then be defined by a computing amount, a message size and - * some private data. - */ - 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(). diff --git a/tools/cmake/DefinePackages.cmake b/tools/cmake/DefinePackages.cmake index 75684f46cd..64480a6087 100644 --- a/tools/cmake/DefinePackages.cmake +++ b/tools/cmake/DefinePackages.cmake @@ -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