From d8eb62b207b566949a0d9ce649a7b21e226b9168 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Wed, 18 Jul 2018 01:51:00 +0200 Subject: [PATCH] doxygen: uniformity in command markers (@ vs. \) --- README.coding | 49 +- doc/Doxyfile.in | 2 +- doc/doxygen/FAQ.doc | 136 ++-- doc/doxygen/examples.doc | 80 +- doc/doxygen/inside_cmake.doc | 32 +- doc/doxygen/inside_doxygen.doc | 24 +- doc/doxygen/inside_extending.doc | 28 +- doc/doxygen/inside_release.doc | 32 +- doc/doxygen/inside_tests.doc | 66 +- doc/doxygen/module-index.doc | 12 +- doc/doxygen/module-msg.doc | 26 +- doc/doxygen/module-s4u.doc | 2 +- doc/doxygen/module-simix.doc | 2 +- doc/doxygen/module-surf.doc | 66 +- doc/doxygen/module-trace.doc | 10 +- doc/doxygen/module-xbt.doc | 32 +- doc/doxygen/ns3.doc | 34 +- doc/doxygen/options.doc | 764 +++++++++--------- doc/doxygen/outcomes_vizu.doc | 268 +++--- doc/doxygen/platform.doc | 626 +++++++------- doc/doxygen/platform_lua.doc | 2 +- doc/doxygen/uhood.doc | 16 +- doc/doxygen/uhood_arch.doc | 44 +- doc/tuto-msg/tuto-msg.doc | 80 +- .../msg/app-masterworker/app-masterworker.c | 2 +- examples/msg/dht-pastry/dht-pastry.c | 10 +- examples/s4u/README.doc | 72 +- .../app-masterworker/s4u-app-masterworker.cpp | 2 +- examples/s4u/dht-chord/s4u-dht-chord-node.cpp | 34 +- include/simgrid/host.h | 94 +-- include/simgrid/kernel/resource/Action.hpp | 6 +- include/simgrid/kernel/resource/Model.hpp | 4 +- .../simgrid/kernel/routing/FatTreeZone.hpp | 10 +- include/simgrid/msg.h | 25 +- include/simgrid/s4u/Link.hpp | 2 +- include/simgrid/simdag.h | 4 +- include/simgrid/simix.h | 6 +- include/xbt/config.h | 18 +- include/xbt/cunit.h | 2 +- include/xbt/dict.h | 22 +- include/xbt/dynar.h | 90 +-- include/xbt/log.h | 109 +-- include/xbt/mallocator.h | 4 +- include/xbt/parmap.h | 28 +- include/xbt/synchro.h | 4 +- include/xbt/sysdep.h | 4 +- include/xbt/xbt_os_thread.h | 8 +- src/bindings/java/org/simgrid/msg/VM.java | 4 +- src/bindings/lua/lua_debug.cpp | 8 +- src/bindings/lua/lua_host.cpp | 52 +- src/bindings/lua/lua_platf.cpp | 4 +- src/bindings/lua/simgrid_lua.cpp | 20 +- src/include/surf/surf.hpp | 44 +- src/include/xbt/parmap.hpp | 50 +- src/instr/instr_interface.cpp | 542 ++++++------- src/kernel/activity/ConditionVariableImpl.cpp | 8 +- src/kernel/activity/MailboxImpl.cpp | 2 +- src/kernel/activity/MutexImpl.cpp | 4 +- src/kernel/lmm/lagrange.cpp | 30 +- src/kernel/lmm/maxmin.cpp | 12 +- src/mc/VisitedState.cpp | 3 +- src/mc/checker/LivenessChecker.cpp | 2 +- src/mc/mc_dwarf.cpp | 133 ++- src/mc/mc_dwarf_attrnames.cpp | 6 +- src/mc/mc_dwarf_tagnames.cpp | 6 +- src/mc/sosp/mc_checkpoint.cpp | 12 +- src/msg/msg_global.cpp | 13 +- src/msg/msg_gos.cpp | 326 ++++---- src/msg/msg_process.cpp | 112 +-- src/msg/msg_task.cpp | 122 +-- src/plugins/file_system/s4u_FileSystem.cpp | 34 +- src/plugins/host_dvfs.cpp | 7 +- src/plugins/host_energy.cpp | 34 +- src/plugins/host_load.cpp | 8 +- src/plugins/link_energy.cpp | 10 +- src/s4u/s4u_Actor.cpp | 82 +- src/s4u/s4u_Host.cpp | 86 +- src/s4u/s4u_Mailbox.cpp | 10 +- src/s4u/s4u_Storage.cpp | 44 +- src/simdag/sd_global.cpp | 46 +- src/simdag/sd_task.cpp | 224 ++--- src/simix/ActorImpl.cpp | 48 +- src/simix/libsmx.cpp | 136 ++-- src/simix/popping_private.hpp | 2 +- src/simix/smx_context.cpp | 30 +- src/simix/smx_deployment.cpp | 33 +- src/simix/smx_environment.cpp | 8 +- src/simix/smx_global.cpp | 39 +- src/simix/smx_host.cpp | 2 +- src/simix/smx_network.cpp | 24 +- src/simix/smx_synchro.cpp | 4 +- src/smpi/include/smpi_coll.hpp | 2 +- src/smpi/internals/smpi_actor.cpp | 4 +- src/smpi/internals/smpi_deployment.cpp | 10 +- src/smpi/internals/smpi_dvfs.cpp | 20 +- src/smpi/internals/smpi_static_variables.cpp | 2 +- src/smpi/plugins/sampi_loadbalancer.cpp | 6 +- src/surf/cpu_ti.cpp | 90 +-- src/surf/network_interface.cpp | 4 +- src/surf/network_interface.hpp | 8 +- src/surf/sg_platf.cpp | 4 +- src/surf/surf_interface.hpp | 76 +- src/surf/trace_mgr.hpp | 4 +- src/xbt/dict.cpp | 117 ++- src/xbt/dict_cursor.c | 2 +- src/xbt/dynar.cpp | 82 +- src/xbt/ex.cpp | 2 +- src/xbt/log.c | 12 +- src/xbt/log_private.h | 6 +- src/xbt/mallocator.c | 37 +- src/xbt/mmalloc/swag.c | 34 +- src/xbt/xbt_os_time.c | 4 +- src/xbt/xbt_replay.cpp | 21 +- tools/generate-dwarf-functions | 12 +- 114 files changed, 2984 insertions(+), 2994 deletions(-) diff --git a/README.coding b/README.coding index c2fd8fbfbe..6b3d048dde 100644 --- a/README.coding +++ b/README.coding @@ -43,6 +43,30 @@ SimGrid4 will follow the these rules: This is different from the old convention (described below), that should not be used in S4U and its bindings, nor in the kernel. +** +** Commenting the source: doxygen +** +**************************************************** + +The global structure of the documentation is in doc/modules.doc + +The structure of each module (xbt, msg, etc) is in doc/module-.doc + +The structure of a module is in its public header. This way, you're sure to +see all the public interface (and only it). The different parts of the +interface are grouped using the @name construct, even if it's buggy. Since +parts often get reordered, it's better to add numbers to the parts (so that +users can see the intended order). + +The documentation of each type and macro are also in the public header since +this is were they live. + +The documentation of each function must be in the C++ file were it lives. + +Any public element (function, type and macro) must have a @brief part. + +We use @ as a command marker, not \ (so, use @brief not \brief) + ** ** OLD Type naming standard in SimGrid3 ** @@ -68,31 +92,6 @@ Example: Moreover, only toto_t (and e_toto_t) are public. The rest (mainly s_toto_t) is private. -If you see any part of the code not following this convention, this is a -bug. Please report it (or fix it yourself if you can). - -** -** Commenting the source: doxygen -** -**************************************************** - -The global structure of the documentation is in doc/modules.doc - -The structure of each module (xbt, msg, etc) is in doc/module-.doc - -The structure of a module is in its public header. This way, you're sure to -see all the public interface (and only it). The different parts of the -interface are grouped using the @name construct, even if it's buggy. Since -parts often get reordered, it's better to add numbers to the parts (so that -users can see the intended order). - -The documentation of each type and macro are also in the public header since -this is were they live. - -The documentation of each function must be in the C file were it lives. - -Any public element (function, type and macro) must have a @brief part. - * * SimGrid Hacker Survival Guide (FIXME: should be betterly placed) diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 9b2afe71a3..512e3c0ae8 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -161,7 +161,7 @@ JAVADOC_AUTOBRIEF = YES # interpret the first line (until the first dot) of a Qt-style # comment as the brief description. If set to NO, the comments # will behave just like regular Qt-style comments (thus requiring -# an explicit \brief command for a brief description.) +# an explicit @brief command for a brief description.) QT_AUTOBRIEF = NO diff --git a/doc/doxygen/FAQ.doc b/doc/doxygen/FAQ.doc index 15a35ec156..6682d8d2f4 100644 --- a/doc/doxygen/FAQ.doc +++ b/doc/doxygen/FAQ.doc @@ -1,10 +1,10 @@ -/*! \page FAQ MSG Frequently Asked Questions +/*! @page FAQ MSG Frequently Asked Questions @tableofcontents This document is the FAQ of the MSG interface. Some entries are a bit aging and it should be refreshed at some point. -\section faq_simgrid I'm new to SimGrid. I have some questions. Where should I start? +@section faq_simgrid I'm new to SimGrid. I have some questions. Where should I start? You are at the right place... To understand what you can do or cannot do with SimGrid, you should read the @@ -14,12 +14,12 @@ material on the blog of Martin Quinson. -Another great source of inspiration can be found in the \ref s4u_examples. +Another great source of inspiration can be found in the @ref s4u_examples. If you are stuck at any point and if this FAQ cannot help you, please drop us a mail to the user mailing list: . -\subsection faq_interfaces What is the difference between MSG and SimDag? Do they serve the same purpose? +@subsection faq_interfaces What is the difference between MSG and SimDag? Do they serve the same purpose? It depend on how you define "purpose", I guess ;) @@ -37,20 +37,20 @@ With MSG, your application is seen as a set of communicating processes, exchanging data by the way of messages and performing computation on their own. -\subsection faq_visualization Visualizing and analyzing the results +@subsection faq_visualization Visualizing and analyzing the results It is sometime convenient to "see" how the agents are behaving. If you like colors, you can use tools/MSG_visualization/colorize.pl as a filter to your MSG outputs. It works directly with INFO. Beware, INFO() prints on stderr. Do not forget to redirect if you want to filter (e.g. with bash): -\verbatim +@verbatim ./msg_test small_platform.xml small_deployment.xml 2>&1 | ../../tools/MSG_visualization/colorize.pl -\endverbatim +@endverbatim -We also have a more graphical output. Have a look at section \ref options_tracing. +We also have a more graphical output. Have a look at section @ref options_tracing. -\subsection faq_C Argh! Do I really have to code in C? +@subsection faq_C Argh! Do I really have to code in C? We provide Java bindings of the MSG interface, which is the main SimGrid user API. @@ -63,9 +63,9 @@ compiler won't work and it wouldn't help if you could). For now, we do not feel a real demand for any other language. But if you think there is one, please speak up! -\section faq_howto Feature related questions +@section faq_howto Feature related questions -\subsection faq_MIA "Could you please add (your favorite feature here) to SimGrid?" +@subsection faq_MIA "Could you please add (your favorite feature here) to SimGrid?" Here is the deal. The whole SimGrid project (MSG, SURF, ...) is meant to be kept as simple and generic as possible. We cannot add @@ -86,9 +86,9 @@ You'll find in this section a few "Missing In Action" features. Many people have asked about it and we have given hints on how to simply do it with MSG. Feel free to contribute... -\subsection faq_MIA_MSG MSG features +@subsection faq_MIA_MSG MSG features -\subsubsection faq_MIA_examples I want some more complex MSG examples! +@subsubsection faq_MIA_examples I want some more complex MSG examples! Many people have come to ask me a more complex example and each time, they have realized afterward that the basics were in the previous three @@ -111,7 +111,7 @@ tried to document the examples so that they are understandable. Tell us if something is not clear and once again feel free to participate! :) -\subsubsection faq_MIA_taskdup Missing in action: MSG Task duplication/replication +@subsubsection faq_MIA_taskdup Missing in action: MSG Task duplication/replication There is no task duplication in MSG. When you create a task, you can process it or send it somewhere else. As soon as a process has sent @@ -136,7 +136,7 @@ and MSG_task_get_data(). You could use a dictionary (#xbt_dict_t) of dynars (#xbt_dynar_t). If you still don't see how to do it, please come back to us... -\subsubsection faq_MIA_thread_synchronization How to synchronize my user processes? +@subsubsection faq_MIA_thread_synchronization How to synchronize my user processes? It depends on why you want to synchronize them. If you just want to have a shared state between your processes, then you probably don't @@ -173,7 +173,7 @@ mailboxes. Typically, if you need one process to notify another one, you could use a condition variable or a semphore, but sending a message to a specific mailbox does the trick in most cases. -\subsubsection faq_MIA_host_load Where is the get_host_load function hidden in MSG? +@subsubsection faq_MIA_host_load Where is the get_host_load function hidden in MSG? There is no such thing because its semantic wouldn't be really clear. Of course, it is something about the amount of host throughput, @@ -202,7 +202,7 @@ would have to do out of the simulator, and thus gives you information that you could also get in real settings to not hinder the realism of your simulation. -\code +@code double get_host_load() { m_task_t task = MSG_task_create("test", 0.001, 0, NULL); double date = MSG_get_clock(); @@ -212,13 +212,13 @@ double get_host_load() { MSG_task_destroy(task); return (0.001/date); } -\endcode +@endcode Of course, it may not match your personal definition of "host load". In this case, please detail what you mean on the mailing list, and we will extend this FAQ section to fit your taste if possible. -\subsubsection faq_MIA_communication_time How can I get the *real* communication time? +@subsubsection faq_MIA_communication_time How can I get the *real* communication time? Communications are synchronous and thus if you simply get the time before and after a communication, you'll only get the transmission @@ -227,7 +227,7 @@ account the time spent waiting for the other party to be ready). However, getting the *real* communication time is not really hard either. The following solution is a good starting point. -\code +@code int sender() { m_task_t task = MSG_task_create("Task", task_comp_size, task_comm_size, @@ -252,11 +252,11 @@ int receiver() MSG_task_destroy(task); return 0; } -\endcode +@endcode -\subsection faq_MIA_SimDag SimDag related questions +@subsection faq_MIA_SimDag SimDag related questions -\subsubsection faq_SG_comm Implementing communication delays between tasks. +@subsubsection faq_SG_comm Implementing communication delays between tasks. A classic question of SimDag newcomers is about how to express a communication delay between tasks. The thing is that in SimDag, both @@ -265,10 +265,10 @@ model a data dependency between two DAG tasks t1 and t2, you have to create 3 SD_tasks: t1, t2 and c and add dependencies in the following way: -\code +@code SD_task_dependency_add(t1, c); SD_task_dependency_add(c, t2); -\endcode +@endcode This way task t2 cannot start before the termination of communication c which in turn cannot start before t1 ends. @@ -281,7 +281,7 @@ comprising the workstations on which t1 and t2 are scheduled (w1 and w2 for example) and build a communication matrix that should look like [0;amount ; 0; 0]. -\subsubsection faq_SG_DAG How to implement a distributed dynamic scheduler of DAGs. +@subsubsection faq_SG_DAG How to implement a distributed dynamic scheduler of DAGs. Distributed is somehow "contagious". If you start making distributed decisions, there is no way to handle DAGs directly anymore (unless I @@ -290,7 +290,7 @@ communicating process to make the whole scheduling process distributed. Here is an example of how you could do that. Assume T1 has to be done before T2. -\code +@code int your_agent(int argc, char *argv[] { ... T1 = MSG_task_create(...); @@ -307,15 +307,15 @@ has to be done before T2. } } } -\endcode +@endcode If you decide that the distributed part is not that much important and that DAG is really the level of abstraction you want to work with, then you should -give a try to \ref SD_API. +give a try to @ref SD_API. -\subsection faq_MIA_generic Generic features +@subsection faq_MIA_generic Generic features -\subsubsection faq_MIA_batch_scheduler Is there a native support for batch schedulers in SimGrid? +@subsubsection faq_MIA_batch_scheduler Is there a native support for batch schedulers in SimGrid? No, there is no native support for batch schedulers and none is planned because this is a very specific need (and doing it in a @@ -324,7 +324,7 @@ their own batch schedulers. Vincent Garonne wrote one during his PhD and put his code in the contrib directory of our SVN so that other can keep working on it. You may find inspiring ideas in it. -\subsubsection faq_MIA_checkpointing I need a checkpointing thing +@subsubsection faq_MIA_checkpointing I need a checkpointing thing Actually, it depends on whether you want to checkpoint the simulation, or to simulate checkpoints. @@ -332,7 +332,7 @@ simulate checkpoints. The first one could help if your simulation is a long standing process you want to keep running even on hardware issues. It could also help to rewind the simulation by jumping sometimes on an old checkpoint to -cancel recent calculations.\n +cancel recent calculations.@n Unfortunately, such thing will probably never exist in SG. One would have to duplicate all data structures because doing a rewind at the simulator level is very very hard (not talking about the malloc free operations that might @@ -346,7 +346,7 @@ If you want to simulate checkpoints instead, it means that you want the state of an executing task (in particular, the progress made towards completion) to be saved somewhere. So if a host (and the task executing on it) fails (cf. #MSG_HOST_FAILURE), then the task can be restarted -from the last checkpoint.\n +from the last checkpoint.@n Actually, such a thing does not exist in SimGrid either, but it's just because we don't think it is fundamental and it may be done in the user code @@ -355,9 +355,9 @@ periodically get the remaining amount of things to do (using MSG_task_get_remaining_computation()), or fragment the task in smaller subtasks. -\subsection faq_platform Platform building and Dynamic resources +@subsection faq_platform Platform building and Dynamic resources -\subsubsection faq_platform_example Where can I find SimGrid platform files? +@subsubsection faq_platform_example Where can I find SimGrid platform files? There are several little examples in the archive, in the examples/msg directory. From time to time, we are asked for other files, but we @@ -368,7 +368,7 @@ You should refer to the Platform Description Archive have available, as well as the Simulacrum simulator, meant to generate SimGrid platforms using all classical generation algorithms. -\subsubsection faq_platform_alnem How can I automatically map an existing platform? +@subsubsection faq_platform_alnem How can I automatically map an existing platform? We are working on a project called ALNeM (Application-Level Network Mapper) which goal is to automatically discover the topology of an @@ -378,7 +378,7 @@ their own lab network (and contribute them to the catalog project). This tool is not ready yet, but it move quite fast forward. Just stay tuned. -\subsubsection faq_platform_synthetic Generating synthetic but realistic platforms +@subsubsection faq_platform_synthetic Generating synthetic but realistic platforms The third possibility to get a platform file (after manual or automatic mapping of real platforms) is to generate synthetic @@ -402,7 +402,7 @@ note that although sound, this model were never scientifically assessed. Please keep this fact in mind when using it. -\subsubsection faq_platform_random Using random variable for the resource power or availability +@subsubsection faq_platform_random Using random variable for the resource power or availability The best way to model the resouce power using a random variable is to use an availability trace that is directed by a probability @@ -441,9 +441,9 @@ myconnect.element = "mylink"; sg_platf_trace_connect(myconnect); @endcode -\section faq_troubleshooting Troubleshooting +@section faq_troubleshooting Troubleshooting -\subsection faq_trouble_changelog The feature X stopped to work after my last update +@subsection faq_trouble_changelog The feature X stopped to work after my last update I guess that you want to read the ChangeLog file, that always contains all the information that could be important to the users during the @@ -458,13 +458,13 @@ should update to the new way of doing things, but if you can't afford it, that's ok. Just stick to the last version that were working for you, and have a pleasant day. -\subsection faq_trouble_lib_compil SimGrid compilation and installation problems +@subsection faq_trouble_lib_compil SimGrid compilation and installation problems -\subsubsection faq_trouble_lib_config cmake fails! +@subsubsection faq_trouble_lib_config cmake fails! We know only one reason for the configure to fail: - - You are using a broken build environment\n + - You are using a broken build environment@n Try updating your cmake version. If symptom is that the configury magic complains about gcc not being able to build executables, you are probably missing the libc6-dev package. Damn Ubuntu. @@ -472,7 +472,7 @@ We know only one reason for the configure to fail: If you experience other kind of issue, please get in touch with us. We are always interested in improving our portability to new systems. -\subsubsection faq_trouble_distcheck Dude! "ctest" fails on my machine! +@subsubsection faq_trouble_distcheck Dude! "ctest" fails on my machine! Don't assume we never run this target, because we do. Check http://cdash.inria.fr/CDash/index.php?project=Simgrid (click on @@ -482,19 +482,19 @@ https://buildd.debian.org/status/logs.php?pkg=simgrid if you don't believe us. If it's failing on your machine in a way not experienced by the autobuilders above, please drop us a mail on the mailing list so that -we can check it out. Make sure to read \ref faq_bugrepport before you +we can check it out. Make sure to read @ref faq_bugrepport before you do so. -\subsection faq_trouble_compil User code compilation problems +@subsection faq_trouble_compil User code compilation problems -\subsubsection faq_trouble_err_logcat "gcc: _simgrid_this_log_category_does_not_exist__??? undeclared (first use in this function)" +@subsubsection faq_trouble_err_logcat "gcc: _simgrid_this_log_category_does_not_exist__??? undeclared (first use in this function)" This is because you are using the log mechanism, but you didn't created -any default category in this file. You should refer to \ref XBT_log +any default category in this file. You should refer to @ref XBT_log for all the details, but you simply forgot to call one of XBT_LOG_NEW_DEFAULT_CATEGORY() or XBT_LOG_NEW_DEFAULT_SUBCATEGORY(). -\subsubsection faq_trouble_pthreadstatic "gcc: undefined reference to pthread_key_create" +@subsubsection faq_trouble_pthreadstatic "gcc: undefined reference to pthread_key_create" This indicates that one of the library SimGrid depends on (libpthread here) was missing on the linking command line. Dependencies of @@ -506,9 +506,9 @@ of SimGrid), you must absolutely specify -lpthread on the linker command line. As usual, this should come after -lsimgrid on this command line. -\subsection faq_trouble_errors Runtime error messages +@subsection faq_trouble_errors Runtime error messages -\subsubsection faq_trouble_errors_big_fat_warning I'm told that my XML files are too old. +@subsubsection faq_trouble_errors_big_fat_warning I'm told that my XML files are too old. The format of the XML platform description files is sometimes improved. For example, we decided to change the units used in SimGrid @@ -525,7 +525,7 @@ of the root tag. Currently, it should read: If your files are too old, you can use the simgrid_update_xml.pl script which can be found in the tools directory of the archive. -\subsection faq_trouble_debug Debugging SMPI applications +@subsection faq_trouble_debug Debugging SMPI applications In order to debug SMPI programs, you can use the following options: @@ -538,16 +538,16 @@ In order to debug SMPI programs, you can use the following options: Both options are needed in order to run the SMPI process under GDB. -\subsection faq_trouble_valgrind Valgrind-related and other debugger issues +@subsection faq_trouble_valgrind Valgrind-related and other debugger issues If you don't, you really should use valgrind to debug your code, it's almost magic. -\subsubsection faq_trouble_vg_libc Valgrind spits tons of errors about backtraces! +@subsubsection faq_trouble_vg_libc Valgrind spits tons of errors about backtraces! It may happen that valgrind, the memory debugger beloved by any decent C programmer, spits tons of warnings like the following : -\verbatim ==8414== Conditional jump or move depends on uninitialised value(s) +@verbatim ==8414== Conditional jump or move depends on uninitialised value(s) ==8414== at 0x400882D: (within /lib/ld-2.3.6.so) ==8414== by 0x414EDE9: (within /lib/tls/i686/cmov/libc-2.3.6.so) ==8414== by 0x400B105: (within /lib/ld-2.3.6.so) @@ -560,7 +560,7 @@ programmer, spits tons of warnings like the following : ==8414== by 0x80764C1: xbt_dictelm_get (dict_elm.c:732) ==8414== by 0x8079010: xbt_cfg_register (config.c:208) ==8414== by 0x806821B: MSG_config (msg_config.c:42) -\endverbatim +@endverbatim This problem is somewhere in the libc when using the backtraces and there is very few things we can do ourselves to fix it. Instead, here is how to tell @@ -569,7 +569,7 @@ create this file on need). Make sure to change the obj line according to your personnal mileage (change 2.3.6 to the actual version you are using, which you can retrieve with a simple "ls /lib/ld*.so"). -\verbatim { +@verbatim { name: Backtrace madness Memcheck:Cond obj:/lib/ld-2.3.6.so @@ -578,7 +578,7 @@ which you can retrieve with a simple "ls /lib/ld*.so"). fun:do_dlopen fun:dlerror_run fun:__libc_dlopen_mode -}\endverbatim +}@endverbatim Then, you have to specify valgrind to use this suppression file by passing the --suppressions=$HOME/.valgrind.supp option on the command line. @@ -587,9 +587,9 @@ automatically. Actually, it passes a bit more options to valgrind, and this happen to be my personnal settings. Check the valgrind documentation for more information. -\verbatim export VALGRIND_OPTS="--leak-check=yes --leak-resolution=high --num-callers=40 --tool=memcheck --suppressions=$HOME/.valgrind.supp" \endverbatim +@verbatim export VALGRIND_OPTS="--leak-check=yes --leak-resolution=high --num-callers=40 --tool=memcheck --suppressions=$HOME/.valgrind.supp" @endverbatim -\subsubsection faq_trouble_backtraces Truncated backtraces +@subsubsection faq_trouble_backtraces Truncated backtraces When debugging SimGrid, it's easier to pass the --disable-compiler-optimization flag to the configure if valgrind or @@ -598,12 +598,12 @@ should remove these flag when everything works before going in production (before launching your 1252135 experiments), or everything will run only one half of the true SimGrid potential. -\subsection faq_deadlock There is a deadlock in my code!!! +@subsection faq_deadlock There is a deadlock in my code!!! Unfortunately, we cannot debug every code written in SimGrid. We furthermore believe that the framework provides ways enough information to debug such information yourself. If the textual output -is not enough, Make sure to check the \ref faq_visualization FAQ entry to see +is not enough, Make sure to check the @ref faq_visualization FAQ entry to see how to get a graphical one. Now, if you come up with a really simple example that deadlocks and @@ -612,7 +612,7 @@ list. Just be aware that you'll be severely punished if the mistake is on your side... We have plenty of FAQ entries to redact and new features to implement for the impenitents! ;) -\subsection faq_surf_network_latency I get weird timings when I play with the latencies. +@subsection faq_surf_network_latency I get weird timings when I play with the latencies. OK, first of all, remember that units should be Bytes, Flops and Seconds. If you don't use such units, some SimGrid constants (e.g. the @@ -622,10 +622,10 @@ right unit and you'll end up with weird results. Here is what happens with a single transfer of size L on a link (bw,lat) when nothing else happens. -\verbatim +@verbatim 0-----lat--------------------------------------------------t |-----|**** real_bw =min(bw,SG_TCP_CTE_GAMMA/(2*lat)) *****| -\endverbatim +@endverbatim In more complex situations, this min is the solution of a complex max-min linear system. Have a look @@ -653,7 +653,7 @@ that may make your result be unexpected. For example, two flows competing on a saturated link receive an amount of bandwidth inversely proportional to their round trip time. -\subsection faq_bugrepport So I've found a bug in SimGrid. How to report it? +@subsection faq_bugrepport So I've found a bug in SimGrid. How to report it? We do our best to make sure to hammer away any bugs of SimGrid, but this is still an academic project so please be patient if/when you find bugs in it. @@ -672,6 +672,4 @@ informative bug repports: http://www.chiark.greenend.org.uk/~sgtatham/bugs.html (it is not SimGrid specific at all, but it's full of good advices). -\author Da SimGrid team - */ diff --git a/doc/doxygen/examples.doc b/doc/doxygen/examples.doc index fa473b21e2..78ca077bec 100644 --- a/doc/doxygen/examples.doc +++ b/doc/doxygen/examples.doc @@ -1,22 +1,22 @@ -/*! \page examples SimGrid Examples +/*! @page examples SimGrid Examples -\tableofcontents +@tableofcontents SimGrid comes with many examples provided in the examples/ directory. -Those examples are described in section \ref msg_examples. Those +Those examples are described in section @ref msg_examples. Those examples are commented and should be easy to understand. for a first step into SimGrid we also provide some more detailed examples in the sections below. -\htmlonly +@htmlonly You should also check our online tutorial section that contains a generic tutorial about using SimGrid. -\endhtmlonly +@endhtmlonly -\section using_msg Using MSG +@section using_msg Using MSG -\htmlonly +@htmlonly You should also check our online tutorial section that contains a dedicated tutorial. -\endhtmlonly +@endhtmlonly Here are some examples on how to use MSG, the most used API. @@ -24,32 +24,32 @@ MSG comes with an extensive set of examples. It is sometimes difficult to find the one you need. This list aims at helping you finding the example from which you can learn what you want to. -\subsection MSG_ex_basics Basic examples and features +@subsection MSG_ex_basics Basic examples and features -\subsubsection MSG_ex_master_worker Basic Master/Workers +@subsubsection MSG_ex_master_worker Basic Master/Workers Simulation of a master-worker application using a realistic platform and an external description of the deployment. -\paragraph MSG_ex_mw_TOC Table of contents: +@paragraph MSG_ex_mw_TOC Table of contents: - - \ref MSG_ext_mw_preliminary - - \ref MSG_ext_mw_master - - \ref MSG_ext_mw_worker - - \ref MSG_ext_mw_core - - \ref MSG_ext_mw_platform - - \ref MSG_ext_mw_application + - @ref MSG_ext_mw_preliminary + - @ref MSG_ext_mw_master + - @ref MSG_ext_mw_worker + - @ref MSG_ext_mw_core + - @ref MSG_ext_mw_platform + - @ref MSG_ext_mw_application
-\dontinclude msg/app-masterworker/app-masterworker.c +@dontinclude msg/app-masterworker/app-masterworker.c -\paragraph MSG_ext_mw_preliminary Preliminary declarations +@paragraph MSG_ext_mw_preliminary Preliminary declarations -\skip include -\until example"); -\skipline Master expects +@skip include +@until example"); +@skipline Master expects -\paragraph MSG_ext_mw_master Master code +@paragraph MSG_ext_mw_master Master code This function has to be assigned to a #msg_process_t that will behave as the master. It should not be called directly but either given as a parameter to #MSG_process_create() or registered as a public function through @@ -63,14 +63,14 @@ C style arguments (argc/argv) are interpreted as: Tasks are evenly sent in a round-robin style. -\until return 0; -\until } -\skipline Worker expects +@until return 0; +@until } +@skipline Worker expects -\paragraph MSG_ext_mw_worker Worker code +@paragraph MSG_ext_mw_worker Worker code This function has to be assigned to a #msg_process_t that has to behave as a worker. Just like the master function -(described in \ref MSG_ext_mw_master), it should not be called directly. +(described in @ref MSG_ext_mw_master), it should not be called directly. C style arguments (argc/argv) are interpreted as: - a unique id used to build the mailbox name of the worker @@ -78,10 +78,10 @@ C style arguments (argc/argv) are interpreted as: This function keeps waiting for tasks and executes them as it receives them. When a special task named 'finalize' is received from the master, the process ends its execution. -\until return 0; -\until } +@until return 0; +@until } -\paragraph MSG_ext_mw_core Main function +@paragraph MSG_ext_mw_core Main function This function is the core of the simulation and is divided only into 3 parts: -# Simulation settings : #MSG_create_environment() creates a realistic @@ -93,20 +93,20 @@ This function is the core of the simulation and is divided only into 3 parts: Its arguments are: - platform_file: the name of a file containing an valid platform description. - deployment_file: the name of a file containing a valid application description -\line main -\until OK; -\until } +@line main +@until OK; +@until } -\paragraph MSG_ext_mw_platform Example of a platform file +@paragraph MSG_ext_mw_platform Example of a platform file -The following platform description can be found in \c examples/msg/platforms/small_platform.xml -\include platforms/small_platform.xml +The following platform description can be found in @c examples/msg/platforms/small_platform.xml +@include platforms/small_platform.xml -\paragraph MSG_ext_mw_application Example of a deployment file +@paragraph MSG_ext_mw_application Example of a deployment file -The following application description can be found in \c examples/msg/app-masterworker/app-masterworker_d.xml: +The following application description can be found in @c examples/msg/app-masterworker/app-masterworker_d.xml: -\include msg/app-masterworker/app-masterworker_d.xml +@include msg/app-masterworker/app-masterworker_d.xml */ diff --git a/doc/doxygen/inside_cmake.doc b/doc/doxygen/inside_cmake.doc index f1e570fd5a..ffb7d5c4f2 100644 --- a/doc/doxygen/inside_cmake.doc +++ b/doc/doxygen/inside_cmake.doc @@ -1,20 +1,20 @@ /*! @page inside_cmake Adding source files or examples -\tableofcontents +@tableofcontents SimGrid uses CMake which is a family of tools designed to build, test, and package software. CMake is used to control the software compilation process using simple platform- and compiler-independent configuration files. CMake generates native makefiles and workspaces that can be used in the compiler environment of your choice. For more information see the official CMake web site. -\section inside_cmake_addsrc How to add source files? +@section inside_cmake_addsrc How to add source files? If you want to rename, add, or delete source file(s) in the SimGrid distribution, you have to edit the $SIMGRID_INSTALL_PATH/tools/cmake/DefinePackages.cmake configuration file. Files are organized in sections, then find the section you are interested in and modify it. For instance, a new S4U source file will have to be listed in: -\verbatim +@verbatim set(S4U_SRC src/s4u/s4u_actor.cpp src/s4u/s4u_as.cpp @@ -26,14 +26,14 @@ set(S4U_SRC src/s4u/s4u_mailbox.cpp src/s4u/s4u_storage.cpp ) -\endverbatim +@endverbatim If sources file always have to be included into the library, you are all set. However, ther inclusion may depend on specific compiling options. For instance, if Boost contexts are not available, you don't want to compile the src/simix/ContextBoost.* files but still add them to the source distribution. This is done by adding those files to the EXTRA_DIST list, as follows: -\verbatim +@verbatim if (HAVE_BOOST_CONTEXTS) set(SIMIX_SRC ${SIMIX_SRC} src/simix/ContextBoost.hpp src/simix/ContextBoost.cpp) @@ -41,14 +41,14 @@ else() set(EXTRA_DIST ${EXTRA_DIST} src/simix/ContextBoost.hpp src/simix/ContextBoost.cpp) endif() -\endverbatim +@endverbatim Once you're done, you must run "make distcheck" to ensure that you did not forget to add any file to the distributed archives. This ensures that everything was commited correctly, so you have to first commit before running "make distcheck". If you forgot something, you want to "git commit --amend". But never amend a commit that you already pushed to public repositories! Do a second commit in that case. -\section inside_cmake_examples How to add an example? +@section inside_cmake_examples How to add an example? The first rule is that the content of examples/ must be interesting to the users. It is expected that the users will take one of these examples and start editing it to make it fit their needs. So, it should be self-contained, @@ -76,7 +76,7 @@ instance, examples/msg/CMakeLists.txt starts with a loop over all the (currently - compile and link the source file (which has to be named as the directory - add the source and tesh files to the distribution. -\verbatim +@verbatim foreach(x app-masterworker app-pingpong app-pmm app-token-ring async-wait async-waitall async-waitany cloud-capping cloud-masterworker cloud-migration cloud-multicore cloud-simple cloud-two-tasks dht-chord dht-pastry energy-consumption energy-onoff energy-pstate energy-ptask energy-vm @@ -90,42 +90,42 @@ foreach(x app-masterworker app-pingpong app-pmm app-token-ring async-wait async- set(examples_src ${examples_src} ${CMAKE_CURRENT_SOURCE_DIR}/${x}/${x}.c) set(tesh_files ${tesh_files} ${CMAKE_CURRENT_SOURCE_DIR}/${x}/${x}.tesh) endforeach() -\endverbatim +@endverbatim Some more complex examples may require more than one source file. If it is the case for your example, you will find inspiration in the following example -\verbatim +@verbatim add_executable (bittorrent app-bittorrent/bittorrent.c app-bittorrent/messages.c app-bittorrent/peer.c app-bittorrent/tracker.c app-bittorrent/connection.c) target_link_libraries(bittorrent simgrid) set_target_properties(bittorrent PROPERTIES RUNTIME_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/app-bittorrent) foreach (file bittorrent connection messages peer tracker) set(examples_src ${examples_src} ${CMAKE_CURRENT_SOURCE_DIR}/app-bittorrent/${file}.c ${CMAKE_CURRENT_SOURCE_DIR}/app-bittorrent/${file}.h) endforeach() -\endverbatim +@endverbatim If your example require a deployment file (see @ref deployment for details), name it as the source file adding "_d.xml". Then add the name of your example to this foreach loop. -\verbatim +@verbatim foreach (file app-bittorrent app-chainsend app-masterworker app-pingpong async-wait async-waitall async-waitany dht-chord dht-kademlia dht-pastry io-remote platform-properties maestro-set task-priority) set(xml_files ${xml_files} ${CMAKE_CURRENT_SOURCE_DIR}/${file}/${file}_d.xml) endforeach() -\endverbatim +@endverbatim If your example includes extra source, text, XML, or tesh files, add them to the existing lists. Finally, register your -example to the testing infrastructure. See \ref inside_tests_add_integration for more details. +example to the testing infrastructure. See @ref inside_tests_add_integration for more details. -\verbatim +@verbatim foreach(x app-bittorrent app-chainsend app-masterworker app-pingpong app-token-ring async-wait async-waitall async-waitany cloud-capping cloud-masterworker cloud-migration cloud-simple cloud-two-tasks dht-chord dht-kademlia platform-failures io-file io-remote io-storage task-priority process-kill process-migration process-suspend platform-properties synchro-semaphore process-startkilltime) ADD_TESH_FACTORIES(msg-${x} "thread;ucontext;raw;boost" --setenv bindir=${CMAKE_BINARY_DIR}/examples/msg/${x} --setenv srcdir=${CMAKE_HOME_DIRECTORY}/examples/platforms --cd ${CMAKE_HOME_DIRECTORY}/examples/msg/${x} ${x}.tesh) endforeach() -\endverbatim +@endverbatim Note that the structure of the CMakeLists.txt file may vary from one directory to another, but there are enough existing examples to find one that can be adapted to your own example. diff --git a/doc/doxygen/inside_doxygen.doc b/doc/doxygen/inside_doxygen.doc index 4758cfa02d..2f6f6e8ca2 100644 --- a/doc/doxygen/inside_doxygen.doc +++ b/doc/doxygen/inside_doxygen.doc @@ -1,7 +1,7 @@ /*! @page inside_doxygen Documenting SimGrid -\tableofcontents +@tableofcontents We use doxygen for our documentation. It's annoying but that's the best we've found so far. Stop bitching about the doc or the tools, and @@ -14,13 +14,13 @@ the organization (and reach half the quality) of the TikZ one. But anyway. As they say: Documentation is like sex; when it's not good it's still better than nothing and when it's good it's very very good. -\section inside_doxygen_module Adding a new module to the reference guide +@section inside_doxygen_module Adding a new module to the reference guide If you add a new file to the project, you want to document it. It's more urgent if it's user-visible, but it should be done in any case if possible. -\subsection inside_doxygen_module_create Declaring the module to doxygen +@subsection inside_doxygen_module_create Declaring the module to doxygen First declare your sub-module in the corresponding (project)/doc/doxygen/module-(enclosing module).doc Two edits are @@ -48,7 +48,7 @@ Warning, the location of this block decides where it appears in the documentation. In particular, the order of the defgroups is not inocuitous at all. -\subsection inside_doxygen_module_populate Adding symbols to your module +@subsection inside_doxygen_module_populate Adding symbols to your module Once your group is created and referenced from the group containing it, you must populate it. For that, edit the corresponding header file @@ -79,7 +79,7 @@ symbols that are there only for the compiler, but that the users should not see. In this case, do not put the symbols you want to hide between the @ { and @ } markers. -\subsection inside_doxygen_module_document Documenting the symbols of your module +@subsection inside_doxygen_module_document Documenting the symbols of your module Finally, you naturally need to actually write the documentation of each public symbol belonging to your module. Macros must naturally be @@ -97,7 +97,7 @@ give any information you feel useful to the user. In particular, add links to any other location of the documentation that could provide interesting additional information. -\section inside_doxygen_page Adding a new page to the user guide +@section inside_doxygen_page Adding a new page to the user guide Note that doxygen provides two hierarchies that cannot be intermixed. Groups are used to build a reference guide while pages are used for @@ -105,7 +105,7 @@ any other kind of page in the documentation. A module cannot contain any page, while a page cannot contain any module. That's the doxygen style. -\subsection inside_doxygen_page_write Writing a new documentation page +@subsection inside_doxygen_page_write Writing a new documentation page The first thing to do to add a new page is to actually write a file containing the information you want to add. It should be located in @@ -144,7 +144,7 @@ people building a reference specify a replacement text as in: @ref shortname "text to use instead of the title" @endverbatim -\subsection inside_doxygen_page_doxy Registering a documentation page to doxygen +@subsection inside_doxygen_page_doxy Registering a documentation page to doxygen Edit (project)/doc/Doxyfile.in and add your page to the INPUT variable. Don't edit the Doxyfile directly, as it is generated @@ -164,7 +164,7 @@ That is why every page in our documentation seem to contain a table of contents of sub pages even if it dupplicates what's on the left. That's the doxygen style (but I can live with it). -\subsection inside_doxygen_page_cmake Registering a documentation page to cmake +@subsection inside_doxygen_page_cmake Registering a documentation page to cmake Ahhh, cmake and doxygen. The perfect combo to bitch about life for a whole day... @@ -175,7 +175,7 @@ newly added page to the DOC_SOURCES. And bitch about these damn tools. Don't forget to commit your page, so that you can get some git fun to complete your day. -\section inside_doxygen_image Adding an image to the documentation +@section inside_doxygen_image Adding an image to the documentation If you need to run a command (like fig2dev) to generate your image, edit tools/cmake/GenerateDoc.cmake and add your command to the @@ -189,7 +189,7 @@ register it to cmake by adding it to the DOC_IMG list of file tools/cmake/DefinePackage.cmake so that it lands in the archive distribution. It will also be copied automatically to the documentation. -\section inside_doxygen_website Working on the website +@section inside_doxygen_website Working on the website Our website is generated/exported via [orgmode](http://www.orgmode.org), a tool that we use to facilitate our reproducible research. @@ -201,7 +201,7 @@ but it might be outdated. Contact us if you really want to help.) git clone git://scm.gforge.inria.fr/simgrid/website.git @endverbatim -\section inside_doxygen_regen Regenerating the documentation +@section inside_doxygen_regen Regenerating the documentation Once you've changed the doc, you want to run doxygen to regenerate the html output (and maybe the pdf too). Here is how to do this: diff --git a/doc/doxygen/inside_extending.doc b/doc/doxygen/inside_extending.doc index a1f1286e1f..10d38b63b7 100644 --- a/doc/doxygen/inside_extending.doc +++ b/doc/doxygen/inside_extending.doc @@ -1,22 +1,22 @@ /** @page inside_extending Extending SimGrid -\tableofcontents +@tableofcontents -\section simgrid_dev_guide_model How to add a new model? +@section simgrid_dev_guide_model How to add a new model? The figure below shows the architecture of the SURF layer. This layer is composed of different kinds of models representing the different systems we want to model (i.e., cpu, network, storage, workstation, virtual machine). A model in SimGrid is composed of three classes: Model, Resource and Action -(\ref SURF_interface "surf_interface.hpp"). +(@ref SURF_interface "surf_interface.hpp"). -\image html surf++.png -\image latex surf++.pdf "surf++" width=\textwidth +@image html surf++.png +@image latex surf++.pdf "surf++" width=\textwidth Actually there are five kind of models: CpuModel, NetworkModel, WorkstationModel, WorkstationVMModel and StorageModel. For each kind of model, there is an -interface (e.g.: \ref SURF_cpu_interface "cpu_interface.hpp") and some implementations (e.g.: cpu_cas01.hpp, +interface (e.g.: @ref SURF_cpu_interface "cpu_interface.hpp") and some implementations (e.g.: cpu_cas01.hpp, cpu_ti.hpp). The CPU model Cas01, for instance, is initialized by the function @@ -27,7 +27,7 @@ that is defined as follows: s_surf_model_description_t surf_network_model_description[] = { -\subsection simgrid_dev_guide_model_implem How to implement a new model? +@subsection simgrid_dev_guide_model_implem How to implement a new model? If you want to create a new implementation of a kind of model you must extend the classes of the corresponding interfaces. @@ -64,18 +64,18 @@ s_surf_model_description_t surf_cpu_model_description[] = { }; ~~~~ -\subsection simgrid_dev_guide_model_kind How to add a new kind of model? +@subsection simgrid_dev_guide_model_kind How to add a new kind of model? If you want to create a new kind of model, you must create a new interface where you extend the classes Model, Resource and Action, and then create an implementation of this interface. -\section simgrid_dev_guide_surf_callbacks How to use surf callbacks? +@section simgrid_dev_guide_surf_callbacks How to use surf callbacks? Adding features to surf could also be handle by using surf callbacks (instead of adding new implementation model). The list of available callbacks is -accessible there \ref SURF_callbacks. An example of using surf callbacks is the +accessible there @ref SURF_callbacks. An example of using surf callbacks is the energy plugin. If you want to add a plugin you need to define callback function and to connect them to callbacks handler in an initialization function. @@ -116,10 +116,10 @@ s_surf_model_description_t surf_plugin_description[] = { }; ~~~~ -\section simgrid_dev_guide_simcall How to add a new simcall? +@section simgrid_dev_guide_simcall How to add a new simcall? First of all you might want to avoid defining a new simcall if possible: -\ref simgrid_dev_guide_generic_simcall. +@ref simgrid_dev_guide_generic_simcall. A simcall is used to go from user mode to kernel mode. There is some sort of popping dance involved, as we want to isolate the user @@ -173,7 +173,7 @@ generates the following files: The simcall.in file list all the simcalls in sections. A line starting by "##" define a new section which will be replace by a "ifdef" in the generated code. -\section simgrid_dev_guide_generic_simcall How to avoid adding a new simcall? +@section simgrid_dev_guide_generic_simcall How to avoid adding a new simcall? We now have some generic simcalls which can be used to interface with the Maestro without creating new simcalls. You might want to use them instead of @@ -251,7 +251,7 @@ catch (std::runtime_error& e) { Note: `kernel_sync(f)` could be implemented as `kernel_async(f).get()`. -\section simgrid_dev_guide_tag What is How to add a new tag for xml files? +@section simgrid_dev_guide_tag What is How to add a new tag for xml files? You should not do something like that. Please work instead to make XML avoidable, ie to make the C++ interface nice and usable. diff --git a/doc/doxygen/inside_release.doc b/doc/doxygen/inside_release.doc index 24173733f1..3cbc5eb377 100644 --- a/doc/doxygen/inside_release.doc +++ b/doc/doxygen/inside_release.doc @@ -1,9 +1,9 @@ /*! -\page inside_release Releasing SimGrid +@page inside_release Releasing SimGrid -\section inside_release_c Releasing the main library +@section inside_release_c Releasing the main library -\subsection inside_release_c_preconditions Before releasing +@subsection inside_release_c_preconditions Before releasing Please apply the following checklist before releasing. @@ -30,25 +30,25 @@ Please apply the following checklist before releasing. - The release date is indicated right below the version name - The release dub name matches the one given in ChangeLog file -\subsection inside_release_c_source Building the source archive +@subsection inside_release_c_source Building the source archive This should be done from a clean git repository because some files are included through globbing. The best is to use a clean checkout: -\verbatim +@verbatim cd /tmp git clone --depth=1 ~/Code/simgrid cd simgrid cmake . && make dist -\endverbatim +@endverbatim If you prefer, you can clean your repository the hard way: -\verbatim +@verbatim git reset --hard master # remove all uncommited changes to the files tracked by git git clean -dfx # delete all files and directories that are not tracked by git cmake . && make dist -\endverbatim +@endverbatim -\subsection inside_release_c_jarfile Building the binary jarfile +@subsection inside_release_c_jarfile Building the binary jarfile Get the jarfiles for several OSes on the CI slaves. Use Save under to give a separate name to each of them. @@ -58,7 +58,7 @@ give a separate name to each of them. - Linux: it is safer to rebuild them in a chroot (to avoid boost-context and all other optional dependencies): -\verbatim +@verbatim mkdir /tmp/build-amd64 cp SimGrid-3.*.tar.gz /tmp/build-amd64 sudo debootstrap --arch amd64 --variant=buildd testing /tmp/build-amd64 http://deb.debian.org/debian/ @@ -70,11 +70,11 @@ cd tmp tar xfz ../SimGrid*tar.gz && cd SimGrid-* cmake . -Denable_documentation=ON -Denable_java=ON make -j4 && LC_ALL=C ctest -R java -\endverbatim +@endverbatim Once all jarfiles are in a separate directory, run the following to merge them: -\verbatim +@verbatim mkdir content ; cd content for j in ../simgrid-linux64.jar ../simgrid*.jar ; do unzip -n $j ; done @@ -89,13 +89,13 @@ x86_64-linux-gnu-strip NATIVE/*/*/lib*dll # Gets Windows, down to 22M rm ../simgrid-3_*.jar zip -r ../simgrid-3_XX.jar * # Produced ../simgrid-3_XX.jar is 7.7M -\endverbatim +@endverbatim To upload the file on gforge, you need to go to Files/Admin then clic on the Settings icon near to the "Add a version" button, and then on the settings icon of the release you want to change. -\subsection inside_release_c_postchecks Check list after releasing +@subsection inside_release_c_postchecks Check list after releasing - Tag the git repository (don't forget to push the tags to the main repo) - Push the archive files (tar.gz and jar) on gforge @@ -103,7 +103,7 @@ the settings icon of the release you want to change. - Update the link scm.gforge.inria.fr:/home/groups/simgrid/htdocs/simgrid/latest (and create the directory of the next version) - Rebuild and resynchronize the website so that the file gets visible - from our download page.\n + from our download page.@n - Edit org/org-templates/level-0.org to change the release version, the tgz link and the jar link. - emacs org/site/index.org and C-c C-c the first source block to refresh the news; fake the date in the result. - emacs org/site/download.org and C-c C-c the first source block to refresh the download. @@ -114,7 +114,7 @@ the settings icon of the release you want to change. - Document the tag on https://github.com/simgrid/simgrid/releases - Mail the simgrid-user mailing list - the NEWS chunk in the mail; - - Hall of Fame in the mail\n + - Hall of Fame in the mail@n git shortlog -sne v3.18.. - the ChangeLog chunk as attachment - Also mail some other lists (G5K users), with only the NEWS chunk diff --git a/doc/doxygen/inside_tests.doc b/doc/doxygen/inside_tests.doc index 8188d3b286..9d6d324eee 100644 --- a/doc/doxygen/inside_tests.doc +++ b/doc/doxygen/inside_tests.doc @@ -4,7 +4,7 @@ This page will teach you how to run the tests, selecting the ones you want, and how to add new tests to the archive. -\tableofcontents +@tableofcontents SimGrid code coverage is usually between 70% and 80%, which is much more than most projects out there. This is because we consider SimGrid @@ -22,13 +22,13 @@ every logged line, this ensures that every change of the models' prediction will be noticed. All these tests should ensure that SimGrid is safe to use and to depend on. -\section inside_tests_runintegration Running the tests +@section inside_tests_runintegration Running the tests Running the tests is done using the ctest binary that comes with cmake. These tests are run for every commit and the result is publicly available. -\verbatim +@verbatim ctest # Launch all tests ctest -R msg # Launch only the tests which name match the string "msg" ctest -j4 # Launch all tests in parallel, at most 4 at the same time @@ -37,14 +37,14 @@ ctest --output-on-failure # Only get verbose for the tests that fail ctest -R msg- -j5 --output-on-failure # You changed MSG and want to check that you didn't break anything, huh? # That's fine, I do so all the time myself. -\endverbatim +@endverbatim -\section inside_tests_rununit Running the unit tests +@section inside_tests_rununit Running the unit tests All unit tests are packed into the testall binary, that lives at the source root. These tests are run when you launch ctest, don't worry. -\verbatim +@verbatim make testall # Rebuild the test runner on need ./testall # Launch all tests ./testall --help # revise how it goes if you forgot @@ -52,12 +52,12 @@ make testall # Rebuild the test runner on need ./testall --dump-only # Display all existing test suites ./testall --tests=-all,+dict # Only launch the tests from the dict test suite ./testall --tests=-all,+foo:bar # run only the bar test from the foo suite. -\endverbatim +@endverbatim -\section inside_tests_add_units Adding unit tests +@section inside_tests_add_units Adding unit tests -\warning this section is outdated. New unit tests should be written +@warning this section is outdated. New unit tests should be written using the unit_test_framework component of Boost. There is no such example so far in our codebase, but that's definitely the way to go for the future. STOP USING XBT. @@ -68,7 +68,7 @@ add your source file to the FILES_CONTAINING_UNITTESTS list. For example, if you want to create unit tests in the file src/xbt/plouf.c, your changes should look like that: -\verbatim +@verbatim --- a/tools/cmake/UnitTesting.cmake +++ b/tools/cmake/UnitTesting.cmake @@ -11,6 +11,7 @@ set(FILES_CONTAINING_UNITTESTS @@ -78,7 +78,7 @@ your changes should look like that: ) if(SIMGRID_HAVE_MC) -\endverbatim +@endverbatim Then, you want to actually add your tests in the source file. All the tests must be protected by "#ifdef SIMGRID_TEST" so that they don't @@ -167,7 +167,7 @@ not upset the other developers. Do not hesitate to stress test your code with such unit tests, but make sure that it runs reasonably fast, or nobody will run "ctest" before commiting code. -\section inside_tests_add_integration Adding integration tests +@section inside_tests_add_integration Adding integration tests TESH (the TEsting SHell) is the test runner that we wrote for our integration tests. It is distributed with the SimGrid source file, and @@ -182,7 +182,7 @@ To add a new integration test, you thus have 3 things to do: strive to make this code clear, well documented and informative for the users. If you manage to do so, put this somewhere under examples/ and modify the cmake files as explained on this page: - \ref inside_cmake_examples. If you feel like you should write a + @ref inside_cmake_examples. If you feel like you should write a torture test that is not interesting to the users (because nobody would sanely write something similar in user code), then put it under teshsuite/ somewhere. @@ -190,7 +190,7 @@ To add a new integration test, you thus have 3 things to do: - Write the tesh file, containing the command to run, the provided input (if any, but almost no SimGrid test provide such an input) and the expected output. Check the tesh man page for more - details.\n + details.@n Tesh is sometimes annoying as you have to ensure that the expected output will always be exactly the same. In particular, your should not output machine dependent informations such as absolute data @@ -198,7 +198,7 @@ To add a new integration test, you thus have 3 things to do: steps can be used here, such as the obfucation of the memory adresses unless the verbose logs are displayed (using the #XBT_LOG_ISENABLED() macro), or the modification of the log formats - to hide the timings when they depend on the host machine.\n + to hide the timings when they depend on the host machine.@n The script located in /tools/tesh/generate_tesh can help you a lot in particular if the output is large (though a smaller output is preferable). There are also example tesh files in the /tools/tesh/ directory, that can be useful to understand the tesh syntax. @@ -218,7 +218,7 @@ To add a new integration test, you thus have 3 things to do: Once the name is chosen, create a new test by adding a line similar to the following (assuming that you use tesh as expected). -\verbatim +@verbatim # Usage: ADD_TEST(test-name ${CMAKE_BINARY_DIR}/bin/tesh ) # option --setenv bindir set the directory containing the binary # --setenv srcdir set the directory containing the source file @@ -229,12 +229,12 @@ ADD_TEST(my-test-name ${CMAKE_BINARY_DIR}/bin/tesh --cd ${CMAKE_HOME_DIRECTORY}/examples/my-test/ ${CMAKE_HOME_DIRECTORY}/examples/msg/io/io.tesh ) -\endverbatim +@endverbatim As usual, you must run "make distcheck" after modifying the cmake files, to ensure that you did not forget any files in the distributed archive. -\section inside_tests_ci Continous Integration +@section inside_tests_ci Continous Integration We use several systems to automatically test SimGrid with a large set of parameters, across as many platforms as possible. @@ -247,7 +247,7 @@ quickly run some tests on Linux and Mac. It answers quickly but may miss issues. And we use AppVeyor to build and somehow test SimGrid on windows. -\subsection inside_tests_jenkins Jenkins on the Inria CI servers +@subsection inside_tests_jenkins Jenkins on the Inria CI servers You should not have to change the configuration of the Jenkins tool yourself, although you could have to change the slaves' configuration @@ -257,14 +257,14 @@ refer to the CI documentation. The result can be seen here: https://ci.inria.fr/simgrid/ We have 2 interesting projects on Jenkins: -\li SimGrid - is the main project, running the tests that we spoke about.\n It is +@li SimGrid + is the main project, running the tests that we spoke about.@n It is configured (on Jenkins) to run the script tools/jenkins/build.sh -\li SimGrid-DynamicAnalysis +@li SimGrid-DynamicAnalysis should be called "nightly" because it does not only run dynamic tests, but a whole bunch of long lasting tests: valgrind (memory errors), gcovr (coverage), Sanitizers (bad pointer usage, threading - errors, use of unspecified C constructs) and the clang static analyzer.\n It is configured + errors, use of unspecified C constructs) and the clang static analyzer.@n It is configured (on Jenkins) to run the script tools/jenkins/DynamicAnalysis.sh In each case, SimGrid gets built in @@ -280,13 +280,13 @@ groovy-expression to disable a specific configuration. For example, in order to disable the "ModelChecker" build on host "small-netbsd-64-clang", use: -\verbatim +@verbatim (label=="small-netbsd-64-clang").implies(build_mode!="ModelChecker") -\endverbatim +@endverbatim Just for the record, the slaves were created from the available template with the following commands: -\verbatim +@verbatim #debian/ubuntu apt-get install gcc g++ gfortran automake cmake libboost-dev openjdk-8-jdk openjdk-8-jre libxslt-dev libxml2-dev libevent-dev libunwind-dev libdw-dev htop git python3 xsltproc libboost-context-dev #for dynamicanalysis: @@ -307,9 +307,9 @@ pkg install boost-libs cmake openjdk8 automake libxslt libxml2 libunwind git hto #osx brew install cmake boost libunwind-headers libxslt git python3 -\endverbatim +@endverbatim -\subsection inside_tests_travis Travis +@subsection inside_tests_travis Travis Travis is a free (as in free beer) Continuous Integration system that open-sourced project can use freely. It is very well integrated in the @@ -318,24 +318,24 @@ configuration is in the file .travis.yml as it should be, and the result is here: https://travis-ci.org/simgrid/simgrid The .travis.yml configuration file can be useful if you fail to get -SimGrid to compile on modern mac systems. We use the \c brew package +SimGrid to compile on modern mac systems. We use the @c brew package manager there, and it works like a charm. -\subsection inside_tests_appveyor AppVeyor +@subsection inside_tests_appveyor AppVeyor AppVeyor aims at becoming the Travis of Windows. It is maybe less mature than Travis, or maybe it is just that I'm less trained in Windows. Our configuration is in the file appveyor.yml as it should be, and the result is here: https://ci.appveyor.com/project/mquinson/simgrid -We use \c Choco as a package manager on AppVeyor, and it is sufficient +We use @c Choco as a package manager on AppVeyor, and it is sufficient for us. In the future, we will probably move to the ubuntu subsystem of Windows 10: SimGrid performs very well under these settings, as tested on Inria's CI servers. For the time being having a native library is still useful for the Java users that don't want to install anything beyond Java on their windows. -\subsection inside_tests_debian Debian builders +@subsection inside_tests_debian Debian builders Since SimGrid is packaged in Debian, we benefit from their huge testing infrastructure. That's an interesting torture test for our @@ -347,7 +347,7 @@ only the most important breakages. The build results are here: https://buildd.debian.org/status/package.php?p=simgrid -\subsection inside_tests_sonarqube SonarQube +@subsection inside_tests_sonarqube SonarQube SonarQube is an open-source code quality analysis solution. Their nice code scanners are provided as plugin. The one for C++ is not free, but diff --git a/doc/doxygen/module-index.doc b/doc/doxygen/module-index.doc index 5c272c37bf..57c4fa2377 100644 --- a/doc/doxygen/module-index.doc +++ b/doc/doxygen/module-index.doc @@ -19,7 +19,7 @@ The API enables the declaration of categories and a function to associate them to the tasks (MSG and SD). The tasks that are not classified according to a category are not traced. If no categories are specified, simulations can still be traced using a special -parameter in the command line (see \ref outcomes_vizu for details). +parameter in the command line (see @ref outcomes_vizu for details). */ /** @defgroup ROUTING_API Routing: Determining the communication paths @@ -55,12 +55,12 @@ The price to pay is that this representation of networks is very specific to SimGrid, so you will have to read further to understand it, even if you already know how real networks work. -The central notion here are \b Networking \b Zones. NetZones represent +The central notion here are @b Networking @b Zones. NetZones represent network areas in which the routing is done in an homogeneous way. Conceptually, netzones generalize from the ideas of local networks (such as Ethernet switched networks) and Autonomous System. The network as a whole is represented as a single hierarchy of netzones, -meaning that every netzone is part of another netzone (but the \c +meaning that every netzone is part of another netzone (but the @c NetRoot, which is the top-level netzone). The main goal of the routing module is to provide a list of links @@ -96,12 +96,12 @@ given processes. For now, you can only declare a platform from an XML file, but we are working to make it possible from the C++ code (or even from bindings -in other languages). Until then, please head to \ref platform. +in other languages). Until then, please head to @ref platform. */ -/** \defgroup SIMIX_API SIMIX - \brief POSIX-like interface for building simulation +/** @defgroup SIMIX_API SIMIX + @brief POSIX-like interface for building simulation This is a developer-level interface that should be useful only if you plan to design a new interface for SimGrid. diff --git a/doc/doxygen/module-msg.doc b/doc/doxygen/module-msg.doc index ddb517c2fb..5f3c420730 100644 --- a/doc/doxygen/module-msg.doc +++ b/doc/doxygen/module-msg.doc @@ -10,7 +10,7 @@ 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 +@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 @@ -18,17 +18,17 @@ abstracted away rather easily. 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 +@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 + - @ref msg_task_usage + - @ref msg_VMs + - @ref msg_synchro + - @ref msg_examples */ @@ -37,7 +37,7 @@ abstracted away rather easily. @ingroup MSG_API @brief How to setup and control your simulation. -The basic workflow is the following (check the \ref msg_examples for +The basic workflow is the following (check the @ref msg_examples for details). -# Initialize the library with #MSG_init @@ -63,7 +63,7 @@ details). /** @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. + * @ref msg_task_usage to see how to put the tasks in action. */ /** @defgroup msg_mailbox_management Mailbox Management Functions diff --git a/doc/doxygen/module-s4u.doc b/doc/doxygen/module-s4u.doc index fe5d8bf9ef..8b70f039ff 100644 --- a/doc/doxygen/module-s4u.doc +++ b/doc/doxygen/module-s4u.doc @@ -15,7 +15,7 @@ bugs. Unsurprisingly, the S4U interface matches the concepts presented in @ref starting_components "the introduction". You should read this page first, to not get lost in the amount of classes provided here. Or you -could jump to the \ref s4u_examples directly if you prefer. +could jump to the @ref s4u_examples directly if you prefer. @section s4u_raii Memory Management of S4U objects diff --git a/doc/doxygen/module-simix.doc b/doc/doxygen/module-simix.doc index 45cff6b571..2191bec55d 100644 --- a/doc/doxygen/module-simix.doc +++ b/doc/doxygen/module-simix.doc @@ -1,6 +1,6 @@ /** @addtogroup SIMIX_API - \section smx_detail Coming soon + @section smx_detail Coming soon @{ */ /** @defgroup m_datatypes_management_details SIMIX datatypes management details */ /** @} */ diff --git a/doc/doxygen/module-surf.doc b/doc/doxygen/module-surf.doc index b85bd68a49..d041a49bf3 100644 --- a/doc/doxygen/module-surf.doc +++ b/doc/doxygen/module-surf.doc @@ -1,40 +1,40 @@ -/** \addtogroup SURF_API +/** @addtogroup SURF_API - \section SURF_doc Surf documentation + @section SURF_doc Surf documentation Surf is composed several components: - - \ref SURF_simulation - - \ref SURF_models - - \ref SURF_build_api - - \ref SURF_c_bindings - - \ref SURF_interface - - \ref SURF_cpu_interface - - \ref SURF_network_interface - - \ref SURF_storage_interface - - \ref SURF_host_interface - - \ref SURF_vm_interface - - \ref SURF_lmm - - \ref SURF_callbacks - - \ref plugin_energy + - @ref SURF_simulation + - @ref SURF_models + - @ref SURF_build_api + - @ref SURF_c_bindings + - @ref SURF_interface + - @ref SURF_cpu_interface + - @ref SURF_network_interface + - @ref SURF_storage_interface + - @ref SURF_host_interface + - @ref SURF_vm_interface + - @ref SURF_lmm + - @ref SURF_callbacks + - @ref plugin_energy */ -/** \defgroup SURF_models Simulation Models - \ingroup SURF_API - \brief Functions to declare the kind of models that you want to use +/** @defgroup SURF_models Simulation Models + @ingroup SURF_API + @brief Functions to declare the kind of models that you want to use */ -/** \defgroup SURF_simulation Simulation - \ingroup SURF_API - \brief Functions for creating the environment and launching the simulation +/** @defgroup SURF_simulation Simulation + @ingroup SURF_API + @brief Functions for creating the environment and launching the simulation This section describes the functions for initializing SURF, performing the simulation and exiting SURF. */ -/** \defgroup SURF_build_api Create a new API - \ingroup SURF_API - \brief How to build a new API on top of SURF +/** @defgroup SURF_build_api Create a new API + @ingroup SURF_API + @brief How to build a new API on top of SURF SURF provides the functionalities to simulate the platform. There are two main data types in SURF: the actions and the resources. Several types of resources exist: @@ -46,35 +46,35 @@ The implementation of these resources depends on the platform models you choose. You can select your model by calling #surf_host_model_init_current_default() (which will give you a - CLM03 model), or similar (see \ref SURF_models). + CLM03 model), or similar (see @ref SURF_models). To initialize SURF, call #surf_init(). Then #surf_host_model_init_current_default() or #surf_host_model_init_ptask_L07() to create the platform. - Then you can access the hosts with the \ref simgrid::s4u::Engine::get_all_hosts. - Some functions of the \ref SURF_host_interface and similar can give + Then you can access the hosts with the @ref simgrid::s4u::Engine::get_all_hosts. + Some functions of the @ref SURF_host_interface and similar can give you some information about: - a host: get_speed(), get_available_speed(); - a network link: get_link_name(), get_link_latency(), get_link_bandwith(); - a route: get_route(), get_route_size(). - During the simulation, call \a surf_host_model->execute() to schedule a - computation task on a host, or \a surf_host_model->communicate() + During the simulation, call @a surf_host_model->execute() to schedule a + computation task on a host, or @a surf_host_model->communicate() to schedule a communication task between two hosts. You can also create parallel task - with \a surf_host_model->extension_public->execute_parallel_task(). These functions return + with @a surf_host_model->extension_public->execute_parallel_task(). These functions return a new action that represents the task you have just created. - To execute the actions created with \a execute(), \a communicate() or \a execute_parallel_task(), call + To execute the actions created with @a execute(), @a communicate() or @a execute_parallel_task(), call surf_solve(). The function surf_solve() is where the simulation takes place. It returns the time elapsed to execute the actions. You can know what actions have changed their state thanks to the states sets. For example, if your want to know what actions are finished, - extract them from \a surf_host_model->common_public->states.done_action_set. + extract them from @a surf_host_model->common_public->states.done_action_set. Depending on these results, you can schedule other tasks and call surf_solve() again. When the simulation is over, just call surf_exit() to clean the memory. - Have a look at the implementation of \ref MSG_API "MSG" and \ref SD_API "Simdag" to see how these module + Have a look at the implementation of @ref MSG_API "MSG" and @ref SD_API "Simdag" to see how these module interact with SURF. But if you want to create a new API on top of SURF, we strongly recommend you to contact us before anyway. diff --git a/doc/doxygen/module-trace.doc b/doc/doxygen/module-trace.doc index 6b98031eb9..ac1e004544 100644 --- a/doc/doxygen/module-trace.doc +++ b/doc/doxygen/module-trace.doc @@ -1,10 +1,10 @@ /** -\addtogroup TRACE_API +@addtogroup TRACE_API -\section TRACE_doc TRACE documentation -- \ref TRACE_category -- \ref TRACE_mark -- \ref TRACE_user_variables +@section TRACE_doc TRACE documentation +- @ref TRACE_category +- @ref TRACE_mark +- @ref TRACE_user_variables @{ diff --git a/doc/doxygen/module-xbt.doc b/doc/doxygen/module-xbt.doc index d8cc3d41b8..6a0c84635b 100644 --- a/doc/doxygen/module-xbt.doc +++ b/doc/doxygen/module-xbt.doc @@ -2,21 +2,21 @@ The XBT functionalities fall into several categories: - Portability support - - \ref XBT_syscall - - \ref XBT_str + - @ref XBT_syscall + - @ref XBT_str - Grounding features - - \ref XBT_ex - - \ref XBT_ex_c - - \ref XBT_log - - \ref XBT_error - - \ref XBT_config - - \ref XBT_mallocator - - \ref XBT_cunit + - @ref XBT_ex + - @ref XBT_ex_c + - @ref XBT_log + - @ref XBT_error + - @ref XBT_config + - @ref XBT_mallocator + - @ref XBT_cunit - Data structures - - \ref XBT_dynar - - \ref XBT_dict - - \ref XBT_misc - - \ref XBT_graph + - @ref XBT_dynar + - @ref XBT_dict + - @ref XBT_misc + - @ref XBT_graph @{ */ /** @defgroup XBT_grounding Grounding features */ @@ -86,13 +86,13 @@ * * PORTABILITY-INTERNALS * * (not included in documentation) * ************************* */ - /** \addtogroup XBT_context Portable context implementation - * \brief Contexts are a higher level system than setjump/longjmp + /** @addtogroup XBT_context Portable context implementation + * @brief Contexts are a higher level system than setjump/longjmp * for non-preemptible threads. * * You shouldn't use it directly since it is merely intended to ease the * implementation of the several programmation environment of the - * SimGrid toolkit (namely, \ref MSG_API and \ref SMPI_API). + * SimGrid toolkit (namely, @ref MSG_API and @ref SMPI_API). * * You should use those environments instead. */ diff --git a/doc/doxygen/ns3.doc b/doc/doxygen/ns3.doc index 91950b9201..5851f536ce 100644 --- a/doc/doxygen/ns3.doc +++ b/doc/doxygen/ns3.doc @@ -1,23 +1,23 @@ -/*! \page pls_ns3 ns-3 as a SimGrid model +/*! @page pls_ns3 ns-3 as a SimGrid model -\tableofcontents +@tableofcontents You can use the well-known ns-3 packet-level network simulator as a SimGrid model, for example to investigate the validity of your simulation. Just install ns-3 and recompile SimGrid accordingly. -\section pls_ns3_install Installing ns-3 +@section pls_ns3_install Installing ns-3 The easiest is to install it with the package manager. Under Debian/Ubuntu, simply type as root: -\verbatim +@verbatim apt-get install libns3-dev ns3 -\endverbatim +@endverbatim You can also install it from scratch with the following commands: -\verbatim +@verbatim # Download the source wget http://www.nsnam.org/release/ns-allinone-3.26.tar.bz2 tar -xf ns-allinone-3.26.tar.bz2 @@ -26,35 +26,35 @@ cd ns-allinone-3.26/ns-3.26/ ./waf configure --prefix="/opt/ns3" # or give another path if you prefer ./waf ./waf install -\endverbatim +@endverbatim For more information, please refer to the ns-3 documentation (official website). -\section pls_ns3_config Enabling SimGrid's support for ns-3 +@section pls_ns3_config Enabling SimGrid's support for ns-3 Normally, you just have to enable ns-3 in ccmake or cmake as follows. If you installed ns-3 in a regular path, just drop the NS3_HINT configuration item. -\verbatim +@verbatim cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed -\endverbatim +@endverbatim By the end of the configuration, cmake reports whether ns-3 was found, and this information is also available in include/simgrid/config.h -If your local copy defines the variable \c SIMGRID_HAVE_NS3 to 1, then ns-3 +If your local copy defines the variable @c SIMGRID_HAVE_NS3 to 1, then ns-3 was correctly detected. If it's defined to 0, then something went wrong. Explore CMakeFiles/CMakeOutput.log and CMakeFiles/CMakeError.log to diagnose the problem. Afterward, you can test your installation as follows: -\verbatim +@verbatim $ ctest -R ns3 -\endverbatim +@endverbatim -\section pls_ns3_use Using ns-3 from SimGrid +@section pls_ns3_use Using ns-3 from SimGrid The SimGrid-ns3 binding only contains features that are common to both systems: ns-3 wireless models are not available, while SimGrid routes @@ -109,9 +109,9 @@ ns-3 will find the path from point to point. Once your platform is OK, just change the "network/model" configuration option to "NS3" as follows. The rest remains unchanged. -\verbatim +@verbatim ./network-ns3 ../../platforms/small_platform_one_link_routes.xml 3hosts_2links_d.xml --cfg=network/model:NS3 -\endverbatim +@endverbatim Many other files from the examples/platform directory are usable with the ns-3 model, such as @ref examples/platforms/dogbone.xml. Check the file @@ -148,7 +148,7 @@ existing one. @subsection pls_ns3_config_trouble I fail to compile ns-3 within SimGrid -If you have a ns-3 version that is not known to SimGrid yet, edit \c +If you have a ns-3 version that is not known to SimGrid yet, edit @c tools/cmake/Modules/FindNS3.cmake in your SimGrid tree, according to the comments on top of this file. diff --git a/doc/doxygen/options.doc b/doc/doxygen/options.doc index 9d08d718d9..ec9f5202c7 100644 --- a/doc/doxygen/options.doc +++ b/doc/doxygen/options.doc @@ -1,15 +1,15 @@ -/*! \page options Configure SimGrid +/*! @page options Configure SimGrid -\htmlonly +@htmlonly
-\endhtmlonly -\htmlinclude graphical-toc.svg -\htmlonly +@endhtmlonly +@htmlinclude graphical-toc.svg +@htmlonly
-\endhtmlonly +@endhtmlonly A number of options can be given at runtime to change the default SimGrid behavior. For a complete list of all configuration options @@ -20,43 +20,43 @@ report so that we can fix it. Note that some of the options presented here may not be available in your simulators, depending on the @ref install_src_config "compile-time options" that you used. -\tableofcontents +@tableofcontents -\section options_using Passing configuration options to the simulators +@section options_using Passing configuration options to the simulators There is several way to pass configuration options to the simulators. -The most common way is to use the \c --cfg command line argument. For -example, to set the item \c Item to the value \c Value, simply -type the following: \verbatim +The most common way is to use the @c --cfg command line argument. For +example, to set the item @c Item to the value @c Value, simply +type the following: @verbatim my_simulator --cfg=Item:Value (other arguments) -\endverbatim +@endverbatim -Several \c `--cfg` command line arguments can naturally be used. If you +Several @c `--cfg` command line arguments can naturally be used. If you need to include spaces in the argument, don't forget to quote the -argument. You can even escape the included quotes (write \' for ' if +argument. You can even escape the included quotes (write @' for ' if you have your argument between '). -Another solution is to use the \c \ tag in the platform file. The +Another solution is to use the @c @ tag in the platform file. The only restriction is that this tag must occure before the first -platform element (be it \c \, \c \, \c \ or whatever). -The \c \ tag takes an \c id attribute, but it is currently +platform element (be it @c @, @c @, @c @ or whatever). +The @c @ tag takes an @c id attribute, but it is currently ignored so you don't really need to pass it. The important par is that -within that tag, you can pass one or several \c \ tags to specify -the configuration to use. For example, setting \c Item to \c Value +within that tag, you can pass one or several @c @ tags to specify +the configuration to use. For example, setting @c Item to @c Value can be done by adding the following to the beginning of your platform file: -\verbatim +@verbatim -\endverbatim +@endverbatim A last solution is to pass your configuration directly using the C interface. If you happen to use the MSG interface, this is very easy with the simgrid::s4u::Engine::setConfig() or MSG_config() functions. If you do not use MSG, that's a bit more complex, as you have to mess with the internal configuration set -directly as follows. Check the \ref XBT_config "relevant page" for -details on all the functions you can use in this context, \c +directly as follows. Check the @ref XBT_config "relevant page" for +details on all the functions you can use in this context, @c _sg_cfg_set being the only configuration set currently used in SimGrid. @@ -73,125 +73,125 @@ int main(int argc, char *argv[]) { } @endcode -\section options_index Index of all existing configuration options +@section options_index Index of all existing configuration options -\note +@note The full list can be retrieved by passing "--help" and "--help-cfg" to an executable that uses SimGrid. -- \c clean-atexit: \ref options_generic_clean_atexit - -- \c contexts/factory: \ref options_virt_factory -- \c contexts/guard-size: \ref options_virt_guard_size -- \c contexts/nthreads: \ref options_virt_parallel -- \c contexts/parallel-threshold: \ref options_virt_parallel -- \c contexts/stack-size: \ref options_virt_stacksize -- \c contexts/synchro: \ref options_virt_parallel - -- \c cpu/maxmin-selective-update: \ref options_model_optim -- \c cpu/model: \ref options_model_select -- \c cpu/optim: \ref options_model_optim - -- \c exception/cutpath: \ref options_exception_cutpath - -- \c host/model: \ref options_model_select - -- \c maxmin/precision: \ref options_model_precision -- \c maxmin/concurrency-limit: \ref options_concurrency_limit - -- \c msg/debug-multiple-use: \ref options_msg_debug_multiple_use - -- \c model-check: \ref options_modelchecking -- \c model-check/checkpoint: \ref options_modelchecking_steps -- \c model-check/communications-determinism: \ref options_modelchecking_comm_determinism -- \c model-check/dot-output: \ref options_modelchecking_dot_output -- \c model-check/hash: \ref options_modelchecking_hash -- \c model-check/property: \ref options_modelchecking_liveness -- \c model-check/max-depth: \ref options_modelchecking_max_depth -- \c model-check/record: \ref options_modelchecking_recordreplay -- \c model-check/reduction: \ref options_modelchecking_reduction -- \c model-check/replay: \ref options_modelchecking_recordreplay -- \c model-check/send-determinism: \ref options_modelchecking_comm_determinism -- \c model-check/sparse-checkpoint: \ref options_modelchecking_sparse_checkpoint -- \c model-check/termination: \ref options_modelchecking_termination -- \c model-check/timeout: \ref options_modelchecking_timeout -- \c model-check/visited: \ref options_modelchecking_visited - -- \c network/bandwidth-factor: \ref options_model_network_coefs -- \c network/crosstraffic: \ref options_model_network_crosstraffic -- \c network/latency-factor: \ref options_model_network_coefs -- \c network/maxmin-selective-update: \ref options_model_optim -- \c network/model: \ref options_model_select -- \c network/optim: \ref options_model_optim -- \c network/TCP-gamma: \ref options_model_network_gamma -- \c network/weight-S: \ref options_model_network_coefs - -- \c ns3/TcpModel: \ref options_pls -- \c path: \ref options_generic_path -- \c plugin: \ref options_generic_plugin - -- \c simix/breakpoint: \ref options_generic_breakpoint - -- \c storage/max_file_descriptors: \ref option_model_storage_maxfd - -- \c surf/precision: \ref options_model_precision - -- \c For collective operations of SMPI, please refer to Section \ref options_index_smpi_coll -- \c smpi/async-small-thresh: \ref options_model_network_asyncsend -- \c smpi/bw-factor: \ref options_model_smpi_bw_factor -- \c smpi/coll-selector: \ref options_model_smpi_collectives -- \c smpi/comp-adjustment-file: \ref options_model_smpi_adj_file -- \c smpi/cpu-threshold: \ref options_smpi_bench -- \c smpi/display-timing: \ref options_smpi_timing -- \c smpi/grow-injected-times: \ref options_model_smpi_test -- \c smpi/host-speed: \ref options_smpi_bench -- \c smpi/IB-penalty-factors: \ref options_model_network_coefs -- \c smpi/iprobe: \ref options_model_smpi_iprobe -- \c smpi/iprobe-cpu-usage: \ref options_model_smpi_iprobe_cpu_usage -- \c smpi/init: \ref options_model_smpi_init -- \c smpi/keep-temps: \ref options_smpi_temps -- \c smpi/lat-factor: \ref options_model_smpi_lat_factor -- \c smpi/ois: \ref options_model_smpi_ois -- \c smpi/or: \ref options_model_smpi_or -- \c smpi/os: \ref options_model_smpi_os -- \c smpi/papi-events: \ref options_smpi_papi_events -- \c smpi/privatization: \ref options_smpi_privatization -- \c smpi/privatize-libs: \ref options_smpi_privatize_libs -- \c smpi/send-is-detached-thresh: \ref options_model_smpi_detached -- \c smpi/shared-malloc: \ref options_model_smpi_shared_malloc -- \c smpi/shared-malloc-hugepage: \ref options_model_smpi_shared_malloc -- \c smpi/simulate-computation: \ref options_smpi_bench -- \c smpi/test: \ref options_model_smpi_test -- \c smpi/wtime: \ref options_model_smpi_wtime - -- \c Tracing configuration options can be found in Section \ref tracing_tracing_options. - -- \c storage/model: \ref options_storage_model -- \c verbose-exit: \ref options_generic_exit - -- \c vm/model: \ref options_vm_model - -\subsection options_index_smpi_coll Index of SMPI collective algorithms options +- @c clean-atexit: @ref options_generic_clean_atexit + +- @c contexts/factory: @ref options_virt_factory +- @c contexts/guard-size: @ref options_virt_guard_size +- @c contexts/nthreads: @ref options_virt_parallel +- @c contexts/parallel-threshold: @ref options_virt_parallel +- @c contexts/stack-size: @ref options_virt_stacksize +- @c contexts/synchro: @ref options_virt_parallel + +- @c cpu/maxmin-selective-update: @ref options_model_optim +- @c cpu/model: @ref options_model_select +- @c cpu/optim: @ref options_model_optim + +- @c exception/cutpath: @ref options_exception_cutpath + +- @c host/model: @ref options_model_select + +- @c maxmin/precision: @ref options_model_precision +- @c maxmin/concurrency-limit: @ref options_concurrency_limit + +- @c msg/debug-multiple-use: @ref options_msg_debug_multiple_use + +- @c model-check: @ref options_modelchecking +- @c model-check/checkpoint: @ref options_modelchecking_steps +- @c model-check/communications-determinism: @ref options_modelchecking_comm_determinism +- @c model-check/dot-output: @ref options_modelchecking_dot_output +- @c model-check/hash: @ref options_modelchecking_hash +- @c model-check/property: @ref options_modelchecking_liveness +- @c model-check/max-depth: @ref options_modelchecking_max_depth +- @c model-check/record: @ref options_modelchecking_recordreplay +- @c model-check/reduction: @ref options_modelchecking_reduction +- @c model-check/replay: @ref options_modelchecking_recordreplay +- @c model-check/send-determinism: @ref options_modelchecking_comm_determinism +- @c model-check/sparse-checkpoint: @ref options_modelchecking_sparse_checkpoint +- @c model-check/termination: @ref options_modelchecking_termination +- @c model-check/timeout: @ref options_modelchecking_timeout +- @c model-check/visited: @ref options_modelchecking_visited + +- @c network/bandwidth-factor: @ref options_model_network_coefs +- @c network/crosstraffic: @ref options_model_network_crosstraffic +- @c network/latency-factor: @ref options_model_network_coefs +- @c network/maxmin-selective-update: @ref options_model_optim +- @c network/model: @ref options_model_select +- @c network/optim: @ref options_model_optim +- @c network/TCP-gamma: @ref options_model_network_gamma +- @c network/weight-S: @ref options_model_network_coefs + +- @c ns3/TcpModel: @ref options_pls +- @c path: @ref options_generic_path +- @c plugin: @ref options_generic_plugin + +- @c simix/breakpoint: @ref options_generic_breakpoint + +- @c storage/max_file_descriptors: @ref option_model_storage_maxfd + +- @c surf/precision: @ref options_model_precision + +- @c For collective operations of SMPI, please refer to Section @ref options_index_smpi_coll +- @c smpi/async-small-thresh: @ref options_model_network_asyncsend +- @c smpi/bw-factor: @ref options_model_smpi_bw_factor +- @c smpi/coll-selector: @ref options_model_smpi_collectives +- @c smpi/comp-adjustment-file: @ref options_model_smpi_adj_file +- @c smpi/cpu-threshold: @ref options_smpi_bench +- @c smpi/display-timing: @ref options_smpi_timing +- @c smpi/grow-injected-times: @ref options_model_smpi_test +- @c smpi/host-speed: @ref options_smpi_bench +- @c smpi/IB-penalty-factors: @ref options_model_network_coefs +- @c smpi/iprobe: @ref options_model_smpi_iprobe +- @c smpi/iprobe-cpu-usage: @ref options_model_smpi_iprobe_cpu_usage +- @c smpi/init: @ref options_model_smpi_init +- @c smpi/keep-temps: @ref options_smpi_temps +- @c smpi/lat-factor: @ref options_model_smpi_lat_factor +- @c smpi/ois: @ref options_model_smpi_ois +- @c smpi/or: @ref options_model_smpi_or +- @c smpi/os: @ref options_model_smpi_os +- @c smpi/papi-events: @ref options_smpi_papi_events +- @c smpi/privatization: @ref options_smpi_privatization +- @c smpi/privatize-libs: @ref options_smpi_privatize_libs +- @c smpi/send-is-detached-thresh: @ref options_model_smpi_detached +- @c smpi/shared-malloc: @ref options_model_smpi_shared_malloc +- @c smpi/shared-malloc-hugepage: @ref options_model_smpi_shared_malloc +- @c smpi/simulate-computation: @ref options_smpi_bench +- @c smpi/test: @ref options_model_smpi_test +- @c smpi/wtime: @ref options_model_smpi_wtime + +- @c Tracing configuration options can be found in Section @ref tracing_tracing_options. + +- @c storage/model: @ref options_storage_model +- @c verbose-exit: @ref options_generic_exit + +- @c vm/model: @ref options_vm_model + +@subsection 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. -\section options_model Configuring the platform models +@section options_model Configuring the platform models -\anchor options_storage_model -\anchor options_vm_model -\subsection options_model_select Selecting the platform models +@anchor options_storage_model +@anchor options_vm_model +@subsection options_model_select Selecting the platform models SimGrid comes with several network, CPU and storage models built in, and you can change the used model at runtime by changing the passed configuration. The three main configuration items are given below. -For each of these items, passing the special \c help value gives -you a short description of all possible values. Also, \c --help-models +For each of these items, passing the special @c help value gives +you a short description of all possible values. Also, @c --help-models should provide information about all models for all existing resources. - - \b network/model: specify the used network model - - \b cpu/model: specify the used CPU model - - \b host/model: specify the used host model - - \b storage/model: specify the used storage model (there is currently only one such model - this option is hence only useful for future releases) - - \b vm/model: specify the model for virtual machines (there is currently only one such model - this option is hence only useful for future releases) + - @b network/model: specify the used network model + - @b cpu/model: specify the used CPU model + - @b host/model: specify the used host model + - @b storage/model: specify the used storage model (there is currently only one such model - this option is hence only useful for future releases) + - @b vm/model: specify the model for virtual machines (there is currently only one such model - this option is hence only useful for future releases) As of writing, the following network models are accepted. Over the time new models can be added, and some experimental models can be @@ -202,39 +202,39 @@ Network Model for Simulation of Grid Application while LV08 is described in Accuracy Study and Improvement of Network Simulation in the SimGrid Framework. - - \b LV08 (default one): Realistic network analytic model + - @b LV08 (default one): Realistic network analytic model (slow-start modeled by multiplying latency by 13.01, bandwidth by .97; bottleneck sharing uses a payload of S=20537 for evaluating RTT) - - \anchor options_model_select_network_constant \b Constant: Simplistic network model where all communication + - @anchor options_model_select_network_constant @b Constant: Simplistic network model where all communication take a constant time (one second). This model provides the lowest realism, but is (marginally) faster. - - \b SMPI: Realistic network model specifically tailored for HPC + - @b SMPI: Realistic network model specifically tailored for HPC settings (accurate modeling of slow start with correction factors on - three intervals: < 1KiB, < 64 KiB, >= 64 KiB). See also \ref + three intervals: < 1KiB, < 64 KiB, >= 64 KiB). See also @ref options_model_network_coefs "this section" for more info. - - \b IB: Realistic network model specifically tailored for HPC + - @b IB: Realistic network model specifically tailored for HPC settings with InfiniBand networks (accurate modeling contention behavior, based on the model explained in http://mescal.imag.fr/membres/jean-marc.vincent/index.html/PhD/Vienne.pdf). - See also \ref options_model_network_coefs "this section" for more info. - - \b CM02: Legacy network analytic model (Very similar to LV08, but + See also @ref options_model_network_coefs "this section" for more info. + - @b CM02: Legacy network analytic model (Very similar to LV08, but without corrective factors. The timings of small messages are thus poorly modeled) - - \b Reno: Model from Steven H. Low using lagrange_solve instead of + - @b Reno: Model from Steven H. Low using lagrange_solve instead of lmm_solve (experts only; check the code for more info). - - \b Reno2: Model from Steven H. Low using lagrange_solve instead of + - @b Reno2: Model from Steven H. Low using lagrange_solve instead of lmm_solve (experts only; check the code for more info). - - \b Vegas: Model from Steven H. Low using lagrange_solve instead of + - @b Vegas: Model from Steven H. Low using lagrange_solve instead of lmm_solve (experts only; check the code for more info). If you compiled SimGrid accordingly, you can use packet-level network -simulators as network models (see \ref pls_ns3). In that case, you have +simulators as network models (see @ref pls_ns3). In that case, you have two extra models, described below, and some -\ref options_pls "specific additional configuration flags". - - \b NS3: Network pseudo-model using the NS3 tcp model +@ref options_pls "specific additional configuration flags". + - @b NS3: Network pseudo-model using the NS3 tcp model Concerning the CPU, we have only one model for now: - - \b Cas01: Simplistic CPU model (time=size/power) + - @b Cas01: Simplistic CPU model (time=size/power) The host concept is the aggregation of a CPU with a network card. Three models exists, but actually, only 2 of them are @@ -245,15 +245,15 @@ existing CPU model with an existing network model, but does not allow parallel tasks because these beasts need some collaboration between the network and CPU model. That is why, ptask_07 is used by default when using SimDag. - - \b default: Default host model. Currently, CPU:Cas01 and + - @b default: Default host model. Currently, CPU:Cas01 and network:LV08 (with cross traffic enabled) - - \b compound: Host model that is automatically chosen if + - @b compound: Host model that is automatically chosen if you change the network and CPU models - - \b ptask_L07: Host model somehow similar to Cas01+CM02 but + - @b ptask_L07: Host model somehow similar to Cas01+CM02 but allowing "parallel tasks", that are intended to model the moldable tasks of the grid scheduling literature. -\subsection options_generic_plugin Plugins +@subsection options_generic_plugin Plugins SimGrid plugins allow to extend the framework without changing its source code directly. Read the source code of the existing plugins to @@ -268,59 +268,59 @@ meaning that you can activate them from the command line without any modification to your simulation code. For example, you can activate the host energy plugin by adding the following to your command line: -\verbatim +@verbatim --cfg=plugin:host_energy -\endverbatim +@endverbatim Here is the full list of plugins that can be activated this way: - - \b host_energy: keeps track of the energy dissipated by + - @b host_energy: keeps track of the energy dissipated by computations. More details in @ref plugin_energy. - - \b link_energy: keeps track of the energy dissipated by + - @b link_energy: keeps track of the energy dissipated by communications. More details in @ref SURF_plugin_energy. - - \b host_load: keeps track of the computational load. + - @b host_load: keeps track of the computational load. More details in @ref plugin_load. -\subsection options_model_optim Optimization level of the platform models +@subsection options_model_optim Optimization level of the platform models The network and CPU models that are based on lmm_solve (that is, all our analytical models) accept specific optimization configurations. - - items \b network/optim and \b cpu/optim (both default to 'Lazy'): - - \b Lazy: Lazy action management (partial invalidation in lmm + + - items @b network/optim and @b cpu/optim (both default to 'Lazy'): + - @b Lazy: Lazy action management (partial invalidation in lmm + heap in action remaining). - - \b TI: Trace integration. Highly optimized mode when using + - @b TI: Trace integration. Highly optimized mode when using availability traces (only available for the Cas01 CPU model for now). - - \b Full: Full update of remaining and variables. Slow but may be + - @b Full: Full update of remaining and variables. Slow but may be useful when debugging. - - items \b network/maxmin-selective-update and - \b cpu/maxmin-selective-update: configure whether the underlying + - items @b network/maxmin-selective-update and + @b cpu/maxmin-selective-update: configure whether the underlying should be lazily updated or not. It should have no impact on the computed timings, but should speed up the computation. -It is still possible to disable the \c maxmin-selective-update feature +It is still possible to disable the @c maxmin-selective-update feature because it can reveal counter-productive in very specific scenarios where the interaction level is high. In particular, if all your communication share a given backbone link, you should disable it: -without \c maxmin-selective-update, every communications are updated +without @c maxmin-selective-update, every communications are updated at each step through a simple loop over them. With that feature enabled, every communications will still get updated in this case (because of the dependency induced by the backbone), but through a complicated pattern aiming at following the actual dependencies. -\subsection options_model_precision Numerical precision of the platform models +@subsection options_model_precision Numerical precision of the platform models The analytical models handle a lot of floating point values. It is possible to change the epsilon used to update and compare them through -the \b maxmin/precision item (default value: 0.00001). Changing it +the @b maxmin/precision item (default value: 0.00001). Changing it may speedup the simulation by discarding very small actions, at the price of a reduced numerical precision. -\subsection options_concurrency_limit Concurrency limit +@subsection options_concurrency_limit Concurrency limit The maximum number of variables per resource can be tuned through -the \b maxmin/concurrency-limit item. The default value is -1, meaning that +the @b maxmin/concurrency-limit item. The default value is -1, meaning that there is no such limitation. You can have as many simultaneous actions per resources as you want. If your simulation presents a very high level of concurrency, it may help to use e.g. 100 as a value here. It means that at @@ -332,22 +332,22 @@ Such limitations help both to the simulation speed and simulation accuracy on highly constrained scenarios, but the simulation speed suffers of this setting on regular (less constrained) scenarios so it is off by default. -\subsection options_model_network Configuring the Network model +@subsection options_model_network Configuring the Network model -\subsubsection options_model_network_gamma Maximal TCP window size +@subsubsection options_model_network_gamma Maximal TCP window size The analytical models need to know the maximal TCP window size to take the TCP congestion mechanism into account. This is set to 4194304 by -default, but can be changed using the \b network/TCP-gamma item. +default, but can be changed using the @b network/TCP-gamma item. On linux, this value can be retrieved using the following commands. Both give a set of values, and you should use the last one, -which is the maximal size.\verbatim +which is the maximal size.@verbatim cat /proc/sys/net/ipv4/tcp_rmem # gives the sender window cat /proc/sys/net/ipv4/tcp_wmem # gives the receiver window -\endverbatim +@endverbatim -\subsubsection options_model_network_coefs Correcting important network parameters +@subsubsection options_model_network_coefs Correcting important network parameters SimGrid can take network irregularities such as a slow startup or changing behavior depending on the message size into account. @@ -368,14 +368,14 @@ InfiniBand network behavior can be modeled through 3 parameters, as explained in this PhD thesis. These factors can be changed through the following option: -\verbatim +@verbatim smpi/IB-penalty-factors:"βe;βs;γs" -\endverbatim +@endverbatim By default SMPI uses factors computed on the Stampede Supercomputer at TACC, with optimal deployment of processes on nodes. -\subsubsection options_model_network_crosstraffic Simulating cross-traffic +@subsubsection options_model_network_crosstraffic Simulating cross-traffic As of SimGrid v3.7, cross-traffic effects can be taken into account in analytical simulations. It means that ongoing and incoming @@ -388,28 +388,28 @@ For that to work, your platform must have two links for each pair of interconnected hosts. An example of usable platform is available in examples/platforms/crosstraffic.xml. -This is activated through the \b network/crosstraffic item, that +This is activated through the @b network/crosstraffic item, that can be set to 0 (disable this feature) or 1 (enable it). Note that with the default host model this option is activated by default. -\subsubsection options_model_network_asyncsend Simulating asyncronous send +@subsubsection options_model_network_asyncsend Simulating asyncronous send (this configuration item is experimental and may change or disapear) It is possible to specify that messages below a certain size will be sent as soon as the call to MPI_Send is issued, without waiting for the correspondant receive. This threshold can be configured through the -\b smpi/async-small-thresh item. The default value is 0. This behavior can also be +@b smpi/async-small-thresh item. The default value is 0. This behavior can also be manually set for MSG mailboxes, by setting the receiving mode of the mailbox -with a call to \ref MSG_mailbox_set_async . For MSG, all messages sent to this +with a call to @ref MSG_mailbox_set_async . For MSG, all messages sent to this mailbox will have this behavior, so consider using two mailboxes if needed. This value needs to be smaller than or equals to the threshold set at -\ref options_model_smpi_detached , because asynchronous messages are +@ref options_model_smpi_detached , because asynchronous messages are meant to be detached as well. -\subsubsection options_pls Configuring packet-level pseudo-models +@subsubsection options_pls Configuring packet-level pseudo-models When using the packet-level pseudo-models, several specific configuration flags are provided to configure the associated tools. @@ -418,45 +418,45 @@ of the associated tools, since we only added the items that we needed ourselves. Feel free to request more items (or even better: provide patches adding more items). -When using NS3, the only existing item is \b ns3/TcpModel, +When using NS3, the only existing item is @b ns3/TcpModel, corresponding to the ns3::TcpL4Protocol::SocketType configuration item in NS3. The only valid values (enforced on the SimGrid side) are 'NewReno' or 'Reno' or 'Tahoe'. -\subsection options_model_storage Configuring the Storage model +@subsection options_model_storage Configuring the Storage model -\subsubsection option_model_storage_maxfd Maximum amount of file descriptors per host +@subsubsection option_model_storage_maxfd Maximum amount of file descriptors per host Each host maintains a fixed-size array of its file descriptors. You -can change its size (1024 by default) through the \b +can change its size (1024 by default) through the @b storage/max_file_descriptors item to either enlarge it if your application requires it or to reduce it to save memory space. -\section options_modelchecking Configuring the Model-Checking +@section options_modelchecking Configuring the Model-Checking To enable the SimGrid model-checking support the program should be executed using the simgrid-mc wrapper: -\verbatim +@verbatim simgrid-mc ./my_program -\endverbatim +@endverbatim Safety properties are expressed as assertions using the function -\verbatim +@verbatim void MC_assert(int prop); -\endverbatim +@endverbatim -\subsection options_modelchecking_liveness Specifying a liveness property +@subsection options_modelchecking_liveness Specifying a liveness property If you want to specify liveness properties (beware, that's experimental), you have to pass them on the command line, specifying the name of the file containing the property, as formatted by the ltl2ba program. -\verbatim +@verbatim --cfg=model-check/property: -\endverbatim +@endverbatim -\subsection options_modelchecking_steps Going for stateful verification +@subsection options_modelchecking_steps Going for stateful verification By default, the system is backtracked to its initial state to explore another path instead of backtracking to the exact step before the fork @@ -469,11 +469,11 @@ Beware, this will certainly explode your memory. Larger values are probably better, make sure to experiment a bit to find the right setting for your specific system. -\verbatim +@verbatim --cfg=model-check/checkpoint:1 -\endverbatim +@endverbatim -\subsection options_modelchecking_reduction Specifying the kind of reduction +@subsection options_modelchecking_reduction Specifying the kind of reduction The main issue when using the model-checking is the state space explosion. To counter that problem, several exploration reduction @@ -483,9 +483,9 @@ properties. In particular, the DPOR method cannot be applied on liveness properties since it may break some cycles in the exploration that are important to the property validity. -\verbatim +@verbatim --cfg=model-check/reduction: -\endverbatim +@endverbatim For now, this configuration variable can take 2 values: * none: Do not apply any kind of reduction (mandatory for now for @@ -493,14 +493,14 @@ For now, this configuration variable can take 2 values: * dpor: Apply Dynamic Partial Ordering Reduction. Only valid if you verify local safety properties (default value for safety checks). -\subsection options_modelchecking_visited model-check/visited, Cycle detection +@subsection options_modelchecking_visited model-check/visited, Cycle detection In order to detect cycles, the model-checker needs to check if a new explored state is in fact the same state than a previous one. For that, the model-checker can take a snapshot of each visited state: this snapshot is then used to compare it with subsequent states in the exploration graph. -The \b model-check/visited option is the maximum number of states which are stored in +The @b model-check/visited option is the maximum number of states which are stored in memory. If the maximum number of snapshotted state is reached, some states will be removed from the memory and some cycles might be missed. Small values can lead to incorrect verifications, but large value can @@ -508,9 +508,9 @@ exhaust your memory, so choose carefully. By default, no state is snapshotted and cycles cannot be detected. -\subsection options_modelchecking_termination model-check/termination, Non termination detection +@subsection options_modelchecking_termination model-check/termination, Non termination detection -The \b model-check/termination configuration item can be used to report if a +The @b model-check/termination configuration item can be used to report if a non-termination execution path has been found. This is a path with a cycle which means that the program might never terminate. @@ -518,44 +518,44 @@ This only works in safety mode. This options is disabled by default. -\subsection options_modelchecking_dot_output model-check/dot-output, Dot output +@subsection options_modelchecking_dot_output model-check/dot-output, Dot output -If set, the \b model-check/dot-output configuration item is the name of a file +If set, the @b model-check/dot-output configuration item is the name of a file in which to write a dot file of the path leading the found property (safety or liveness violation) as well as the cycle for liveness properties. This dot file can then fed to the graphviz dot tool to generate an corresponding graphical representation. -\subsection options_modelchecking_max_depth model-check/max-depth, Depth limit +@subsection options_modelchecking_max_depth model-check/max-depth, Depth limit -The \b model-checker/max-depth can set the maximum depth of the exploration +The @b model-checker/max-depth can set the maximum depth of the exploration graph of the model-checker. If this limit is reached, a logging message is sent and the results might not be exact. By default, there is not depth limit. -\subsection options_modelchecking_timeout Handling of timeout +@subsection options_modelchecking_timeout Handling of timeout By default, the model-checker does not handle timeout conditions: the `wait` -operations never time out. With the \b model-check/timeout configuration item -set to \b yes, the model-checker will explore timeouts of `wait` operations. +operations never time out. With the @b model-check/timeout configuration item +set to @b yes, the model-checker will explore timeouts of `wait` operations. -\subsection options_modelchecking_comm_determinism Communication determinism +@subsection options_modelchecking_comm_determinism Communication determinism -The \b model-check/communications-determinism and -\b model-check/send-determinism items can be used to select the communication +The @b model-check/communications-determinism and +@b model-check/send-determinism items can be used to select the communication determinism mode of the model-checker which checks determinism properties of the communications of an application. -\subsection options_modelchecking_sparse_checkpoint Per page checkpoints +@subsection options_modelchecking_sparse_checkpoint Per page checkpoints When the model-checker is configured to take a snapshot of each explored state -(with the \b model-checker/visited item), the memory consumption can rapidly +(with the @b model-checker/visited item), the memory consumption can rapidly reach GiB ou Tib of memory. However, for many workloads, the memory does not change much between different snapshots and taking a complete copy of each snapshot is a waste of memory. -The \b model-check/sparse-checkpoint option item can be set to \b yes in order +The @b model-check/sparse-checkpoint option item can be set to @b yes in order to avoid making a complete copy of each snapshot: instead, each snapshot will be decomposed in blocks which will be stored separately. If multiple snapshots share the same block (or if the same block @@ -572,28 +572,28 @@ snapshotting strategy. This option is currently disabled by default. -\subsection options_mc_perf Performance considerations for the model checker +@subsection options_mc_perf Performance considerations for the model checker The size of the stacks can have a huge impact on the memory consumption when using model-checking. By default, each snapshot will save a copy of the whole stacks and not only of the part which is really meaningful: you should expect the contribution of the memory -consumption of the snapshots to be \f$ \mbox{number of processes} -\times \mbox{stack size} \times \mbox{number of states} \f$. +consumption of the snapshots to be @f$ @mbox{number of processes} +@times @mbox{stack size} @times @mbox{number of states} @f$. -The \b model-check/sparse-checkpoint can be used to reduce the memory +The @b model-check/sparse-checkpoint can be used to reduce the memory consumption by trying to share memory between the different snapshots. When compiled against the model checker, the stacks are not protected with guards: if the stack size is too small for your application, the stack will silently overflow on other parts of the -memory (see \ref options_virt_guard_size). +memory (see @ref options_virt_guard_size). -\subsection options_modelchecking_hash Hashing of the state (experimental) +@subsection options_modelchecking_hash Hashing of the state (experimental) Usually most of the time of the model-checker is spent comparing states. This process is complicated and consumes a lot of bandwidth and cache. -In order to speedup the state comparison, the experimental \b model-checker/hash +In order to speedup the state comparison, the experimental @b model-checker/hash configuration item enables the computation of a hash summarizing as much information of the state as possible into a single value. This hash can be used to avoid most of the comparisons: the costly comparison is then only used when @@ -603,7 +603,7 @@ Currently most of the state is not included in the hash because the implementation was found to be buggy and this options is not as useful as it could be. For this reason, it is currently disabled by default. -\subsection options_modelchecking_recordreplay Record/replay (experimental) +@subsection options_modelchecking_recordreplay Record/replay (experimental) As the model-checker keeps jumping at different places in the execution graph, it is difficult to understand what happens when trying to debug an application @@ -619,7 +619,7 @@ the model-checker and replay it without the model-checker. When the model-checker finds an interesting path in the application execution graph (where a safety or liveness property is violated), it can generate an identifier for this path. In order to enable this behavious the -\b model-check/record must be set to \b yes. By default, this behaviour is not +@b model-check/record must be set to @b yes. By default, this behaviour is not enabled. This is an example of output: @@ -639,7 +639,7 @@ This is an example of output: This path can then be replayed outside of the model-checker (and even in -non-MC build of simgrid) by setting the \b model-check/replay item to the given +non-MC build of simgrid) by setting the @b model-check/replay item to the given path. The other options should be the same (but the model-checker should be disabled). @@ -647,9 +647,9 @@ The format and meaning of the path may change between different releases so the same release of Simgrid should be used for the record phase and the replay phase. -\section options_virt Configuring the User Process Virtualization +@section options_virt Configuring the User Process Virtualization -\subsection options_virt_factory Selecting the virtualization factory +@subsection options_virt_factory Selecting the virtualization factory In SimGrid, the user code is virtualized in a specific mechanism that allows the simulation kernel to control its execution: when a user @@ -660,27 +660,27 @@ graphically in the [relevant tutorial, available online](http://simgrid.gforge.i In SimGrid, the containers in which user processes are virtualized are called contexts. Several context factory are provided, and you can -select the one you want to use with the \b contexts/factory +select the one you want to use with the @b contexts/factory configuration item. Some of the following may not exist on your machine because of portability issues. In any case, the default one should be the most effcient one (please report bugs if the auto-detection fails for you). They are approximately sorted here from the slowest to the most efficient: - - \b thread: very slow factory using full featured threads (either + - @b thread: very slow factory using full featured threads (either pthreads or windows native threads). They are slow but very standard. Some debuggers or profilers only work with this factory. - - \b java: Java applications are virtualized onto java threads (that + - @b java: Java applications are virtualized onto java threads (that are regular pthreads registered to the JVM) - - \b ucontext: fast factory using System V contexts (Linux and FreeBSD only) - - \b boost: This uses the [context implementation](http://www.boost.org/doc/libs/1_59_0/libs/context/doc/html/index.html) + - @b ucontext: fast factory using System V contexts (Linux and FreeBSD only) + - @b boost: This uses the [context implementation](http://www.boost.org/doc/libs/1_59_0/libs/context/doc/html/index.html) of the boost library for a performance that is comparable to our - raw implementation.\n Install the relevant library (e.g. with the + raw implementation.@n Install the relevant library (e.g. with the libboost-contexts-dev package on Debian/Ubuntu) and recompile SimGrid. Note that our implementation is not compatible with recent implementations of the library, and it will be hard to fix this since the library's author decided to hide an API that we were using. - - \b raw: amazingly fast factory using a context switching mechanism + - @b raw: amazingly fast factory using a context switching mechanism of our own, directly implemented in assembly (only available for x86 and amd64 platforms for now) and without any unneeded system call. @@ -692,7 +692,7 @@ to debug concurrency issues. Valgrind is also more comfortable with threads, but it should be usable with all factories (but the callgrind tool that really don't like raw and ucontext factories). -\subsection options_virt_stacksize Adapting the used stack size +@subsection options_virt_stacksize Adapting the used stack size Each virtualized used process is executed using a specific system stack. The size of this stack has a huge impact on the simulation @@ -702,7 +702,7 @@ rather disturbing: this leads to stack overflow (overwriting other stacks), leading to segfaults with corrupted stack traces. If you want to push the scalability limits of your code, you might -want to reduce the \b contexts/stack-size item. Its default value +want to reduce the @b contexts/stack-size item. Its default value is 8192 (in KiB), while our Chord simulation works with stacks as small as 16 KiB, for example. For the thread factory, the default value is the one of the system but you can still change it with this parameter. @@ -710,16 +710,16 @@ is the one of the system but you can still change it with this parameter. The operating system should only allocate memory for the pages of the stack which are actually used and you might not need to use this in most cases. However, this setting is very important when using the -model checker (see \ref options_mc_perf). +model checker (see @ref options_mc_perf). -\subsection options_virt_guard_size Disabling stack guard pages +@subsection options_virt_guard_size Disabling stack guard pages A stack guard page is usually used which prevents the stack of a given actor from overflowing on another stack. But the performance impact may become prohibitive when the amount of actors increases. The -option \b contexts:guard-size is the number of stack guard pages used. +option @b contexts:guard-size is the number of stack guard pages used. By setting it to 0, no guard pages will be used: in this case, you -should avoid using small stacks (\b stack-size) as the stack will +should avoid using small stacks (@b stack-size) as the stack will silently overflow on other parts of the memory. When no stack guard page is created, stacks may then silently overflow @@ -728,26 +728,26 @@ application. This happens: - on Windows systems; - when the model checker is enabled; -- and of course when guard pages are explicitely disabled (with \b contexts:guard-size=0). +- and of course when guard pages are explicitely disabled (with @b contexts:guard-size=0). -\subsection options_virt_parallel Running user code in parallel +@subsection options_virt_parallel Running user code in parallel Parallel execution of the user code is only considered stable in SimGrid v3.7 and higher, and mostly for MSG simulations. SMPI simulations may well fail in parallel mode. It is described in INRIA RR-7653. -If you are using the \c ucontext or \c raw context factories, you can +If you are using the @c ucontext or @c raw context factories, you can request to execute the user code in parallel. Several threads are launched, each of them handling as much user contexts at each run. To -actiave this, set the \b contexts/nthreads item to the amount of +actiave this, set the @b contexts/nthreads item to the amount of cores that you have in your computer (or lower than 1 to have the amount of cores auto-detected). Even if you asked several worker threads using the previous option, you can request to start the parallel execution (and pay the associated synchronization costs) only if the potential parallelism is -large enough. For that, set the \b contexts/parallel-threshold +large enough. For that, set the @b contexts/parallel-threshold item to the minimal amount of user contexts needed to start the parallel execution. In any given simulation round, if that amount is not reached, the contexts will be run sequentially directly by the @@ -756,24 +756,24 @@ option is mainly useful when the grain of the user code is very fine, because our synchronization is now very efficient. When parallel execution is activated, you can choose the -synchronization schema used with the \b contexts/synchro item, +synchronization schema used with the @b contexts/synchro item, which value is either: - - \b futex: ultra optimized synchronisation schema, based on futexes + - @b futex: ultra optimized synchronisation schema, based on futexes (fast user-mode mutexes), and thus only available on Linux systems. This is the default mode when available. - - \b posix: slow but portable synchronisation using only POSIX + - @b posix: slow but portable synchronisation using only POSIX primitives. - - \b busy_wait: not really a synchronisation: the worker threads + - @b busy_wait: not really a synchronisation: the worker threads constantly request new contexts to execute. It should be the most efficient synchronisation schema, but it loads all the cores of your machine for no good reason. You probably prefer the other less eager schemas. -\section options_tracing Configuring the tracing subsystem +@section options_tracing Configuring the tracing subsystem -The \ref outcomes_vizu "tracing subsystem" can be configured in several +The @ref outcomes_vizu "tracing subsystem" can be configured in several different ways depending on the nature of the simulator (MSG, SimDag, -SMPI) and the kind of traces that need to be obtained. See the \ref +SMPI) and the kind of traces that need to be obtained. See the @ref tracing_tracing_options "Tracing Configuration Options subsection" to get a detailed description of each configuration option. @@ -782,27 +782,27 @@ you never used the tracing API. - Any SimGrid-based simulator (MSG, SimDag, SMPI, ...) and raw traces: -\verbatim +@verbatim --cfg=tracing:yes --cfg=tracing/uncategorized:yes --cfg=triva/uncategorized:uncat.plist -\endverbatim +@endverbatim The first parameter activates the tracing subsystem, the second tells it to trace host and link utilization (without any categorization) and the third creates a graph configuration file to configure Triva when analysing the resulting trace file. - MSG or SimDag-based simulator and categorized traces (you need to declare categories and classify your tasks according to them) -\verbatim +@verbatim --cfg=tracing:yes --cfg=tracing/categorized:yes --cfg=triva/categorized:cat.plist -\endverbatim +@endverbatim The first parameter activates the tracing subsystem, the second tells it to trace host and link categorized utilization and the third creates a graph configuration file to configure Triva when analysing the resulting trace file. - SMPI simulator and traces for a space/time view: -\verbatim +@verbatim smpirun -trace ... -\endverbatim +@endverbatim The -trace parameter for the smpirun script runs the simulation with --cfg=tracing:yes and --cfg=tracing/smpi:yes. Check the smpirun's -help parameter for additional tracing options. @@ -812,22 +812,22 @@ correctly identify them later, or to provide data that can be used to reproduce an experiment. You have two ways to do that: - Add a string on top of the trace file as comment: -\verbatim +@verbatim --cfg=tracing/comment:my_simulation_identifier -\endverbatim +@endverbatim - Add the contents of a textual file on top of the trace file as comment: -\verbatim +@verbatim --cfg=tracing/comment-file:my_file_with_additional_information.txt -\endverbatim +@endverbatim Please, use these two parameters (for comments) to make reproducible simulations. For additional details about this and all tracing -options, check See the \ref tracing_tracing_options. +options, check See the @ref tracing_tracing_options. -\section options_msg Configuring MSG +@section options_msg Configuring MSG -\subsection options_msg_debug_multiple_use Debugging MSG +@subsection options_msg_debug_multiple_use Debugging MSG Sometimes your application may try to send a task that is still being executed somewhere else, making it impossible to send this task. However, @@ -836,40 +836,40 @@ doing. This option shows a backtrace of the other process. Enable this option by adding -\verbatim +@verbatim --cfg=msg/debug-multiple-use:on -\endverbatim +@endverbatim -\section options_smpi Configuring SMPI +@section options_smpi Configuring SMPI The SMPI interface provides several specific configuration items. These are uneasy to see since the code is usually launched through the -\c smiprun script directly. +@c smiprun script directly. -\subsection options_smpi_bench smpi/bench: Automatic benchmarking of SMPI code +@subsection options_smpi_bench smpi/bench: Automatic benchmarking of SMPI code In SMPI, the sequential code is automatically benchmarked, and these computations are automatically reported to the simulator. That is to -say that if you have a large computation between a \c MPI_Recv() and a -\c MPI_Send(), SMPI will automatically benchmark the duration of this +say that if you have a large computation between a @c MPI_Recv() and a +@c MPI_Send(), SMPI will automatically benchmark the duration of this code, and create an execution task within the simulator to take this into account. For that, the actual duration is measured on the host machine and then scaled to the power of the corresponding simulated -machine. The variable \b smpi/host-speed allows to specify the +machine. The variable @b smpi/host-speed allows to specify the computational speed of the host machine (in flop/s) to use when scaling the execution times. It defaults to 20000, but you really want to update it to get accurate simulation results. When the code is constituted of numerous consecutive MPI calls, the previous mechanism feeds the simulation kernel with numerous tiny -computations. The \b smpi/cpu-threshold item becomes handy when this +computations. The @b smpi/cpu-threshold item becomes handy when this impacts badly the simulation performance. It specifies a threshold (in seconds) below which the execution chunks are not reported to the simulation kernel (default value: 1e-6). -\note +@note The option smpi/cpu-threshold ignores any computation time spent - below this threshold. SMPI does not consider the \a amount of these + below this threshold. SMPI does not consider the @a amount of these computations; there is no offset for this. Hence, by using a value that is too low, you may end up with unreliable simulation results. @@ -886,13 +886,13 @@ being replayed/simulated. At the moment, these computation events can be simulated using SMPI by calling internal smpi_execute*() functions. To disable the benchmarking/simulation of computation in the simulated -application, the variable \b smpi/simulate-computation should be set to no. +application, the variable @b smpi/simulate-computation should be set to no. -\note +@note This option just ignores the timings in your simulation; it still executes the computations itself. If you want to stop SMPI from doing that, you should check the SMPI_SAMPLE macros, documented in the section - \ref SMPI_adapting_speed. + @ref SMPI_adapting_speed. Solution | Computations actually executed? | Computations simulated ? ---------------------------------- | ------------------------------- | ------------------------ @@ -900,17 +900,17 @@ Solution | Computations actually executed? | Computati --cfg=smpi/cpu-threshold:42 | Yes, in all cases | Only if it lasts more than 42 seconds SMPI_SAMPLE() macro | Only once per loop nest (see @ref SMPI_adapting_speed "documentation") | Always -\subsection options_model_smpi_adj_file smpi/comp-adjustment-file: Slow-down or speed-up parts of your code. +@subsection options_model_smpi_adj_file smpi/comp-adjustment-file: Slow-down or speed-up parts of your code. This option allows you to pass a file that contains two columns: The first column defines the section that will be subject to a speedup; the second column is the speedup. For instance: -\verbatim +@verbatim "start:stop","ratio" "exchange_1.f:30:exchange_1.f:130",1.18244559422142 -\endverbatim +@endverbatim The first line is the header - you must include it. The following line means that the code between two consecutive MPI calls on @@ -922,12 +922,12 @@ equal to 1. Of course, you can set any arbitrary filenames you want (so the start and end don't have to be in the same file), but be aware that this mechanism only supports @em consecutive calls! -\note - Please note that you must pass the \b -trace-call-location flag to smpicc +@note + Please note that you must pass the @b -trace-call-location flag to smpicc or smpiff, respectively! This flag activates some macro definitions in our mpi.h / mpi.f files that help with obtaining the call location. -\subsection options_model_smpi_bw_factor smpi/bw-factor: Bandwidth factors +@subsection options_model_smpi_bw_factor smpi/bw-factor: Bandwidth factors The possible throughput of network links is often dependent on the message sizes, as protocols may adapt to different message sizes. With @@ -935,36 +935,36 @@ this option, a series of message sizes and factors are given, helping the simulation to be more realistic. For instance, the current default value is -\verbatim +@verbatim 65472:0.940694;15424:0.697866;9376:0.58729;5776:1.08739;3484:0.77493;1426:0.608902;732:0.341987;257:0.338112;0:0.812084 -\endverbatim +@endverbatim So, messages with size 65472 and more will get a total of MAX_BANDWIDTH*0.940694, messages of size 15424 to 65471 will get MAX_BANDWIDTH*0.697866 and so on. Here, MAX_BANDWIDTH denotes the bandwidth of the link. -\note +@note The SimGrid-Team has developed a script to help you determine these values. You can find more information and the download here: 1. http://simgrid.gforge.inria.fr/contrib/smpi-calibration-doc.html 2. http://simgrid.gforge.inria.fr/contrib/smpi-saturation-doc.html -\subsection options_smpi_timing smpi/display-timing: Reporting simulation time +@subsection options_smpi_timing smpi/display-timing: Reporting simulation time -\b Default: 0 (false) +@b Default: 0 (false) Most of the time, you run MPI code with SMPI to compute the time it would take to run it on a platform. But since the -code is run through the \c smpirun script, you don't have any control +code is run through the @c smpirun script, you don't have any control on the launcher code, making it difficult to report the simulated time -when the simulation ends. If you set the \b smpi/display-timing item -to 1, \c smpirun will display this information when the simulation ends. \verbatim +when the simulation ends. If you set the @b smpi/display-timing item +to 1, @c smpirun will display this information when the simulation ends. @verbatim Simulation time: 1e3 seconds. -\endverbatim +@endverbatim -\subsection options_smpi_temps smpi/keep-temps: not cleaning up after simulation +@subsection options_smpi_temps smpi/keep-temps: not cleaning up after simulation -\b Default: 0 (false) +@b Default: 0 (false) Under some conditions, SMPI generates a lot of temporary files. They usually get cleaned, but you may use this option to not erase these @@ -972,30 +972,30 @@ files. This is for example useful when debugging or profiling executions using the dlopen privatization schema, as missing binary files tend to fool the debuggers. -\subsection options_model_smpi_lat_factor smpi/lat-factor: Latency factors +@subsection options_model_smpi_lat_factor smpi/lat-factor: Latency factors The motivation and syntax for this option is identical to the motivation/syntax -of smpi/bw-factor, see \ref options_model_smpi_bw_factor for details. +of smpi/bw-factor, see @ref options_model_smpi_bw_factor for details. -There is an important difference, though: While smpi/bw-factor \a reduces the +There is an important difference, though: While smpi/bw-factor @a reduces the actual bandwidth (i.e., values between 0 and 1 are valid), latency factors increase the latency, i.e., values larger than or equal to 1 are valid here. This is the default value: -\verbatim +@verbatim 65472:11.6436;15424:3.48845;9376:2.59299;5776:2.18796;3484:1.88101;1426:1.61075;732:1.9503;257:1.95341;0:2.01467 -\endverbatim +@endverbatim -\note +@note The SimGrid-Team has developed a script to help you determine these values. You can find more information and the download here: 1. http://simgrid.gforge.inria.fr/contrib/smpi-calibration-doc.html 2. http://simgrid.gforge.inria.fr/contrib/smpi-saturation-doc.html -\subsection options_smpi_papi_events smpi/papi-events: Trace hardware counters with PAPI +@subsection options_smpi_papi_events smpi/papi-events: Trace hardware counters with PAPI -\warning +@warning This option is experimental and will be subject to change. This feature currently requires superuser privileges, as registers are queried. Only use this feature with code you trust! Call smpirun for instance via @@ -1003,21 +1003,21 @@ This is the default value: or run sudo sh -c "echo 0 > /proc/sys/kernel/perf_event_paranoid" In the later case, sudo will not be required. -\note +@note This option is only available when SimGrid was compiled with PAPI support. This option takes the names of PAPI counters and adds their respective values -to the trace files. (See Section \ref tracing_tracing_options.) +to the trace files. (See Section @ref tracing_tracing_options.) It is planned to make this feature available on a per-process (or per-thread?) basis. The first draft, however, just implements a "global" (i.e., for all processes) set of counters, the "default" set. -\verbatim +@verbatim --cfg=smpi/papi-events:"default:PAPI_L3_LDM:PAPI_L2_LDM" -\endverbatim +@endverbatim -\subsection options_smpi_privatization smpi/privatization: Automatic privatization of global variables +@subsection options_smpi_privatization smpi/privatization: Automatic privatization of global variables MPI executables are usually meant to be executed in separated processes, but SMPI is executed in only one process. Global variables @@ -1030,16 +1030,16 @@ ways of automatically privatizing the globals, and this option allows to choose between them. - no (default when not using smpirun): Do not automatically privatize variables. - Pass \c -no-privatize to smpirun to disable this feature. + Pass @c -no-privatize to smpirun to disable this feature. - dlopen or yes (default when using smpirun): Link multiple times against the binary. - mmap (slower, but maybe somewhat more stable): Runtime automatic switching of the data segments. -\warning +@warning This configuration option cannot be set in your platform file. You can only pass it as an argument to smpirun. -\subsection options_smpi_privatize_libs smpi/privatize-libs: Automatic privatization of +@subsection options_smpi_privatize_libs smpi/privatize-libs: Automatic privatization of global variables inside external libraries Linux/BSD only: When using dlopen (default) privatization, privatize specific @@ -1047,7 +1047,7 @@ shared libraries with internal global variables, if they can't be linked statica For example libgfortran is usually used for Fortran I/O and indexes in files can be mixed up. -\warning +@warning This configuration option can only use either full paths to libraries, or full names. Check with ldd the name of the library you want to use. Example: @@ -1057,32 +1057,32 @@ can be mixed up. Multiple libraries can be given, semicolon separated. -\subsection options_model_smpi_detached Simulating MPI detached send +@subsection options_model_smpi_detached Simulating MPI detached send This threshold specifies the size in bytes under which the send will return -immediately. This is different from the threshold detailed in \ref options_model_network_asyncsend +immediately. This is different from the threshold detailed in @ref options_model_network_asyncsend because the message is not effectively sent when the send is posted. SMPI still waits for the correspondant receive to be posted to perform the communication operation. This threshold can be set -by changing the \b smpi/send-is-detached-thresh item. The default value is 65536. +by changing the @b smpi/send-is-detached-thresh item. The default value is 65536. -\subsection options_model_smpi_collectives Simulating MPI collective algorithms +@subsection options_model_smpi_collectives Simulating MPI collective algorithms SMPI implements more than 100 different algorithms for MPI collective communication, to accurately -simulate the behavior of most of the existing MPI libraries. The \b smpi/coll-selector item can be used +simulate the behavior of most of the existing MPI libraries. The @b smpi/coll-selector item can be used to use the decision logic of either OpenMPI or MPICH libraries (values: ompi or mpich, by default SMPI uses naive version of collective operations). Each collective operation can be manually selected with a -\b smpi/collective_name:algo_name. Available algorithms are listed in \ref SMPI_use_colls . +@b smpi/collective_name:algo_name. Available algorithms are listed in @ref SMPI_use_colls . -\subsection options_model_smpi_iprobe smpi/iprobe: Inject constant times for calls to MPI_Iprobe +@subsection options_model_smpi_iprobe smpi/iprobe: Inject constant times for calls to MPI_Iprobe -\b Default value: 0.0001 +@b Default value: 0.0001 -The behavior and motivation for this configuration option is identical with \a smpi/test, see -Section \ref options_model_smpi_test for details. +The behavior and motivation for this configuration option is identical with @a smpi/test, see +Section @ref options_model_smpi_test for details. -\subsection options_model_smpi_iprobe_cpu_usage smpi/iprobe-cpu-usage: Reduce speed for iprobe calls +@subsection options_model_smpi_iprobe_cpu_usage smpi/iprobe-cpu-usage: Reduce speed for iprobe calls -\b Default value: 1 (no change from default behavior) +@b Default value: 1 (no change from default behavior) MPI_Iprobe calls can be heavily used in applications. To account correctly for the energy cores spend probing, it is necessary to reduce the load that these calls cause inside @@ -1092,32 +1092,32 @@ For instance, we measured a max power consumption of 220 W for a particular appl only 180 W while this application was probing. Hence, the correct factor that should be passed to this option would be 180/220 = 0.81. -\subsection options_model_smpi_init smpi/init: Inject constant times for calls to MPI_Init +@subsection options_model_smpi_init smpi/init: Inject constant times for calls to MPI_Init -\b Default value: 0 +@b Default value: 0 -The behavior for this configuration option is identical with \a smpi/test, see -Section \ref options_model_smpi_test for details. +The behavior for this configuration option is identical with @a smpi/test, see +Section @ref options_model_smpi_test for details. -\subsection options_model_smpi_ois smpi/ois: Inject constant times for asynchronous send operations +@subsection options_model_smpi_ois smpi/ois: Inject constant times for asynchronous send operations -This configuration option works exactly as \a smpi/os, see Section \ref options_model_smpi_os. -Of course, \a smpi/ois is used to account for MPI_Isend instead of MPI_Send. +This configuration option works exactly as @a smpi/os, see Section @ref options_model_smpi_os. +Of course, @a smpi/ois is used to account for MPI_Isend instead of MPI_Send. -\subsection options_model_smpi_os smpi/os: Inject constant times for send operations +@subsection options_model_smpi_os smpi/os: Inject constant times for send operations In several network models such as LogP, send (MPI_Send, MPI_Isend) and receive (MPI_Recv) operations incur costs (i.e., they consume CPU time). SMPI can factor these costs in as well, but the user has to configure SMPI accordingly as these values may vary by machine. This can be done by using smpi/os for MPI_Send operations; for MPI_Isend and -MPI_Recv, use \a smpi/ois and \a smpi/or, respectively. These work exactly as -\a smpi/ois. +MPI_Recv, use @a smpi/ois and @a smpi/or, respectively. These work exactly as +@a smpi/ois. -\a smpi/os can consist of multiple sections; each section takes three values, for example: +@a smpi/os can consist of multiple sections; each section takes three values, for example: -\verbatim +@verbatim 1:3:2;10:5:1 -\endverbatim +@endverbatim Here, the sections are divided by ";" (that is, this example contains two sections). Furthermore, each section consists of three values. @@ -1131,7 +1131,7 @@ Furthermore, each section consists of three values. be charged, no matter what the size of the message. In the first section above, this value is "3". -3. The third value is the \a per-byte cost. That is, it is charged for every +3. The third value is the @a per-byte cost. That is, it is charged for every byte of the message (incurring cost messageSize*cost_per_byte) and hence accounts also for larger messages. In the first section of the example above, this value is "2". @@ -1142,23 +1142,23 @@ the second section will be used, not the first, as the first value of the second section is closer to the message size. Hence, a message of size 11 incurs the following cost inside MPI_Send: -\verbatim +@verbatim 5+11*1 -\endverbatim +@endverbatim As 5 is the startup cost and 1 is the cost per byte. -\note +@note The order of sections can be arbitrary; they will be ordered internally. -\subsection options_model_smpi_or smpi/or: Inject constant times for receive operations +@subsection options_model_smpi_or smpi/or: Inject constant times for receive operations -This configuration option works exactly as \a smpi/os, see Section \ref options_model_smpi_os. -Of course, \a smpi/or is used to account for MPI_Recv instead of MPI_Send. +This configuration option works exactly as @a smpi/os, see Section @ref options_model_smpi_os. +Of course, @a smpi/or is used to account for MPI_Recv instead of MPI_Send. -\subsection options_model_smpi_test smpi/test: Inject constant times for calls to MPI_Test +@subsection options_model_smpi_test smpi/test: Inject constant times for calls to MPI_Test -\b Default value: 0.0001 +@b Default value: 0.0001 By setting this option, you can control the amount of time a process sleeps when MPI_Test() is called; this is important, because SimGrid normally only @@ -1168,14 +1168,14 @@ break-condition. Here is an example: -\code{.unparsed} +@code{.unparsed} while(!flag) { MPI_Test(request, flag, status); ... } -\endcode +@endcode -\note +@note Internally, in order to speed up execution, we use a counter to keep track on how often we already checked if the handle is now valid or not. Hence, we actually use counter*SLEEP_TIME, that is, the time MPI_Test() causes the process @@ -1184,9 +1184,9 @@ Here is an example: also disable this behavior for MPI_Iprobe. -\subsection options_model_smpi_shared_malloc smpi/shared-malloc: Factorize malloc()s +@subsection options_model_smpi_shared_malloc smpi/shared-malloc: Factorize malloc()s -\b Default: global +@b Default: global If your simulation consumes too much memory, you may want to modify your code so that the working areas are shared by all MPI ranks. For @@ -1200,14 +1200,14 @@ section of the SMPI CourseWare (see Activity #2.2 of the pointed assignment). In practice, change the call to malloc() and free() into SMPI_SHARED_MALLOC() and SMPI_SHARED_FREE(). -SMPI provides 2 algorithms for this feature. The first one, called \c +SMPI provides 2 algorithms for this feature. The first one, called @c local, allocates one bloc per call to SMPI_SHARED_MALLOC() in your code (each call location gets its own bloc) and this bloc is shared amongst all MPI ranks. This is implemented with the shm_* functions to create a new POSIX shared memory object (kept in RAM, in /dev/shm) for each shared bloc. -With the \c global algorithm, each call to SMPI_SHARED_MALLOC() +With the @c global algorithm, each call to SMPI_SHARED_MALLOC() returns a new adress, but it only points to a shadow bloc: its memory area is mapped on a 1MiB file on disk. If the returned bloc is of size N MiB, then the same file is mapped N times to cover the whole bloc. @@ -1215,7 +1215,7 @@ At the end, no matter how many SMPI_SHARED_MALLOC you do, this will only consume 1 MiB in memory. You can disable this behavior and come back to regular mallocs (for -example for debugging purposes) using \c "no" as a value. +example for debugging purposes) using @c "no" as a value. If you want to keep private some parts of the buffer, for instance if these parts are used by the application logic and should not be corrupted, you @@ -1223,9 +1223,9 @@ can use SMPI_PARTIAL_SHARED_MALLOC(size, offsets, offsets_count). As an example, -\code{.C} +@code{.C} mem = SMPI_PARTIAL_SHARED_MALLOC(500, {27,42 , 100,200}, 2); -\endcode +@endcode will allocate 500 bytes to mem, such that mem[27..41] and mem[100..199] are shared and other area remain private. @@ -1239,18 +1239,18 @@ entry per Mb of malloced data instead of one entry per 4k. To activate this, you must mount a hugetlbfs on your system and allocate at least one huge page: -\code{.sh} +@code{.sh} mkdir /home/huge sudo mount none /home/huge -t hugetlbfs -o rw,mode=0777 sudo sh -c 'echo 1 > /proc/sys/vm/nr_hugepages' # echo more if you need more -\endcode +@endcode Then, you can pass the option --cfg=smpi/shared-malloc-hugepage:/home/huge to smpirun to actually activate the huge page support in shared mallocs. -\subsection options_model_smpi_wtime smpi/wtime: Inject constant times for calls to MPI_Wtime +@subsection options_model_smpi_wtime smpi/wtime: Inject constant times for calls to MPI_Wtime -\b Default value: 0 +@b Default value: 0 By setting this option, you can control the amount of time a process sleeps when MPI_Wtime() is called; this is important, because SimGrid normally only @@ -1260,22 +1260,22 @@ break-condition. Here is an example: -\code{.unparsed} +@code{.unparsed} while(MPI_Wtime() < some_time_bound) { ... } -\endcode +@endcode If the time is never advanced, this loop will clearly never end as MPI_Wtime() always returns the same value. Hence, pass a (small) value to the smpi/wtime option to force a call to MPI_Wtime to advance the time as well. -\section options_generic Configuring other aspects of SimGrid +@section options_generic Configuring other aspects of SimGrid -\subsection options_generic_clean_atexit Cleanup before termination +@subsection options_generic_clean_atexit Cleanup before termination -The C / C++ standard contains a function called \b [atexit](http://www.cplusplus.com/reference/cstdlib/atexit/). +The C / C++ standard contains a function called @b [atexit](http://www.cplusplus.com/reference/cstdlib/atexit/). atexit registers callbacks, which are called just before the program terminates. By setting the configuration option clean-atexit to 1 (true), a callback @@ -1283,20 +1283,20 @@ is registered and will clean up some variables and terminate/cleanup the tracing TODO: Add when this should be used. -\subsection options_generic_path Profile files' search path +@subsection options_generic_path Profile files' search path It is possible to specify a list of directories to search into for the -trace files (see @ref pf_trace) by using the \b path configuration +trace files (see @ref pf_trace) by using the @b path configuration item. To add several directory to the path, set the configuration -item several times, as in \verbatim +item several times, as in @verbatim --cfg=path:toto --cfg=path:tutu -\endverbatim +@endverbatim -\subsection options_generic_breakpoint Set a breakpoint +@subsection options_generic_breakpoint Set a breakpoint -\verbatim +@verbatim --cfg=simix/breakpoint:3.1416 -\endverbatim +@endverbatim This configuration option sets a breakpoint: when the simulated clock reaches the given time, a SIGTRAP is raised. This can be used to stop the execution and @@ -1305,23 +1305,23 @@ get a backtrace with a debugger. It is also possible to set the breakpoint from inside the debugger, by writing in global variable simgrid::simix::breakpoint. For example, with gdb: -\verbatim +@verbatim set variable simgrid::simix::breakpoint = 3.1416 -\endverbatim +@endverbatim -\subsection options_generic_exit Behavior on Ctrl-C +@subsection options_generic_exit Behavior on Ctrl-C By default, when Ctrl-C is pressed, the status of all existing simulated processes is displayed before exiting the simulation. This is very useful to debug your code, but it can reveal troublesome in some cases (such as when the amount of processes becomes really big). This behavior is disabled -when \b verbose-exit is set to 0 (it is to 1 by default). +when @b verbose-exit is set to 0 (it is to 1 by default). -\subsection options_exception_cutpath Truncate local path from exception backtrace +@subsection options_exception_cutpath Truncate local path from exception backtrace -\verbatim +@verbatim --cfg=exception/cutpath:1 -\endverbatim +@endverbatim This configuration option is used to remove the path from the backtrace shown when an exception is thrown. This is mainly useful for @@ -1330,8 +1330,8 @@ thus failing as we are currently comparing output. Clearly, the path used on different machines are almost guaranteed to be different and hence, the output would mismatch, causing the test to fail. -\section options_log Logging Configuration +@section options_log Logging Configuration -It can be done by using XBT. Go to \ref XBT_log for more details. +It can be done by using XBT. Go to @ref XBT_log for more details. */ diff --git a/doc/doxygen/outcomes_vizu.doc b/doc/doxygen/outcomes_vizu.doc index 1c4381c20b..06fdfd09ee 100644 --- a/doc/doxygen/outcomes_vizu.doc +++ b/doc/doxygen/outcomes_vizu.doc @@ -1,4 +1,4 @@ -/*! \page outcomes_vizu Visualization and Statistical Analysis +/*! @page outcomes_vizu Visualization and Statistical Analysis SimGrid comes with an extensive support to trace and register what happens during the simulation, so that it can be either visualized or @@ -15,7 +15,7 @@ and analyze them. This part of the user manual explains how the tracing-related features can be enabled and used during the development of simulators using the SimGrid library. -\section instr_category_functions Tracing categories functions +@section instr_category_functions Tracing categories functions The SimGrid library is instrumented so users can trace the platform utilization using MSG, SimDAG and SMPI interfaces. It registers how @@ -33,192 +33,192 @@ below let the user declare a category and apply it to tasks. The tasks that are not classified according to a category are not traced. Even if the user does not specify any category, the simulations can still be traced in terms of resource utilization by -using a special parameter that is detailed below (see section \ref +using a special parameter that is detailed below (see section @ref tracing_tracing_options). -\li \c TRACE_category(const char *category) -\li \c TRACE_category_with_color(const char *category, const char *color) -\li \c MSG_task_set_category(msg_task_t task, const char *category) -\li \c MSG_task_get_category(msg_task_t task) -\li \c SD_task_set_category(SD_task_t task, const char *category) -\li \c SD_task_get_category(SD_task_t task) +@li @c TRACE_category(const char *category) +@li @c TRACE_category_with_color(const char *category, const char *color) +@li @c MSG_task_set_category(msg_task_t task, const char *category) +@li @c MSG_task_get_category(msg_task_t task) +@li @c SD_task_set_category(SD_task_t task, const char *category) +@li @c SD_task_get_category(SD_task_t task) -\section instr_mark_functions Tracing marks functions -\li \c TRACE_declare_mark(const char *mark_type) -\li \c TRACE_mark(const char *mark_type, const char *mark_value) +@section instr_mark_functions Tracing marks functions +@li @c TRACE_declare_mark(const char *mark_type) +@li @c TRACE_mark(const char *mark_type, const char *mark_value) -\section instr_uservariables_functions Tracing user variables functions +@section instr_uservariables_functions Tracing user variables functions For hosts: -\li \c TRACE_host_variable_declare(const char *variable) -\li \c TRACE_host_variable_declare_with_color(const char *variable, const char *color) -\li \c TRACE_host_variable_set(const char *host, const char *variable, double value) -\li \c TRACE_host_variable_add(const char *host, const char *variable, double value) -\li \c TRACE_host_variable_sub(const char *host, const char *variable, double value) -\li \c TRACE_host_variable_set_with_time(double time, const char *host, const char *variable, double value) -\li \c TRACE_host_variable_add_with_time(double time, const char *host, const char *variable, double value) -\li \c TRACE_host_variable_sub_with_time(double time, const char *host, const char *variable, double value) +@li @c TRACE_host_variable_declare(const char *variable) +@li @c TRACE_host_variable_declare_with_color(const char *variable, const char *color) +@li @c TRACE_host_variable_set(const char *host, const char *variable, double value) +@li @c TRACE_host_variable_add(const char *host, const char *variable, double value) +@li @c TRACE_host_variable_sub(const char *host, const char *variable, double value) +@li @c TRACE_host_variable_set_with_time(double time, const char *host, const char *variable, double value) +@li @c TRACE_host_variable_add_with_time(double time, const char *host, const char *variable, double value) +@li @c TRACE_host_variable_sub_with_time(double time, const char *host, const char *variable, double value) For links: -\li \c TRACE_link_variable_declare(const char *variable) -\li \c TRACE_link_variable_declare_with_color(const char *variable, const char *color) -\li \c TRACE_link_variable_set(const char *link, const char *variable, double value) -\li \c TRACE_link_variable_add(const char *link, const char *variable, double value) -\li \c TRACE_link_variable_sub(const char *link, const char *variable, double value) -\li \c TRACE_link_variable_set_with_time(double time, const char *link, const char *variable, double value) -\li \c TRACE_link_variable_add_with_time(double time, const char *link, const char *variable, double value) -\li \c TRACE_link_variable_sub_with_time(double time, const char *link, const char *variable, double value) +@li @c TRACE_link_variable_declare(const char *variable) +@li @c TRACE_link_variable_declare_with_color(const char *variable, const char *color) +@li @c TRACE_link_variable_set(const char *link, const char *variable, double value) +@li @c TRACE_link_variable_add(const char *link, const char *variable, double value) +@li @c TRACE_link_variable_sub(const char *link, const char *variable, double value) +@li @c TRACE_link_variable_set_with_time(double time, const char *link, const char *variable, double value) +@li @c TRACE_link_variable_add_with_time(double time, const char *link, const char *variable, double value) +@li @c TRACE_link_variable_sub_with_time(double time, const char *link, const char *variable, double value) For links, but use source and destination to get route: -\li \c TRACE_link_srcdst_variable_set(const char *src, const char *dst, const char *variable, double value) -\li \c TRACE_link_srcdst_variable_add(const char *src, const char *dst, const char *variable, double value) -\li \c TRACE_link_srcdst_variable_sub(const char *src, const char *dst, const char *variable, double value) -\li \c TRACE_link_srcdst_variable_set_with_time(double time, const char *src, const char *dst, const char *variable, double value) -\li \c TRACE_link_srcdst_variable_add_with_time(double time, const char *src, const char *dst, const char *variable, double value) -\li \c TRACE_link_srcdst_variable_sub_with_time(double time, const char *src, const char *dst, const char *variable, double value) +@li @c TRACE_link_srcdst_variable_set(const char *src, const char *dst, const char *variable, double value) +@li @c TRACE_link_srcdst_variable_add(const char *src, const char *dst, const char *variable, double value) +@li @c TRACE_link_srcdst_variable_sub(const char *src, const char *dst, const char *variable, double value) +@li @c TRACE_link_srcdst_variable_set_with_time(double time, const char *src, const char *dst, const char *variable, double value) +@li @c TRACE_link_srcdst_variable_add_with_time(double time, const char *src, const char *dst, const char *variable, double value) +@li @c TRACE_link_srcdst_variable_sub_with_time(double time, const char *src, const char *dst, const char *variable, double value) -\section tracing_tracing_options Tracing configuration Options +@section tracing_tracing_options Tracing configuration Options To check which tracing options are available for your simulator, you -can just run it with the option \verbatim --help-tracing \endverbatim +can just run it with the option @verbatim --help-tracing @endverbatim to get a very detailed and updated explanation of each tracing parameter. These are some of the options accepted by the tracing system of SimGrid, you can use them by running your simulator with the --cfg= switch: -\li \c +@li @c tracing : Safe switch. It activates (or deactivates) the tracing system. No other tracing options take effect if this one is not activated. -\verbatim +@verbatim --cfg=tracing:yes -\endverbatim +@endverbatim -\li \c +@li @c tracing/categorized : It activates the categorized resource utilization tracing. It should be enabled if tracing categories are used by this simulator. -\verbatim +@verbatim --cfg=tracing/categorized:yes -\endverbatim +@endverbatim -\li \c +@li @c tracing/uncategorized : It activates the uncategorized resource utilization tracing. Use it if this simulator do not use tracing categories and resource use have to be traced. -\verbatim +@verbatim --cfg=tracing/uncategorized:yes -\endverbatim +@endverbatim -\li \c +@li @c tracing/filename : A file with this name will be created to register the simulation. The file is in the Paje format and can be analyzed using Paje visualization tools. More information can be found in these webpages: http://github.com/schnorr/pajeng/ -\verbatim +@verbatim --cfg=tracing/filename:mytracefile.trace -\endverbatim +@endverbatim If you do not provide this parameter, the trace file will be named simgrid.trace. -\li \c +@li @c tracing/smpi : This option only has effect if this simulator is SMPI-based. Traces the MPI interface and generates a trace that can be analyzed using Gantt-like visualizations. Every MPI function (implemented by SMPI) is transformed in a state, and point-to-point communications can be analyzed with arrows. -\verbatim +@verbatim --cfg=tracing/smpi:yes -\endverbatim +@endverbatim -\li \c +@li @c tracing/smpi/group : This option only has effect if this simulator is SMPI-based. The processes are grouped by the hosts where they were executed. -\verbatim +@verbatim --cfg=tracing/smpi/group:yes -\endverbatim +@endverbatim -\li \c +@li @c tracing/smpi/computing : This option only has effect if this simulator is SMPI-based. The parts external to SMPI are also outputted to the trace. Provides better way to analyze the data automatically. -\verbatim +@verbatim --cfg=tracing/smpi/computing:yes -\endverbatim +@endverbatim -\li \c +@li @c tracing/smpi/internals : This option only has effect if this simulator is SMPI-based. Display internal communications happening during a collective MPI call. -\verbatim +@verbatim --cfg=tracing/smpi/internals:yes -\endverbatim +@endverbatim -\li \c +@li @c tracing/smpi/display-sizes : This option only has effect if this simulator is SMPI-based. Display the sizes of the messages exchanged in the trace, both in the links and on the states. For collective, size means the global size of data sent by the process in general. -\verbatim +@verbatim --cfg=tracing/smpi/display-sizes:yes -\endverbatim +@endverbatim -\li \c +@li @c tracing/smpi/sleeping : TODO -\verbatim +@verbatim TODO -\endverbatim +@endverbatim -\li \c +@li @c tracing/smpi/format : TODO -\verbatim +@verbatim TODO -\endverbatim +@endverbatim -\li \c +@li @c tracing/smpi/format/ti-one-file : TODO -\verbatim +@verbatim TODO -\endverbatim +@endverbatim -\li \c +@li @c tracing/vm : TODO -\verbatim +@verbatim TODO -\endverbatim +@endverbatim -\li \c +@li @c tracing/msg/process : This option only has effect if this simulator is MSG-based. It traces the behavior of all categorized MSG processes, grouping them by hosts. This option can be used to track process location if this simulator has process migration. -\verbatim +@verbatim --cfg=tracing/msg/process:yes -\endverbatim +@endverbatim -\li \c +@li @c tracing/buffer : This option put some events in a time-ordered buffer using the @@ -227,11 +227,11 @@ tracing/buffer make this process slow. The simulator performance can be severely impacted if this option is activated, but you are sure to get a trace file with events sorted. -\verbatim +@verbatim --cfg=tracing/buffer:yes -\endverbatim +@endverbatim -\li \c +@li @c tracing/onelink-only : This option changes the way SimGrid register its platform on the trace @@ -240,131 +240,131 @@ size) on the platform file to re-create the resource topology. If this option is activated, only the routes with one link are used to register the topology within a netzone. Routes among netzones continue to be traced as usual. -\verbatim +@verbatim --cfg=tracing/onelink-only:yes -\endverbatim +@endverbatim -\li \c +@li @c tracing/disable-link : TODO -\verbatim +@verbatim TODO -\endverbatim +@endverbatim -\li \c +@li @c tracing/disable-power : TODO -\verbatim +@verbatim TODO -\endverbatim +@endverbatim -\li \c +@li @c tracing/disable-destroy : Disable the destruction of containers at the end of simulation. This can be used with simulators that have a different notion of time (different from the simulated time). -\verbatim +@verbatim --cfg=tracing/disable-destroy:yes -\endverbatim +@endverbatim -\li \c +@li @c tracing/basic : Some visualization tools are not able to parse correctly the Paje file format. Use this option if you are using one of these tools to visualize the simulation trace. Keep in mind that the trace might be incomplete, without all the information that would be registered otherwise. -\verbatim +@verbatim --cfg=tracing/basic:yes -\endverbatim +@endverbatim -\li \c +@li @c tracing/comment : Use this to add a comment line to the top of the trace file. -\verbatim +@verbatim --cfg=tracing/comment:my_string -\endverbatim +@endverbatim -\li \c +@li @c tracing/comment-file : Use this to add the contents of a file to the top of the trace file as comment. -\verbatim +@verbatim --cfg=tracing/comment-file:textual_file.txt -\endverbatim +@endverbatim -\li \c +@li @c tracing/precision : This option determines the precision of timings stored in the trace file. Make sure -you set \ref options_model_precision to at least the same value as this option! (Traces +you set @ref options_model_precision to at least the same value as this option! (Traces cannot be more accurate than the simulation; they can be less accurate, though.) The following example will give you a precision of E-10 in the trace file: -\verbatim +@verbatim --cfg=tracing/precision:10 -\endverbatim +@endverbatim -\li \c +@li @c tracing/platform : TODO -\verbatim +@verbatim TODO -\endverbatim +@endverbatim -\li \c +@li @c tracing/platform/topology : TODO -\verbatim +@verbatim TODO -\endverbatim +@endverbatim -Please pass \verbatim --help-tracing \endverbatim to your simulator +Please pass @verbatim --help-tracing @endverbatim to your simulator for the updated list of tracing options. -\section tracing_tracing_example_parameters Case studies +@section tracing_tracing_example_parameters Case studies Some scenarios that might help you decide which tracing options you should use to analyze your simulator. -\li I want to trace the resource utilization of all hosts +@li I want to trace the resource utilization of all hosts and links of the platform, and my simulator does not use the tracing API. For that, you can run a uncategorized trace with the following parameters (it will work with any Simgrid simulator): -\verbatim -./your_simulator \ - --cfg=tracing:yes \ - --cfg=tracing/uncategorized:yes \ - --cfg=tracing/filename:mytracefile.trace \ -\endverbatim - -\li I want to trace only a subset of my MSG (or SimDAG) tasks. +@verbatim +./your_simulator @ + --cfg=tracing:yes @ + --cfg=tracing/uncategorized:yes @ + --cfg=tracing/filename:mytracefile.trace @ +@endverbatim + +@li I want to trace only a subset of my MSG (or SimDAG) tasks. For that, you will need to create tracing categories using the TRACE_category (...) function (as explained above), and then classify your tasks to a previously declared category using the MSG_task_set_category (...) (or SD_task_set_category (...) for SimDAG tasks). After recompiling, run your simulator with the following parameters: -\verbatim -./your_simulator \ - --cfg=tracing:yes \ - --cfg=tracing/categorized:yes \ - --cfg=tracing/filename:mytracefile.trace \ -\endverbatim +@verbatim +./your_simulator @ + --cfg=tracing:yes @ + --cfg=tracing/categorized:yes @ + --cfg=tracing/filename:mytracefile.trace @ +@endverbatim -\section tracing_tracing_example Example of Instrumentation +@section tracing_tracing_example Example of Instrumentation A simplified example using the tracing mandatory functions. -\verbatim +@verbatim int main (int argc, char **argv) { MSG_init (&argc, &argv); @@ -396,9 +396,9 @@ int main (int argc, char **argv) MSG_clean(); return 0; } -\endverbatim +@endverbatim -\section tracing_tracing_analyzing Analyzing SimGrid Simulation Traces +@section tracing_tracing_analyzing Analyzing SimGrid Simulation Traces A SimGrid-based simulator, when executed with the correct parameters (see above) creates a trace file in the Paje file format holding the diff --git a/doc/doxygen/platform.doc b/doc/doxygen/platform.doc index 94e1194de1..3b909d4521 100644 --- a/doc/doxygen/platform.doc +++ b/doc/doxygen/platform.doc @@ -1,17 +1,17 @@ -/*! \page platform Describing the virtual platform +/*! @page platform Describing the virtual platform @tableofcontents -\htmlonly +@htmlonly
-\endhtmlonly -\htmlinclude graphical-toc.svg -\htmlonly +@endhtmlonly +@htmlinclude graphical-toc.svg +@htmlonly
-\endhtmlonly +@endhtmlonly As @ref starting_components "explained in the introduction," any SimGrid study must entail the description of the platform on which you @@ -44,7 +44,7 @@ As usual, SimGrid is a versatile framework, and you should find the way of describing your platform that best fits your experimental practice. -\section pf_overview Describing the platform with XML +@section pf_overview Describing the platform with XML Your platform description should follow the specification presented in the [simgrid.dtd](http://simgrid.gforge.inria.fr/simgrid/simgrid.dtd) @@ -57,12 +57,12 @@ enclosed within a @c platform tag, that have a @c version attribute. The current version is 4.1. The @c simgrid_update_xml program can upgrade most of the past platform files to the recent formalism. -\section pf_first_example First Platform Example +@section pf_first_example First Platform Example Here is a very simple platform file, containing 3 resources (two hosts and one link), and explicitly giving the route between the hosts. -\code{.xml} +@code{.xml} @@ -77,7 +77,7 @@ and one link), and explicitly giving the route between the hosts. -\endcode +@endcode As we said, the englobing @ref pf_overview "<platform>" tag is used to specify the dtd version used for this file. @@ -115,11 +115,11 @@ models the core of a national network interconnecting a small flat cluster (AS4) and a larger hierarchical cluster (AS5), a subset of a LAN (AS6), and a set of peers scattered around the world (AS7). -\section pf_res Resource description +@section pf_res Resource description -\subsection pf_res_computing Computing Resources +@subsection pf_res_computing Computing Resources -\subsubsection pf_tag_host <host> +@subsubsection pf_tag_host <host> An host is the computing resource on which an actor can execute. @@ -141,28 +141,28 @@ pstate | Double (Defaults to 0) | FIXME: Not yet documented. #### Examples #### -\code{.xml} +@code{.xml} -\endcode +@endcode -\anchor pf_host_dynamism +@anchor pf_host_dynamism ### Expressing dynamism ### SimGrid provides mechanisms to change a hosts' availability over -time, using the ``availability_file`` attribute to the ``\`` tag +time, using the ``availability_file`` attribute to the ``@`` tag and a separate text file whose syntax is exemplified below. #### Adding a trace file #### -\verbatim +@verbatim -\endverbatim +@endverbatim #### Example of "bob.trace" file #### @@ -176,17 +176,17 @@ PERIODICITY 1.0 Let us begin to explain this example by looking at line 2. (Line 1 will become clear soon). The first column describes points in time, in this case, time 0. The second column describes the relative amount of power this host is able to deliver (relative -to the maximum performance specified in the ``\`` tag). (Clearly, the +to the maximum performance specified in the ``@`` tag). (Clearly, the second column needs to contain values that are not smaller than 0 and not larger than 1). In this example, our host will deliver 500 Mflop/s at time 0, as 500 Mflop/s is the maximum performance of this host. At time 11.0, it will deliver half of its maximum performance, i.e., 250 Mflop/s until time 20.0 when it will -will start delivering 80\% of its power. In this example, this amounts to 400 Mflop/s. +will start delivering 80@% of its power. In this example, this amounts to 400 Mflop/s. Since the periodicity in line 1 was set to be 1.0, i.e., 1 timestep, this host will continue to provide 500 Mflop/s from time 21. From time 32 it will provide 250 MFlop/s and so on. -\subsubsection pf_tag_cluster <cluster> +@subsubsection pf_tag_cluster <cluster> ```` represents a machine-cluster. It is most commonly used when one wants to define many hosts and a network quickly. Technically, @@ -194,7 +194,7 @@ when one wants to define many hosts and a network quickly. Technically, view, a cluster is a network zone where some optimized routing is defined
. The default inner organization of the cluster is as follow: -\verbatim +@verbatim __________ | | | router | @@ -204,7 +204,7 @@ The default inner organization of the cluster is as follow: | | | ........ | | | | | c-0.me c-99.me -\endverbatim +@endverbatim Here, a set of hosts is defined. Each of them has a link to a central backbone (backbone is a link itself, as a link can @@ -215,18 +215,18 @@ SimGrid treats a cluster as a network zone containing all hosts: the router is t gateway for the cluster. There is an alternative organization, which is as follows: -\verbatim +@verbatim __________ | | | router | |__________| - / | \ - / | \ - l0 / l1| \l2 - / | \ - / | \ + / | @ + / | @ + l0 / l1| @l2 + / | @ + / | @ host0 host1 host2 -\endverbatim +@endverbatim The principle is the same, except that there is no backbone. This representation can be obtained easily: just do not set the bb_* attributes. @@ -238,19 +238,19 @@ id | yes | string | The identifier of the cluster. Facilitate prefix | yes | string | Each node of the cluster has to have a name. This name will be prefixed with this prefix. suffix | yes | string | Each node of the cluster will be suffixed with this suffix radical | yes | string | Regexp used to generate cluster nodes name. Syntax: "10-20" will give you 11 machines numbered from 10 to 20, "10-20;2" will give you 12 machines, one with the number 2, others numbered as before. The produced number is concatenated between prefix and suffix to form machine names. -speed | yes | int | Same as the ``speed`` attribute of the ``\`` tag. -core | no | int (default: 1) | Same as the ``core`` attribute of the ``\`` tag. -bw | yes | int | Bandwidth for the links between nodes and backbone (if any). See the \ref pf_tag_link "link section" for syntax/details. +speed | yes | int | Same as the ``speed`` attribute of the ``@`` tag. +core | no | int (default: 1) | Same as the ``core`` attribute of the ``@`` tag. +bw | yes | int | Bandwidth for the links between nodes and backbone (if any). See the @ref pf_tag_link "link section" for syntax/details. lat | yes | int | Latency for the links between nodes and backbone (if any). See link section for syntax/details. sharing_policy | no | string | Sharing policy for the links between nodes and backbone (if any). See link section for syntax/details. bb_bw | no | int | Bandwidth for backbone (if any). See link section for syntax/details. If bb_bw and bb_lat (see below) attributes are omitted, no backbone is created (alternative cluster architecture described before). bb_lat | no | int | Latency for backbone (if any). See link section for syntax/details. If bb_lat and bb_bw (see above) attributes are omitted, no backbone is created (alternative cluster architecture described before). bb_sharing_policy | no | string | Sharing policy for the backbone (if any). See link section for syntax/details. limiter_link | no | int | Bandwidth for limiter link (if any). This adds a specific link for each node, to set the maximum bandwidth reached when communicating in both directions at the same time. In theory this value should be 2*bw for splitduplex links, but in reality this might be less. This value will depend heavily on the communication model, and on the cluster's hardware, so no default value can be set, this has to be measured. More details can be obtained in "Toward Better Simulation of MPI Applications on Ethernet/TCP Networks" -loopback_bw | no | int | Bandwidth for loopback (if any). See link section for syntax/details. If loopback_bw and loopback_lat (see below) attributes are omitted, no loopback link is created and all intra-node communication will use the main network link of the node. Loopback link is a \ref pf_sharing_policy_fatpipe "\b FATPIPE". +loopback_bw | no | int | Bandwidth for loopback (if any). See link section for syntax/details. If loopback_bw and loopback_lat (see below) attributes are omitted, no loopback link is created and all intra-node communication will use the main network link of the node. Loopback link is a @ref pf_sharing_policy_fatpipe "@b FATPIPE". loopback_lat | no | int | Latency for loopback (if any). See link section for syntax/details. See loopback_bw for more info. -topology | no | FLAT\|TORUS\|FAT_TREE\|DRAGONFLY (default: FLAT) | Network topology to use. SimGrid currently supports FLAT (with or without backbone, as described before), TORUS , FAT_TREE, and DRAGONFLY attributes for this tag. -topo_parameters | no | string | Specific parameters to pass for the topology defined in the topology tag. For torus networks, comma-separated list of the number of nodes in each dimension of the torus. Please refer to the specific documentation for \ref simgrid::kernel::routing::FatTreeZone "FatTree NetZone", \ref simgrid::kernel::routing::DragonflyZone "Dragonfly NetZone". +topology | no | FLAT@|TORUS@|FAT_TREE@|DRAGONFLY (default: FLAT) | Network topology to use. SimGrid currently supports FLAT (with or without backbone, as described before), TORUS , FAT_TREE, and DRAGONFLY attributes for this tag. +topo_parameters | no | string | Specific parameters to pass for the topology defined in the topology tag. For torus networks, comma-separated list of the number of nodes in each dimension of the torus. Please refer to the specific documentation for @ref simgrid::kernel::routing::FatTreeZone "FatTree NetZone", @ref simgrid::kernel::routing::DragonflyZone "Dragonfly NetZone". the router name is defined as the resulting String in the following @@ -265,32 +265,32 @@ router_name = prefix + clusterId + "_router" + suffix; Consider the following two (and independent) uses of the ``cluster`` tag: -\verbatim +@verbatim -\endverbatim +@endverbatim The second example creates one router and 100 machines with the following names: -\verbatim +@verbatim c-my_cluster_2_router.me c-0.me c-1.me c-2.me ... c-99.me -\endverbatim +@endverbatim -\subsubsection pf_cabinet <cabinet> +@subsubsection pf_cabinet <cabinet> -\note +@note This tag is only available when the routing mode of the network zone is set to ``Cluster``. -The ``<cabinet />`` tag is, like the \ref pf_tag_cluster "<cluster>" tag, +The ``<cabinet />`` tag is, like the @ref pf_tag_cluster "<cluster>" tag, a meta-tag. This means that it is simply a shortcut for creating a set of (homogenous) hosts and links quickly; unsurprisingly, this tag was introduced to setup cabinets in data centers quickly. Unlike <cluster>, however, the <cabinet> assumes that you create the backbone @@ -304,21 +304,21 @@ id | yes | string | The identifier of the cabinet. Facilitate prefix | yes | string | Each node of the cabinet has to have a name. This name will be prefixed with this prefix. suffix | yes | string | Each node of the cabinet will be suffixed with this suffix radical | yes | string | Regexp used to generate cabinet nodes name. Syntax: "10-20" will give you 11 machines numbered from 10 to 20, "10-20;2" will give you 12 machines, one with the number 2, others numbered as before. The produced number is concatenated between prefix and suffix to form machine names. -speed | yes | int | Same as the ``speed`` attribute of the \ref pf_tag_host "<host>" tag. -bw | yes | int | Bandwidth for the links between nodes and backbone (if any). See the \ref pf_tag_link "link section" for syntax/details. -lat | yes | int | Latency for the links between nodes and backbone (if any). See the \ref pf_tag_link "link section" for syntax/details. +speed | yes | int | Same as the ``speed`` attribute of the @ref pf_tag_host "<host>" tag. +bw | yes | int | Bandwidth for the links between nodes and backbone (if any). See the @ref pf_tag_link "link section" for syntax/details. +lat | yes | int | Latency for the links between nodes and backbone (if any). See the @ref pf_tag_link "link section" for syntax/details. -\note +@note Please note that as of now, it is impossible to change attributes such as, amount of cores (always set to 1), the initial state of hosts/links - (always set to ON), the sharing policy of the links (always set to \ref pf_sharing_policy_splitduplex "SPLITDUPLEX"). + (always set to ON), the sharing policy of the links (always set to @ref pf_sharing_policy_splitduplex "SPLITDUPLEX"). #### Example #### The following example was taken from ``examples/platforms/meta_cluster.xml`` and shows how to use the cabinet tag. -\verbatim +@verbatim @@ -329,10 +329,10 @@ shows how to use the cabinet tag. -\endverbatim +@endverbatim -\note - Please note that you must specify the \ref pf_backbone "<backbone>" +@note + Please note that you must specify the @ref pf_backbone "<backbone>" tag by yourself; this is not done automatically and there are no checks that ensure this backbone was defined. @@ -340,16 +340,16 @@ The hosts generated in the above example are named host-1.cluster, host-2.cluste etc. -\subsubsection pf_peer <peer> (Vivaldi netzones only) +@subsubsection pf_peer <peer> (Vivaldi netzones only) This tag represents a peer, as in Peer-to-Peer (P2P) networks. This can only be used in Vivaldi NetZones. It creates the following resources to the NetZone: -\li A host -\li Two links: One for download and one for upload. This is +@li A host +@li Two links: One for download and one for upload. This is convenient to use and simulate stuff under the last mile model (e.g., ADSL peers). -\li It connects the two links to the host +@li It connects the two links to the host #### Attributes #### @@ -360,7 +360,7 @@ speed | yes | int | See the description of the ``host`` tag f bw_in | yes | int | Bandwidth of the private downstream link bw_out | yes | int | Bandwidth of the private upstream link coordinates | no | string | Coordinates of the gateway for this peer. Example value: 12.8 14.4 6.4 -sharing_policy | no | SHARED\|SPLITDUPLEX (default: SPLITDUPLEX) | Sharing policy for links. See link description for details. +sharing_policy | no | SHARED@|SPLITDUPLEX (default: SPLITDUPLEX) | Sharing policy for links. See link description for details. availability_file| no | string | Availability file for the peer. Same as host availability file. See host description for details. state_file | no | string | State file for the peer. Same as host state file. See host description for details. @@ -374,14 +374,14 @@ See the documentation of simgrid::kernel::routing::VivaldiZone for details on how the latency is computed from the coordinate, and on the the up and down bandwidth are used. -\subsection pf_ne Network equipments +@subsection pf_ne Network equipments There are two tags at all times available to represent network entities and several other tags that are available only in certain contexts. 1. ````: Represents a entity that has a limited bandwidth, a latency, and that can be shared according to TCP way to share this bandwidth. -\remark +@remark The concept of links in SimGrid may not be intuitive, as links are not limited to connecting (exactly) two entities; in fact, you can have more than two equipments connected to it. (In graph theoretical terms: A link in @@ -396,11 +396,11 @@ several other tags that are available only in certain contexts. 3. ````: This tag is only available when the containing network zone is used as a cluster (i.e., mode="Cluster") -\remark +@remark If you want to represent an entity like a switch, you must use ```` (see section). Routers are used - to run some routing algorithm and determine routes (see Section \ref pf_routing for details). + to run some routing algorithm and determine routes (see Section @ref pf_routing for details). -\subsubsection pf_router <router/> +@subsubsection pf_router <router/> As said before, router is used only to give some information for routing algorithms. So, it does not have any attributes except: @@ -410,15 +410,15 @@ for routing algorithms. So, it does not have any attributes except: Attribute name | Mandatory | Values | Description --------------- | --------- | ------ | ----------- id | yes | string | The identifier of the router to be used when referring to it. -coordinates | no | string | Must be provided when choosing the Vivaldi, coordinate-based routing model for the network zone the router belongs to. More details can be found in the Section \ref pf_P2P_tags. +coordinates | no | string | Must be provided when choosing the Vivaldi, coordinate-based routing model for the network zone the router belongs to. More details can be found in the Section @ref pf_P2P_tags. #### Example #### -\verbatim +@verbatim -\endverbatim +@endverbatim -\subsubsection pf_tag_link <link> +@subsubsection pf_tag_link <link> Network links can represent one-hop network connections. They are characterized by their id and their bandwidth; links can (but may not) be subject @@ -431,8 +431,8 @@ Attribute name | Mandatory | Values | Description id | yes | string | The identifier of the link to be used when referring to it. bandwidth | yes | int | Maximum bandwidth for this link, given in bytes/s latency | no | double (default: 0.0) | Latency for this link. -sharing_policy | no | \ref sharing_policy_shared "SHARED"\|\ref pf_sharing_policy_fatpipe "FATPIPE"\|\ref pf_sharing_policy_splitduplex "SPLITDUPLEX" (default: SHARED) | Sharing policy for the link. -state | no | ON\|OFF (default: ON) | Allows you to to turn this link on or off (working / not working) +sharing_policy | no | @ref sharing_policy_shared "SHARED"@|@ref pf_sharing_policy_fatpipe "FATPIPE"@|@ref pf_sharing_policy_splitduplex "SPLITDUPLEX" (default: SHARED) | Sharing policy for the link. +state | no | ON@|OFF (default: ON) | Allows you to to turn this link on or off (working / not working) bandwidth_file | no | string | Allows you to use a file as input for bandwidth. latency_file | no | string | Allows you to use a file as input for latency. state_file | no | string | Allows you to use a file as input for states. @@ -444,11 +444,11 @@ When using the latency attribute, you can specify the latency by using the scien notation or by using common abbreviations. For instance, the following three tags are equivalent: -\verbatim +@verbatim -\endverbatim +@endverbatim Here, the second tag uses "us", meaning "microseconds". Other shortcuts are: @@ -466,13 +466,13 @@ Picosecond | ps | 0.000000000001 = 10^(-12) #### Sharing policy #### -\anchor sharing_policy_shared -By default a network link is \b SHARED, i.e., if two or more data flows go +@anchor sharing_policy_shared +By default a network link is @b SHARED, i.e., if two or more data flows go through a link, the bandwidth is shared fairly among all data flows. This is similar to the sharing policy TCP uses. -\anchor pf_sharing_policy_fatpipe -On the other hand, if a link is defined as a \b FATPIPE, +@anchor pf_sharing_policy_fatpipe +On the other hand, if a link is defined as a @b FATPIPE, each flow going through this link will be provided with the complete bandwidth, i.e., no sharing occurs and the bandwidth is only limiting each flow individually. Please note that this is really on a per-flow basis, not only on a per-host basis! @@ -482,13 +482,13 @@ is ``number_of_flows*bandwidth``, with at most ``bandwidth`` being available per Using the FATPIPE mode allows to model backbones that won't affect performance (except latency). -\anchor pf_sharing_policy_splitduplex -The last mode available is \b SPLITDUPLEX. This means that SimGrid will +@anchor pf_sharing_policy_splitduplex +The last mode available is @b SPLITDUPLEX. This means that SimGrid will automatically generate two links (one carrying the suffix _UP and the other the suffix _DOWN) for each ```` tag. This models situations when the direction of traffic is important. -\remark +@remark Transfers from one side to the other will interact similarly as TCP when ACK returning packets circulate on the other direction. More discussion about it is available in the description of link_ctn description. @@ -497,31 +497,31 @@ In other words: The SHARED policy defines a physical limit for the bandwidth. The FATPIPE mode defines a limit for each application, with no upper total limit. -\remark +@remark Tip: By using the FATPIPE mode, you can model big backbones that won't affect performance (except latency). #### Example #### -\verbatim +@verbatim -\endverbatim +@endverbatim #### Expressing dynamism and failures #### Similar to hosts, it is possible to declare links whose state, bandwidth -or latency changes over time (see Section \ref pf_host_dynamism for details). +or latency changes over time (see Section @ref pf_host_dynamism for details). In the case of network links, the ``bandwidth`` and ``latency`` attributes are replaced by the ``bandwidth_file`` and ``latency_file`` attributes. The following XML snippet demonstrates how to use this feature in the platform file. The structure of the files "link1.bw" and "link1.lat" is shown below. -\verbatim +@verbatim -\endverbatim +@endverbatim -\note +@note Even if the syntax is the same, the semantic of bandwidth and latency trace files differs from that of host availability files. For bandwidth and latency, the corresponding files do not @@ -570,12 +570,12 @@ kicks in. It then loops back, starting at 100µs (the initial value) for one sec #### The ```` tag #### Similar to the ```` tag, a link may also contain the ```` tag; see the host -documentation (Section \ref pf_tag_host) for an example. +documentation (Section @ref pf_tag_host) for an example. -\subsubsection pf_backbone +@subsubsection pf_backbone -\note +@note This tag is only available when the containing network zone uses the "Cluster" routing mode! Using this tag, you can designate an already existing link to be a backbone. @@ -584,9 +584,9 @@ Attribute name | Mandatory | Values | Description --------------- | --------- | ------ | ----------- id | yes | string | Name of the link that is supposed to act as a backbone. -\subsection pf_storage Storage +@subsection pf_storage Storage -\note +@note This is a prototype version that should evolve quickly, hence this is just some doc valuable only at the time of writing. This section describes the storage management under SimGrid ; nowadays @@ -595,14 +595,14 @@ id | yes | string | Name of the link that is supposed to act @ref msg_file ; access functions are organized as a POSIX-like interface. -\subsubsection pf_sto_conc Storage - Main Concepts +@subsubsection pf_sto_conc Storage - Main Concepts The storage facilities implemented in SimGrid help to model (and account for) storage devices, such as tapes, hard-drives, CD or DVD devices etc. A typical situation is depicted in the figure below: -\image html ./webcruft/storage_sample_scenario.png -\image latex ./webcruft/storage_sample_scenario.png "storage_sample_scenario" width=\textwidth +@image html ./webcruft/storage_sample_scenario.png +@image latex ./webcruft/storage_sample_scenario.png "storage_sample_scenario" width=@textwidth In this figure, two hosts called Bob and Alice are interconnected via a network and each host is physically attached to a disk; it is not only possible for each host to @@ -615,24 +615,24 @@ that include storage facilities: Entity name | Description --------------- | ----------- -\ref pf_storage_entity_storage_type "storage_type" | Defines a template for a particular kind of storage (such as a hard-drive) and specifies important features of the storage, such as capacity, performance (read/write), contents, ... Different models of hard-drives use different storage_types (because the difference between an SSD and an HDD does matter), as they differ in some specifications (e.g., different sizes or read/write performance). -\ref pf_tag_storage "storage" | Defines an actual instance of a storage type (disk, RAM, ...); uses a ``storage_type`` template (see line above) so that you don't need to re-specify the same details over and over again. -\ref pf_tag_mount "mount" | Must be wrapped by a \ref pf_tag_host tag; declares which storage(s) this host has mounted and where (i.e., the mountpoint). +@ref pf_storage_entity_storage_type "storage_type" | Defines a template for a particular kind of storage (such as a hard-drive) and specifies important features of the storage, such as capacity, performance (read/write), contents, ... Different models of hard-drives use different storage_types (because the difference between an SSD and an HDD does matter), as they differ in some specifications (e.g., different sizes or read/write performance). +@ref pf_tag_storage "storage" | Defines an actual instance of a storage type (disk, RAM, ...); uses a ``storage_type`` template (see line above) so that you don't need to re-specify the same details over and over again. +@ref pf_tag_mount "mount" | Must be wrapped by a @ref pf_tag_host tag; declares which storage(s) this host has mounted and where (i.e., the mountpoint). -\anchor pf_storage_content_file +@anchor pf_storage_content_file ### %Storage Content File ### In order to assess exactly how much time is spent reading from the storage, SimGrid needs to know what is stored on the storage device (identified by distinct (file-)name, like in a file system) and what size this content has. -\note +@note The content file is never changed by the simulation; it is parsed once per simulation and kept in memory afterwards. When the content of the storage changes, only the internal SimGrid data structures change. -\anchor pf_storage_content_file_structure +@anchor pf_storage_content_file_structure #### Structure of a %Storage Content File #### Here is an excerpt from two storage content file; if you want to see the whole file, check @@ -642,7 +642,7 @@ SimGrid source code. SimGrid essentially supports two different formats: UNIX-style filepaths should follow the well known format: -\verbatim +@verbatim /lib/libsimgrid.so.3.6.2 12710497 /bin/smpicc 918 /bin/smpirun 7292 @@ -652,50 +652,50 @@ follow the well known format: /bin/simgrid-colorizer 2993 /bin/smpiff 820 /bin/tesh 356434 -\endverbatim +@endverbatim Windows filepaths, unsurprisingly, use the windows style: -\verbatim -\Windows\avastSS.scr 41664 -\Windows\bfsvc.exe 75264 -\Windows\bootstat.dat 67584 -\Windows\CoreSingleLanguage.xml 31497 -\Windows\csup.txt 12 -\Windows\dchcfg64.exe 335464 -\Windows\dcmdev64.exe 93288 -\endverbatim - -\note +@verbatim +@Windows@avastSS.scr 41664 +@Windows@bfsvc.exe 75264 +@Windows@bootstat.dat 67584 +@Windows@CoreSingleLanguage.xml 31497 +@Windows@csup.txt 12 +@Windows@dchcfg64.exe 335464 +@Windows@dcmdev64.exe 93288 +@endverbatim + +@note The different file formats come at a cost; in version 3.12 (and most likely in later versions, too), copying files from windows-style storages to unix-style storages (and vice versa) is not supported. -\anchor pf_storage_content_file_create +@anchor pf_storage_content_file_create #### Generate a %Storage Content File #### If you want to generate a storage content file based on your own filesystem (or at least a filesystem you have access to), try running this command (works only on unix systems): -\verbatim -find . -type f -exec ls -1s --block=1 {} \; 2>/dev/null | awk '{ print $2 " " $1}' > ./content.txt -\endverbatim +@verbatim +find . -type f -exec ls -1s --block=1 {} @; 2>/dev/null | awk '{ print $2 " " $1}' > ./content.txt +@endverbatim -\subsubsection pf_storage_entities The Storage Entities +@subsubsection pf_storage_entities The Storage Entities These are the entities that you can use in your platform files to include -storage in your model. See also the list of our \ref pf_storage_example_files "example files"; +storage in your model. See also the list of our @ref pf_storage_example_files "example files"; these might also help you to get started. -\anchor pf_storage_entity_storage_type -#### \ #### +@anchor pf_storage_entity_storage_type +#### @ #### Attribute name | Mandatory | Values | Description --------------- | --------- | ------ | ----------- id | yes | string | Identifier of this storage_type; used when referring to it model | no | string | In the future, this will allow to change the performance model to use size | yes | string | Specifies the amount of available storage space; you can specify storage like "500GiB" or "500GB" if you want. (TODO add a link to all the available abbreviations) -content | yes | string | Path to a \ref pf_storage_content_file "Storage Content File" on your system. This file must exist. +content | yes | string | Path to a @ref pf_storage_content_file "Storage Content File" on your system. This file must exist. This tag must contain some predefined model properties, specified via the <model_prop> tag. Here is a list, see below for an example: @@ -705,41 +705,41 @@ Property id | Mandatory | Values | Description Bwrite | yes | string | Bandwidth for write access; in B/s (but you can also specify e.g. "30MBps") Bread | yes | string | Bandwidth for read access; in B/s (but you can also specify e.g. "30MBps") -\note +@note A storage_type can also contain the <prop> tag. The <prop> tag allows you to associate additional information to this <storage_type> and follows the attribute/value schema; see the example below. You may want to use it to give information to the tool you use for rendering your simulation, for example. Here is a complete example for the ``storage_type`` tag: -\verbatim +@verbatim -\endverbatim +@endverbatim @subsubsection pf_tag_storage <storage> Attributes | Mandatory | Values | Description -------------- | --------- | ------ | ----------- id | yes | string | Identifier of this ``storage``; used when referring to it -typeId | yes | string | Here you need to refer to an already existing \ref pf_storage_entity_storage_type "\"; the storage entity defined by this tag will then inherit the properties defined there. -attach | yes | string | Name of a host (see Section \ref pf_tag_host) to which this storage is physically attached to (e.g., a hard drive in a computer) -content | no | string | When specified, overwrites the content attribute of \ref pf_storage_entity_storage_type "\" +typeId | yes | string | Here you need to refer to an already existing @ref pf_storage_entity_storage_type "@"; the storage entity defined by this tag will then inherit the properties defined there. +attach | yes | string | Name of a host (see Section @ref pf_tag_host) to which this storage is physically attached to (e.g., a hard drive in a computer) +content | no | string | When specified, overwrites the content attribute of @ref pf_storage_entity_storage_type "@" Here are two examples: -\verbatim +@verbatim -\endverbatim +@endverbatim The first example is straightforward: A disk is defined and called "Disk1"; it is -of type "single_HDD" (shown as an example of \ref pf_storage_entity_storage_type "\" above) and attached +of type "single_HDD" (shown as an example of @ref pf_storage_entity_storage_type "@" above) and attached to a host called "bob" (the definition of this host is omitted here). The second storage is called "Disk2", is still of the same type as Disk1 but @@ -747,19 +747,19 @@ now specifies a new content file (so the contents will be different from Disk1) and the filesystem uses the windows style; finally, it is attached to a second host, called alice (which is again not defined here). -\subsubsection pf_tag_mount <mount> +@subsubsection pf_tag_mount <mount> | Attribute | Mandatory | Values | Description | | ----------- | ----------- | -------- | ------------- | -| id | yes | string | Refers to a \ref pf_tag_storage "<storage>" entity that will be mounted on that computer | +| id | yes | string | Refers to a @ref pf_tag_storage "<storage>" entity that will be mounted on that computer | | name | yes | string | Path/location to/of the logical reference (mount point) of this disk -This tag must be enclosed by a \ref pf_tag_host tag. It then specifies where the mountpoint of a given storage device (defined by the ``id`` attribute) +This tag must be enclosed by a @ref pf_tag_host tag. It then specifies where the mountpoint of a given storage device (defined by the ``id`` attribute) is; this location is specified by the ``name`` attribute. Here is a simple example, taken from the file ``examples/platform/storage.xml``: -\verbatim +@verbatim @@ -780,11 +780,11 @@ Here is a simple example, taken from the file ``examples/platform/storage.xml``: -\endverbatim +@endverbatim This example is quite interesting, as the same device, called "Disk2", is mounted by two hosts at the same time! Note, however, that the host called ``alice`` is actually -attached to this storage, as can be seen in the \ref pf_tag_storage "<storage>" +attached to this storage, as can be seen in the @ref pf_tag_storage "<storage>" tag. This means that ``denise`` must access this storage through the network, but SimGrid automatically takes care of that for you. @@ -792,7 +792,7 @@ Furthermore, this example shows that ``denise`` has mounted two storages with di filesystem types (unix and windows). In general, a host can mount as many storage devices as required. -\note +@note Again, the difference between ``attach`` and ``mount`` is simply that an attached storage is always physically inside (or connected to) that machine; for instance, a USB stick is attached to one and only one machine (where it's plugged-in) @@ -800,9 +800,9 @@ required. ###### Example files ##### -\verbinclude example_filelist_xmltag_mount +@verbinclude example_filelist_xmltag_mount -\subsubsection pf_storage_example_files Example files +@subsubsection pf_storage_example_files Example files Several examples were already discussed above; if you're interested in full examples, check the the following platforms: @@ -813,7 +813,7 @@ check the the following platforms: If you're looking for some examplary C code, you may find the source code available in the directory ``examples/msg/io/`` useful. -\subsubsection pf_storage_examples_modelling Modelling different situations +@subsubsection pf_storage_examples_modelling Modelling different situations The storage functionality of SimGrid is type-agnostic, that is, the implementation does not presume any type of storage, such as HDDs/SSDs, RAM, @@ -827,33 +827,33 @@ common scenario would be the access of remote RAM. How can this be achieved in SimGrid? Let's assume we have a setup where three hosts (HostA, HostB, HostC) need to access remote RAM: -\verbatim +@verbatim Host A / RAM -- Host B - \ + @ Host C -\endverbatim +@endverbatim An easy way to model this scenario is to setup and define the RAM via the -\ref pf_tag_storage "storage" and \ref pf_storage_entity_storage_type "storage type" +@ref pf_tag_storage "storage" and @ref pf_storage_entity_storage_type "storage type" entities and attach it to a remote dummy host; then, every host can have their own links to this host (modelling for instance certain scenarios, such as PCIe ...) -\verbatim +@verbatim Host A / RAM - Dummy -- Host B - \ + @ Host C -\endverbatim +@endverbatim Now, if read from this storage, the host that mounts this storage communicates to the dummy host which reads from RAM and sends the information back. -\section pf_routing Routing +@section pf_routing Routing To achieve high performance, the routing tables used within SimGrid are static. This means that routing between two nodes is calculated once @@ -871,7 +871,7 @@ are all calculating shortest paths. They do require some time to converge, but eventually, when the routing tables have stabilized, your packets will follow the shortest paths. -\subsection pf_tag_zone <zone> +@subsection pf_tag_zone <zone> Before SimGrid v3.16, networking zones used to be called Autonomous Systems, but this was misleading as zones may include other zones in a @@ -881,39 +881,39 @@ zones, please report this as a bug. Attribute | Value | Description ----------- | ------------------------------------------------- | ---------------------------------------------- id | String (mandatory) | The identifier of this zone (must be unique) -routing | One of the existing routing algorithm (mandatory) | See Section \ref pf_rm for details. +routing | One of the existing routing algorithm (mandatory) | See Section @ref pf_rm for details. Example: -\code +@code -\endcode +@endcode In this example, zone0 contains two hosts (host1 and host2). The route between the hosts goes through link1. -\subsection pf_rm Routing models +@subsection pf_rm Routing models For each network zone, you must define explicitly which routing model will be used. There are 3 different categories for routing models: -1. \ref pf_routing_model_shortest_path "Shortest-path" based models: SimGrid calculates shortest +1. @ref pf_routing_model_shortest_path "Shortest-path" based models: SimGrid calculates shortest paths and manages them. Behaves more or less like most real life routing mechanisms. -2. \ref pf_routing_model_manual "Manually-entered" route models: you have to define all routes +2. @ref pf_routing_model_manual "Manually-entered" route models: you have to define all routes manually in the platform description file; this can become tedious very quickly, as it is very verbose. Consistent with some manually managed real life routing. -3. \ref pf_routing_model_simple "Simple/fast models": those models offer fast, low memory routing +3. @ref pf_routing_model_simple "Simple/fast models": those models offer fast, low memory routing algorithms. You should consider to use this type of model if you can make some assumptions about your network zone. Routing in this case is more or less ignored. -\subsubsection pf_raf The router affair +@subsubsection pf_raf The router affair Using routers becomes mandatory when using shortest-path based models or when using the bindings to the ns-3 packet-level @@ -940,26 +940,26 @@ To express this topological information, a route has to be defined in order to declare which link is connected to a router. -\subsubsection pf_routing_model_shortest_path Shortest-path based models +@subsubsection pf_routing_model_shortest_path Shortest-path based models The following table shows all the models that compute routes using shortest-paths algorithms are currently available in SimGrid. More detail on how -to choose the best routing model is given in the Section called \"\ref pf_routing_howto_choose_wisely\". +to choose the best routing model is given in the Section called @"@ref pf_routing_howto_choose_wisely@". | Name | Description | | --------------------------------------------------- | -------------------------------------------------------------------------- | -| \ref pf_routing_model_floyd "Floyd" | Floyd routing data. Pre-calculates all routes once | -| \ref pf_routing_model_dijkstra "Dijkstra" | Dijkstra routing data. Calculates routes only when needed | -| \ref pf_routing_model_dijkstracache "DijkstraCache" | Dijkstra routing data. Handles some cache for already calculated routes. | +| @ref pf_routing_model_floyd "Floyd" | Floyd routing data. Pre-calculates all routes once | +| @ref pf_routing_model_dijkstra "Dijkstra" | Dijkstra routing data. Calculates routes only when needed | +| @ref pf_routing_model_dijkstracache "DijkstraCache" | Dijkstra routing data. Handles some cache for already calculated routes. | All those shortest-path models are instanciated in the same way and are completely interchangeable. Here are some examples: -\anchor pf_routing_model_floyd +@anchor pf_routing_model_floyd ### Floyd ### Floyd example: -\verbatim +@verbatim -\endverbatim +@endverbatim zoneroute given at the end gives a topological information: link1 is between router1 and host1. @@ -989,9 +989,9 @@ between router1 and host1. This is an automatically generated list of example files that use the Floyd routing model (the path is given relative to SimGrid's source directory) -\verbinclude example_filelist_routing_floyd +@verbinclude example_filelist_routing_floyd -\anchor pf_routing_model_dijkstra +@anchor pf_routing_model_dijkstra ### Dijkstra ### #### Example platform files #### @@ -999,10 +999,10 @@ routing model (the path is given relative to SimGrid's source directory) This is an automatically generated list of example files that use the Dijkstra routing model (the path is given relative to SimGrid's source directory) -\verbinclude example_filelist_routing_dijkstra +@verbinclude example_filelist_routing_dijkstra Dijkstra example: -\verbatim +@verbatim @@ -1019,18 +1019,18 @@ Dijkstra example: -\endverbatim +@endverbatim -\anchor pf_routing_model_dijkstracache +@anchor pf_routing_model_dijkstracache ### DijkstraCache ### DijkstraCache example: -\verbatim +@verbatim ... (platform unchanged compared to upper example) -\endverbatim +@endverbatim #### Example platform files #### @@ -1040,85 +1040,85 @@ routing model (the path is given relative to SimGrid's source directory): Editor's note: At the time of writing, no platform file used this routing model - so if there are no example files listed here, this is likely to be correct. -\verbinclude example_filelist_routing_dijkstra_cache +@verbinclude example_filelist_routing_dijkstra_cache -\subsubsection pf_routing_model_manual Manually-entered route models +@subsubsection pf_routing_model_manual Manually-entered route models | Name | Description | | ---------------------------------- | ------------------------------------------------------------------------------ | -| \ref pf_routing_model_full "Full" | You have to enter all necessary routers manually; that is, every single route. This may consume a lot of memory when the XML is parsed and might be tedious to write; i.e., this is only recommended (if at all) for small platforms. | +| @ref pf_routing_model_full "Full" | You have to enter all necessary routers manually; that is, every single route. This may consume a lot of memory when the XML is parsed and might be tedious to write; i.e., this is only recommended (if at all) for small platforms. | -\anchor pf_routing_model_full +@anchor pf_routing_model_full ### Full ### Full example: -\verbatim +@verbatim -\endverbatim +@endverbatim #### Example platform files #### This is an automatically generated list of example files that use the Full routing model (the path is given relative to SimGrid's source directory): -\verbinclude example_filelist_routing_full +@verbinclude example_filelist_routing_full -\subsubsection pf_routing_model_simple Simple/fast models +@subsubsection pf_routing_model_simple Simple/fast models | Name | Description | | ---------------------------------------- | ------------------------------------------------------------------------------ | -| \ref pf_routing_model_cluster "Cluster" | This is specific to the \ref pf_tag_cluster "<cluster/>" tag and should not be used by the user, as several assumptions are made. | -| \ref pf_routing_model_none "None" | No routing at all. Unless you know what you're doing, avoid using this mode in combination with a non-constant network model. | -| \ref pf_routing_model_vivaldi "Vivaldi" | Perfect when you want to use coordinates. Also see the corresponding \ref pf_P2P_tags "P2P section" below. | +| @ref pf_routing_model_cluster "Cluster" | This is specific to the @ref pf_tag_cluster "<cluster/>" tag and should not be used by the user, as several assumptions are made. | +| @ref pf_routing_model_none "None" | No routing at all. Unless you know what you're doing, avoid using this mode in combination with a non-constant network model. | +| @ref pf_routing_model_vivaldi "Vivaldi" | Perfect when you want to use coordinates. Also see the corresponding @ref pf_P2P_tags "P2P section" below. | -\anchor pf_routing_model_cluster +@anchor pf_routing_model_cluster ### Cluster ### -\note - In this mode, the \ref pf_cabinet "<cabinet/>" tag is available. +@note + In this mode, the @ref pf_cabinet "<cabinet/>" tag is available. #### Example platform files #### This is an automatically generated list of example files that use the Cluster routing model (the path is given relative to SimGrid's source directory): -\verbinclude example_filelist_routing_cluster +@verbinclude example_filelist_routing_cluster -\anchor pf_routing_model_none +@anchor pf_routing_model_none ### None ### This model does exactly what it's name advertises: Nothing. There is no routing available within this model and if you try to communicate within the zone that uses this model, SimGrid will fail unless you have explicitly activated the -\ref options_model_select_network_constant "Constant Network Model" (this model charges +@ref options_model_select_network_constant "Constant Network Model" (this model charges the same for every single communication). It should -be noted, however, that you can still attach an \ref pf_tag_zoneroute "ZoneRoute", +be noted, however, that you can still attach an @ref pf_tag_zoneroute "ZoneRoute", as is demonstrated in the example below: -\verbinclude platforms/cluster_and_one_host.xml +@verbinclude platforms/cluster_and_one_host.xml #### Example platform files #### This is an automatically generated list of example files that use the None routing model (the path is given relative to SimGrid's source directory): -\verbinclude example_filelist_routing_none +@verbinclude example_filelist_routing_none -\anchor pf_routing_model_vivaldi +@anchor pf_routing_model_vivaldi ### Vivaldi ### For more information on how to use the [Vivaldi Coordinates](https://en.wikipedia.org/wiki/Vivaldi_coordinates), -see also Section \ref pf_P2P_tags "P2P tags". +see also Section @ref pf_P2P_tags "P2P tags". Note that it is possible to combine the Vivaldi routing model with other routing models; -an example can be found in the file \c examples/platforms/cloud.xml. This +an example can be found in the file @c examples/platforms/cloud.xml. This examples models a NetZone using Vivaldi that contains other NetZones that use different routing models. @@ -1127,76 +1127,76 @@ routing models. This is an automatically generated list of example files that use the None routing model (the path is given relative to SimGrid's source directory): -\verbinclude example_filelist_routing_vivaldi +@verbinclude example_filelist_routing_vivaldi -\subsection ps_dec Defining routes +@subsection ps_dec Defining routes There are currently four different ways to define routes: | Name | Description | | ------------------------------------------------- | ----------------------------------------------------------------------------------- | -| \ref pf_tag_route "route" | Used to define route between host/router | -| \ref pf_tag_zoneroute "zoneRoute" | Used to define route between different zones | -| \ref pf_tag_bypassroute "bypassRoute" | Used to supersede normal routes as calculated by the network model between host/router; e.g., can be used to use a route that is not the shortest path for any of the shortest-path routing models. | -| \ref pf_tag_bypassasroute "bypassZoneRoute" | Used in the same way as bypassRoute, but for zones | +| @ref pf_tag_route "route" | Used to define route between host/router | +| @ref pf_tag_zoneroute "zoneRoute" | Used to define route between different zones | +| @ref pf_tag_bypassroute "bypassRoute" | Used to supersede normal routes as calculated by the network model between host/router; e.g., can be used to use a route that is not the shortest path for any of the shortest-path routing models. | +| @ref pf_tag_bypassasroute "bypassZoneRoute" | Used in the same way as bypassRoute, but for zones | Basically all those tags will contain an (ordered) list of references to link that compose the route you want to define. Consider the example below: -\verbatim +@verbatim -\endverbatim +@endverbatim The route here from host Alice to Bob will be first link1, then link2, -and finally link3. What about the reverse route? \ref pf_tag_route "Route" and -\ref pf_tag_zoneroute "zoneroute" have an optional attribute \c symmetrical, that can -be either \c YES or \c NO. \c YES means that the reverse route is the same -route in the inverse order, and is set to \c YES by default. Note that +and finally link3. What about the reverse route? @ref pf_tag_route "Route" and +@ref pf_tag_zoneroute "zoneroute" have an optional attribute @c symmetrical, that can +be either @c YES or @c NO. @c YES means that the reverse route is the same +route in the inverse order, and is set to @c YES by default. Note that this is not the case for bypass*Route, as it is more probable that you want to bypass only one default route. -For an \ref pf_tag_zoneroute "zoneroute", things are just slightly more complicated, as you have +For an @ref pf_tag_zoneroute "zoneroute", things are just slightly more complicated, as you have to give the id of the gateway which is inside the zone you want to access ... So it looks like this: -\verbatim +@verbatim -\endverbatim +@endverbatim gw == gateway, so when any message are trying to go from zone1 to zone2, it means that it must pass through router1 to get out of the zone, then pass through link1, and get into zone2 by being received by router2. router1 must belong to zone1 and router2 must belong to zone2. -\subsubsection pf_tag_linkctn <link_ctn> +@subsubsection pf_tag_linkctn <link_ctn> This entity has only one purpose: Refer to an already existing -\ref pf_tag_link "<link/>" when defining a route, i.e., it -can only occur as a child of \ref pf_tag_route "<route/>" +@ref pf_tag_link "<link/>" when defining a route, i.e., it +can only occur as a child of @ref pf_tag_route "<route/>" | Attribute name | Mandatory | Values | Description | | --------------- | --------- | ------ | ----------- | | id | yes | String | The identifier of the link that should be added to the route. | -| direction | maybe | UP\|DOWN | If the link referenced by \c id has been declared as \ref pf_sharing_policy_splitduplex "SPLITDUPLEX", this indicates which direction the route traverses through this link: UP or DOWN. If you don't use SPLITDUPLEX, do not use this attribute or SimGrid will not find the right link. +| direction | maybe | UP@|DOWN | If the link referenced by @c id has been declared as @ref pf_sharing_policy_splitduplex "SPLITDUPLEX", this indicates which direction the route traverses through this link: UP or DOWN. If you don't use SPLITDUPLEX, do not use this attribute or SimGrid will not find the right link. #### Example Files #### -This is an automatically generated list of example files that use the \c <link_ctn/> +This is an automatically generated list of example files that use the @c <link_ctn/> entity (the path is given relative to SimGrid's source directory): -\verbinclude example_filelist_xmltag_linkctn +@verbinclude example_filelist_xmltag_linkctn -\subsubsection pf_tag_zoneroute <zoneRoute> +@subsubsection pf_tag_zoneroute <zoneRoute> The purpose of this entity is to define a route between two NetZones. Recall that all zones form a tree, so to connect two @@ -1205,26 +1205,26 @@ and destination zones, along with the gateway in each zone (ie, the point to reach within that zone to reach the netzone), and the list of links in the ancestor zone to go from one zone to another. -So, to go from an host \c src_host that is within zone \c src, to an -host \c dst_host that is within \c dst, you need to: +So, to go from an host @c src_host that is within zone @c src, to an +host @c dst_host that is within @c dst, you need to: - - move within zone \c src, from \c src_host to the specified \c gw_src; + - move within zone @c src, from @c src_host to the specified @c gw_src; - traverse all links specified by the zoneRoute (they are supposed to be within the common ancestor); - - move within zone \c dst, from \c gw_dst to \c dst_host. + - move within zone @c dst, from @c gw_dst to @c dst_host. #### Attributes #### | Attribute name | Mandatory | Values | Description | | --------------- | --------- | ------ | ----------- | | src | yes | String | The identifier of the source zone | -| dst | yes | String | See the \c src attribute | -| gw_src | yes | String | The gateway that will be used within the src zone; this can be any \ref pf_tag_host "Host" or \ref pf_router "Router" defined within the src zone. | -| gw_dst | yes | String | Same as \c gw_src, but with the dst zone instead. | -| symmetrical | no | YES\|NO (Default: YES) | If this route is symmetric, the opposite route (from dst to src) will also be declared implicitly. | +| dst | yes | String | See the @c src attribute | +| gw_src | yes | String | The gateway that will be used within the src zone; this can be any @ref pf_tag_host "Host" or @ref pf_router "Router" defined within the src zone. | +| gw_dst | yes | String | Same as @c gw_src, but with the dst zone instead. | +| symmetrical | no | YES@|NO (Default: YES) | If this route is symmetric, the opposite route (from dst to src) will also be declared implicitly. | #### Example #### -\verbatim +@verbatim -\endverbatim +@endverbatim -\subsubsection pf_tag_route <route> +@subsubsection pf_tag_route <route> The principle is the same as for -\ref pf_tag_zoneroute "ZoneRoute": The route contains a list of links that -provide a path from \c src to \c dst. Here, \c src and \c dst can both be either a -\ref pf_tag_host "host" or \ref pf_router "router". This is mostly useful for the -\ref pf_routing_model_full "Full routing model" as well as for the -\ref pf_routing_model_shortest_path "shortest-paths" based models (as they require +@ref pf_tag_zoneroute "ZoneRoute": The route contains a list of links that +provide a path from @c src to @c dst. Here, @c src and @c dst can both be either a +@ref pf_tag_host "host" or @ref pf_router "router". This is mostly useful for the +@ref pf_routing_model_full "Full routing model" as well as for the +@ref pf_routing_model_shortest_path "shortest-paths" based models (as they require topological information). @@ -1264,31 +1264,31 @@ topological information). | --------------- | --------- | ---------------------- | ----------- | | src | yes | String | The value given to the source's "id" attribute | | dst | yes | String | The value given to the destination's "id" attribute. | -| symmetrical | no | YES\| NO (Default: YES) | If this route is symmetric, the opposite route (from dst to src) will also be declared implicitly. | +| symmetrical | no | YES@| NO (Default: YES) | If this route is symmetric, the opposite route (from dst to src) will also be declared implicitly. | #### Examples #### -A route in the \ref pf_routing_model_full "Full routing model" could look like this: -\verbatim +A route in the @ref pf_routing_model_full "Full routing model" could look like this: +@verbatim -\endverbatim +@endverbatim -A route in the \ref pf_routing_model_shortest_path "Shortest-Path routing model" could look like this: -\verbatim +A route in the @ref pf_routing_model_shortest_path "Shortest-Path routing model" could look like this: +@verbatim -\endverbatim -\note +@endverbatim +@note You must only have one link in your routes when you're using them to provide topological information, as the routes here are simply the edges of the (network-)graph and the employed algorithms need to know which edge connects which pair of entities. -\subsubsection pf_tag_bypassasroute bypasszoneroute +@subsubsection pf_tag_bypassasroute bypasszoneroute As said before, once you choose a model, it (most likely; the constant network model, for example, doesn't) calculates routes for you. But maybe you want to @@ -1308,24 +1308,24 @@ list of links that are in the path between src and dst. | dst | yes | String | The value given to the destination zone's "id" attribute. | | gw_src | yes | String | The value given to the source gateway's "id" attribute; this can be any host or router within the src zone | | gw_dst | yes | String | The value given to the destination gateway's "id" attribute; this can be any host or router within the dst zone| -| symmetrical | no | YES\| NO (Default: YES) | If this route is symmetric, the opposite route (from dst to src) will also be declared implicitly. | +| symmetrical | no | YES@| NO (Default: YES) | If this route is symmetric, the opposite route (from dst to src) will also be declared implicitly. | #### Example #### -\verbatim +@verbatim -\endverbatim +@endverbatim -This example shows that link \c link_tmp (definition not displayed here) directly -connects the router \c my_cluster_1_router in the source cluster to the router -\c my_cluster_2_router in the destination router. Additionally, as the \c symmetrical +This example shows that link @c link_tmp (definition not displayed here) directly +connects the router @c my_cluster_1_router in the source cluster to the router +@c my_cluster_2_router in the destination router. Additionally, as the @c symmetrical attribute was not given, this route is presumed to be symmetrical. -\subsubsection pf_tag_bypassroute bypassRoute +@subsubsection pf_tag_bypassroute bypassRoute As said before, once you choose a model, it (most likely; the constant network model, for example, doesn't) calculates routes for you. But maybe you want to @@ -1342,28 +1342,28 @@ links that are in the path between src and dst. | --------------- | --------- | ---------------------- | ----------- | | src | yes | String | The value given to the source zone's "id" attribute | | dst | yes | String | The value given to the destination zone's "id" attribute. | -| symmetrical | no | YES \| NO (Default: YES) | If this route is symmetric, the opposite route (from dst to src) will also be declared implicitly. | +| symmetrical | no | YES @| NO (Default: YES) | If this route is symmetric, the opposite route (from dst to src) will also be declared implicitly. | #### Examples #### -\verbatim +@verbatim -\endverbatim +@endverbatim -This example shows that link \c link_tmp (definition not displayed here) directly -connects host \c host_1 to host \c host_2. Additionally, as the \c symmetrical +This example shows that link @c link_tmp (definition not displayed here) directly +connects host @c host_1 to host @c host_2. Additionally, as the @c symmetrical attribute was not given, this route is presumed to be symmetrical. -\subsection pb_baroex Basic Routing Example +@subsection pb_baroex Basic Routing Example Let's say you have an zone named zone_Big that contains two other zone, zone_1 and zone_2. If you want to make a host (h1) from zone_1 with another one (h2) from zone_2 then you'll have to proceed as follows: -\li First, you have to ensure that a route is defined from h1 to the +@li First, you have to ensure that a route is defined from h1 to the zone_1's exit gateway and from h2 to zone_2's exit gateway. -\li Then, you'll have to define a route between zone_1 to zone_2. As those +@li Then, you'll have to define a route between zone_1 to zone_2. As those zone are both resources belonging to zone_Big, then it has to be done at zone_big level. To define such a route, you have to give the source zone (zone_1), the destination zone (zone_2), and their respective @@ -1374,8 +1374,8 @@ and zone_2. If you want to make a host (h1) from zone_1 with another one this route will be computed automatically. As said before, there are mainly 2 tags for routing: -\li zoneroute: to define routes between two zone -\li route: to define routes between two host/router +@li zoneroute: to define routes between two zone +@li route: to define routes between two host/router As we are dealing with routes between zone, it means that those we'll have some definition at zone_Big level. Let consider zone_1 contains 1 @@ -1389,7 +1389,7 @@ we're using some shortest path algorithms to route into zone_2, we'll then have to define some route to gives some topological information to SimGrid. Here is a file doing it all: -\verbatim +@verbatim @@ -1423,17 +1423,17 @@ information to SimGrid. Here is a file doing it all: -\endverbatim +@endverbatim -\section pf_other Other tags +@section pf_other Other tags -The following tags can be used inside a \ tag even if they are not +The following tags can be used inside a @ tag even if they are not directly describing the platform: - @ref pf_tag_config passes configuration options, e.g. to change the network model; - @ref pf_tag_prop gives user-defined properties to various elements -\subsection pf_tag_config <config> +@subsection pf_tag_config <config> Adding configuration flags into the platform file is particularly useful when the described platform is best used with specific @@ -1449,7 +1449,7 @@ Any such configuration must be given at the very top of the platform file. * **Example** -\verbatim +@verbatim @@ -1462,9 +1462,9 @@ Any such configuration must be given at the very top of the platform file. ... -\endverbatim +@endverbatim -\subsection pf_tag_prop <prop> +@subsection pf_tag_prop <prop> Defines a user-defined property, identified with a name and having a value. You can specify such properties to most kind of resources: @@ -1482,12 +1482,12 @@ or similar functions. #### Example #### -\code{.xml} +@code{.xml} -\endcode +@endcode -\subsection pf_trace trace and trace_connect +@subsection pf_trace trace and trace_connect Both tags are an alternate way to pass files containing information on availability, state etc. to an entity. (See also @ref howto_churn). @@ -1499,49 +1499,49 @@ you say that the file trace must be used by the entity. #### Example #### -\verbatim +@verbatim -\endverbatim +@endverbatim -\note - The order here is important. \c trace_connect must come - after the elements \c trace and \c host, as both the host - and the trace definition must be known when \c trace_connect - is parsed; the order of \c trace and \c host is arbitrary. +@note + The order here is important. @c trace_connect must come + after the elements @c trace and @c host, as both the host + and the trace definition must be known when @c trace_connect + is parsed; the order of @c trace and @c host is arbitrary. -#### \c trace attributes #### +#### @c trace attributes #### | Attribute name | Mandatory | Values | Description | | --------------- | --------- | ---------------------- | ----------- | -| id | yes | String | Identifier of this trace; this is the name you pass on to \c trace_connect. | +| id | yes | String | Identifier of this trace; this is the name you pass on to @c trace_connect. | | file | no | String | Filename of the file that contains the information - the path must follow the style of your OS. You can omit this, but then you must specifiy the values inside of <trace> and </trace> - see the example below. | -| trace_periodicity | yes | String | This is the same as for \ref pf_tag_host "hosts" (see there for details) | +| trace_periodicity | yes | String | This is the same as for @ref pf_tag_host "hosts" (see there for details) | Here is an example of trace when no file name is provided: -\verbatim +@verbatim 0.0 1.0 11.0 0.5 20.0 0.8 -\endverbatim +@endverbatim -#### \c trace_connect attributes #### +#### @c trace_connect attributes #### | Attribute name | Mandatory | Values | Description | | --------------- | --------- | ---------------------- | ----------- | -| kind | no | HOST_AVAIL\|POWER\|
LINK_AVAIL\|BANDWIDTH\|LATENCY (Default: HOST_AVAIL) | Describes the kind of trace. | -| trace | yes | String | Identifier of the referenced trace (specified of the trace's \c id attribute) | -| element | yes | String | The identifier of the referenced entity as given by its \c id attribute | +| kind | no | HOST_AVAIL@|POWER@|
LINK_AVAIL@|BANDWIDTH@|LATENCY (Default: HOST_AVAIL) | Describes the kind of trace. | +| trace | yes | String | Identifier of the referenced trace (specified of the trace's @c id attribute) | +| element | yes | String | The identifier of the referenced entity as given by its @c id attribute | -\section pf_hints Hints, tips and frequently requested features +@section pf_hints Hints, tips and frequently requested features Now you should know at least the syntax and be able to create a platform by your own. However, after having ourselves wrote some platforms, there @@ -1565,7 +1565,7 @@ for @ref pf_trace "trace_connect": ./two_hosts.xml:17: @endverbatim -\subsection pf_hint_generating How to generate different platform files? +@subsection pf_hint_generating How to generate different platform files? This is actually a good idea to search for a better platform file, that better fit the need of your study. To be honest, the provided @@ -1595,7 +1595,7 @@ This project is dormant since over 10 years (and you will have to update the generated platforms with bin/simgrid_update_xml to use them), but that's the best we have for this right now.... -\subsection pf_zone_h Zone Hierarchy +@subsection pf_zone_h Zone Hierarchy The network zone design allows SimGrid to go fast, because computing route is done only for the set of resources defined in the current zone. If you're using only a big zone containing all resource with no zone into it and you're @@ -1608,12 +1608,12 @@ describe a real life platform is to follow the zone described in reality, since this kind of trade-off works well for real life platforms. -\subsection pf_exit_zone Exit Zone: why and how +@subsection pf_exit_zone Exit Zone: why and how Users that have looked at some of our platforms may have notice a non-intuitive schema ... Something like that: -\verbatim +@verbatim @@ -1646,7 +1646,7 @@ non-intuitive schema ... Something like that: -\endverbatim +@endverbatim In the zone_4, you have an exitzone_4 defined, containing only one router, and routes defined to that zone from all other zone (as cluster is only a @@ -1657,14 +1657,14 @@ issues) to have routes from an zone to a single host/router, you have to enclose your gateway, when you have zone included in your zone, within an zone to define routes to it. -\subsection pf_P2P_tags P2P or how to use coordinates +@subsection pf_P2P_tags P2P or how to use coordinates SimGrid allows you to use some coordinated-based system, like vivaldi, to describe a platform. The main concept is that you have some peers that are located somewhere: this is the function of the -coordinates of the \ or \ tag. There's nothing +coordinates of the @ or @ tag. There's nothing complicated in using it, here is an example: -\verbatim +@verbatim @@ -1676,7 +1676,7 @@ complicated in using it, here is an example:
-\endverbatim +@endverbatim Coordinates are then used to calculate latency (in microseconds) between two hosts by calculating the distance between the two hosts @@ -1690,7 +1690,7 @@ approximations of the latency matrices (see the paper describing Vivaldi). Note that the previous example defines a routing directly between hosts but it could be also used to define a routing between zone. -That is for example what is commonly done when using peers (see Section \ref pf_peer). +That is for example what is commonly done when using peers (see Section @ref pf_peer). @verbatim @@ -1709,7 +1709,7 @@ This is currently a convention and we may offer to change this convention in the You may have noted that conveniently, a peer named FOO defines an zone named FOO and a router named router_FOO, which is why it works seamlessly with the peer tag. -\subsection pf_routing_howto_choose_wisely Choosing wisely the routing model to use +@subsection pf_routing_howto_choose_wisely Choosing wisely the routing model to use Choosing wisely the routing model to use can significantly fasten your @@ -1717,27 +1717,27 @@ simulation/save your time when writing the platform/save tremendous disk space. Here is the list of available model and their characteristics (lookup: time to resolve a route): -\li Full: Full routing data (fast, large memory requirements, +@li Full: Full routing data (fast, large memory requirements, fully expressive) -\li Floyd: Floyd routing data (slow initialization, fast +@li Floyd: Floyd routing data (slow initialization, fast lookup, lesser memory requirements, shortest path routing only). Calculates all routes at once at the beginning. -\li Dijkstra: Dijkstra routing data (fast initialization, slow +@li Dijkstra: Dijkstra routing data (fast initialization, slow lookup, small memory requirements, shortest path routing only). Calculates a route when necessary. -\li DijkstraCache: Dijkstra routing data (fast initialization, +@li DijkstraCache: Dijkstra routing data (fast initialization, fast lookup, small memory requirements, shortest path routing only). Same as Dijkstra, except it handles a cache for latest used routes. -\li None: No routing (usable with Constant network only). +@li None: No routing (usable with Constant network only). Defines that there is no routes, so if you try to determine a route without constant network within this zone, SimGrid will raise an exception. -\li Vivaldi: Vivaldi routing, so when you want to use coordinates -\li Cluster: Cluster routing, specific to cluster tag, should +@li Vivaldi: Vivaldi routing, so when you want to use coordinates +@li Cluster: Cluster routing, specific to cluster tag, should not be used. -\subsection pf_switch I want to describe a switch but there is no switch tag! +@subsection pf_switch I want to describe a switch but there is no switch tag! Actually we did not include switch tag. But when you're trying to simulate a switch, assuming @@ -1752,7 +1752,7 @@ can be connected to this "switch", which is then included in routes just as a normal link. -\subsection pf_multicabinets I want to describe multi-cabinets clusters! +@subsection pf_multicabinets I want to describe multi-cabinets clusters! You have several possibilities, as usual when modeling things. If your cabinets are homogeneous and the intercabinet network negligible for @@ -1772,13 +1772,13 @@ the <cluster> internals is certainly to create one separate <cluster> per cabinet and interconnect them together. This is what we did in the G5K example platform for the Graphen cluster. -\subsection pf_platform_multipath I want to express multipath routing in platform files! +@subsection pf_platform_multipath I want to express multipath routing in platform files! It is unfortunately impossible to express the fact that there is more than one routing path between two given hosts. Let's consider the following platform file: -\verbatim +@verbatim @@ -1788,7 +1788,7 @@ following platform file: -\endverbatim +@endverbatim Although it is perfectly valid, it does not mean that data traveling from A to C can either go directly (using link 3) or through B (using @@ -1803,12 +1803,12 @@ the provided ones. You are also free to declare platform where the routing is not symmetrical. For example, add the following to the previous file: -\verbatim +@verbatim -\endverbatim +@endverbatim This makes sure that data from C to A go through B where data from A to C go directly. Don't worry about realism of such settings since diff --git a/doc/doxygen/platform_lua.doc b/doc/doxygen/platform_lua.doc index 97596eb8dc..a844a7930b 100644 --- a/doc/doxygen/platform_lua.doc +++ b/doc/doxygen/platform_lua.doc @@ -19,7 +19,7 @@ mail so that we keep it working once S4U is out, to give you the time to switch at your pace. -\section pf_lua_why Why lua ? +@section pf_lua_why Why lua ? Lua is a fast and portable scripting language. Its main goal is to make the internal mechanics of C/C++ programs easily recombinable from diff --git a/doc/doxygen/uhood.doc b/doc/doxygen/uhood.doc index 67632a5d26..df2de9bcab 100644 --- a/doc/doxygen/uhood.doc +++ b/doc/doxygen/uhood.doc @@ -1,13 +1,13 @@ /*! @page uhood Under the Hood -\tableofcontents +@tableofcontents TBD - Simulation Loop, LMM, sharing -> papers - Context Switching, privatization -> papers -\section simgrid_uhood_s4u S4U +@section simgrid_uhood_s4u S4U S4U classes are designed to be user process interfaces to Maestro resources. We provide an uniform interface to them: @@ -129,9 +129,9 @@ void SIMIX_process_unref(smx_process_t process) } ~~~ -\section simgrid_uhood_async Asynchronous operations +@section simgrid_uhood_async Asynchronous operations -\subsection simgrid_uhood_futures Futures +@subsection simgrid_uhood_futures Futures The `simgrid::kernel::Future` class has been added to SimGrid as an abstraction to represent asynchronous operations in the SimGrid maestro. Its API is based @@ -197,9 +197,9 @@ futures are currently not implemented in our futures however such as [`shared_future`](http://en.cppreference.com/w/cpp/thread/shared_future), [`when_any()`](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/p0159r0.html#futures.when_any). -\subsection simgrid_uhood_timer Timers +@subsection simgrid_uhood_timer Timers -\section simgrid_uhood_mc Model Checker +@section simgrid_uhood_mc Model Checker The current implementation of the model-checker uses two distinct processes: @@ -226,7 +226,7 @@ process using the following techniques: - a custom heap is enabled in the model-checked process which allows the model checker to know which chunks are allocated and which are freed. -\subsection simgrid_uhood_mc_address_space Address space +@subsection simgrid_uhood_mc_address_space Address space The `AddressSpace` is a base class used for both the model-checked process and its snapshots and has methods to read in the corresponding address space: @@ -243,7 +243,7 @@ Additional helper class include: - `RemotePtr` represents the address of an object of type `T` in some remote `AddressSpace` (it could be an alias to `Remote`). -\subsection simgrid_uhood_mc_address_elf_dwarf ELF and DWARF +@subsection simgrid_uhood_mc_address_elf_dwarf ELF and DWARF [ELF](http://refspecs.linuxbase.org/elf/elf.pdf) is a standard executable file and dynamic libraries file format. diff --git a/doc/doxygen/uhood_arch.doc b/doc/doxygen/uhood_arch.doc index 484026c327..f8663f4332 100644 --- a/doc/doxygen/uhood_arch.doc +++ b/doc/doxygen/uhood_arch.doc @@ -13,20 +13,20 @@ If you need to extend SimGrid, then you probably need to head to @ref uhood_tech once you understant the overall design presented on this page. -\htmlonly +@htmlonly
-\endhtmlonly -\htmlinclude simgrid_modules.map -\htmlonly +@endhtmlonly +@htmlinclude simgrid_modules.map +@htmlonly
SimGrid Components (click to jump to API)
-\endhtmlonly +@endhtmlonly -\section ug_overview Overview of the toolkit components +@section ug_overview Overview of the toolkit components -\subsection ug_overview_envs Programing environments layer +@subsection ug_overview_envs Programing environments layer SimGrid provides several programming environments built on top of a unique simulation kernel. Each environment targets a specific audience and @@ -35,17 +35,17 @@ you have to think about what you want to do and what would be the result of your work. - If you want to study a theoretical problem and compare several - heuristics, you probably want to try \ref MSG_API (yet another + heuristics, you probably want to try @ref MSG_API (yet another historical name). It was designed exactly to that extend and should allow you to build easily rather realistic multi-agents simulation. Yet, realism is not the main goal of this environment and the most annoying - technical issues of real platforms are masked here. Check the \ref + technical issues of real platforms are masked here. Check the @ref MSG_API section for more information. - If you want to study the behavior of a MPI application using emulation, - you should have a look at the \ref SMPI_API (Simulated + you should have a look at the @ref SMPI_API (Simulated MPI) programming environment. Unfortunately, this work is still underway. - Check the \ref SMPI_API section for more information. + Check the @ref SMPI_API section for more information. If your favorite programming environment/model is not there (BSP, components, OpenMP, etc.) is not represented in the SimGrid toolkit yet, you may @@ -53,10 +53,10 @@ consider adding it. You should contact us first on the SimGrid developers mailing list, though. -\subsection ug_overview_kernel Simulation kernel layer +@subsection ug_overview_kernel Simulation kernel layer The core functionalities to simulate a virtual platform are provided by a -module called \ref SURF_API. It is +module called @ref SURF_API. It is very low-level and is not intended to be used as such by end-users. Instead, it serve as a basis for the higher level layer. @@ -64,27 +64,27 @@ SURF main features are a fast max-min linear solver and the ability to change transparently the model used to describe the platform. This greatly eases the comparison of the several models existing in the literature. -See the \ref SURF_API section for more details. +See the @ref SURF_API section for more details. -\subsection ug_overview_fundation Base layer +@subsection ug_overview_fundation Base layer -The base of the whole toolkit is constituted by the \ref XBT_API +The base of the whole toolkit is constituted by the @ref XBT_API (eXtended Bundle of Tools). -It is a portable library providing some grounding features such as \ref -XBT_log, \ref XBT_ex and \ref XBT_config. +It is a portable library providing some grounding features such as @ref +XBT_log, @ref XBT_ex and @ref XBT_config. XBT also encompass the following convenient C data structures: -\ref XBT_dynar and \ref XBT_dict. +@ref XBT_dynar and @ref XBT_dict. The code is being migrated in C++ so you should probably want to use standard C++ containers instead of them if possible. It contains some C++ polyfills and utilities as well. -See the \ref XBT_API section for more details. +See the @ref XBT_API section for more details. -\subsection ug_lucas_layer Tracing simulation -Finally, a transversal module allows you to trace your simulation. More documentation in the section \ref TRACE_doc +@subsection ug_lucas_layer Tracing simulation +Finally, a transversal module allows you to trace your simulation. More documentation in the section @ref TRACE_doc */ diff --git a/doc/tuto-msg/tuto-msg.doc b/doc/tuto-msg/tuto-msg.doc index 01b1fb4b64..c0ebbb3e60 100644 --- a/doc/tuto-msg/tuto-msg.doc +++ b/doc/tuto-msg/tuto-msg.doc @@ -1,12 +1,12 @@ /*! @page tutorial_msg SimGrid Tutorial with MSG -\tableofcontents +@tableofcontents -\section tuto-msg-intro Introduction +@section tuto-msg-intro Introduction -\subsection tuto-msg-intro-settings Settings +@subsection tuto-msg-intro-settings Settings -\warning Before you take this tutorial, you should remember that the +@warning Before you take this tutorial, you should remember that the MSG interface is currently deprecated. It means that it will remain as is, inchanged, for a few years, but that new developments should use the new S4U interface instead. Unfortunately, the S4U tutorial is not @@ -22,15 +22,15 @@ simulator. Let's consider the following scenario: > large) set of worker machines. What is the best way to organize the > computations ? -\htmlonly +@htmlonly
-\endhtmlonly -\htmlinclude tuto-msg/overview.svg -\htmlonly +@endhtmlonly +@htmlinclude tuto-msg/overview.svg +@htmlonly
-\endhtmlonly +@endhtmlonly -\subsection tuto-msg-intro-questions Raised Questions +@subsection tuto-msg-intro-questions Raised Questions Although this looks like a very simple setting it raises several interesting questions: @@ -103,7 +103,7 @@ With SimGrid, you can forget about most technical details (but not all), and focus on your algorithm. The whole simulation mechanism is already working. -\subsection tuto-msg-intro-goal Envisionned Study +@subsection tuto-msg-intro-goal Envisionned Study The following figure is a screenshot of [triva][fn:1] visualizing a [SimGrid @@ -113,9 +113,9 @@ usage over a long period of time. ![Test](./sc3-description.png) -\section tuto-msg-starting Getting Started +@section tuto-msg-starting Getting Started -\subsection tuto-msg-prerequesite Prerequisite +@subsection tuto-msg-prerequesite Prerequisite In this example, we use Pajeng and Vite to visualize the result of SimGrid simulations. These external tools are usually very easy to @@ -125,7 +125,7 @@ install. On Debian and Ubuntu for example, you can get them as follows: sudo apt-get install pajeng vite ~~~~ -\subsection tuto-msg-setup Setting up and Compiling +@subsection tuto-msg-setup Setting up and Compiling The corresponding source files can be obtained [online on GitLab](https://gitlab.inria.fr/simgrid/simgrid/tree/master/doc/tuto-msg/src). @@ -138,7 +138,7 @@ everything for you. If you struggle with the compilation, then you should double your @ref install "SimGrid installation". On need, please refer to the @ref install_yours_trouble section. -\section tuto-msg-ex0 Discovering the provided simulator +@section tuto-msg-ex0 Discovering the provided simulator Please compile and execute the provided simulator as follows: @@ -155,8 +155,8 @@ For a more "fancy" output, you can use simgrid-colorizer. If you installed SimGrid to a non-standard path, you may have to specify the full path to simgrid-colorizer on the above line, such as -\c /opt/simgrid/bin/simgrid-colorizer. If you did not install it at all, -you can find it in \/bin/colorize. +@c /opt/simgrid/bin/simgrid-colorizer. If you did not install it at all, +you can find it in @/bin/colorize. For a classical Gantt-Chart visualization, you can produce a [Paje][fn:5] trace: @@ -174,25 +174,25 @@ Alternatively, you can use [vite][fn:6]. vite simgrid.trace ~~~~ -\subsection tuto-msg-exo0-source Understanding this source code +@subsection tuto-msg-exo0-source Understanding this source code -Explore the \ref doc/tuto-msg/masterworker.c source file. It contains 3 functions: - - \c master: that's the code executed by the master process.
+Explore the @ref doc/tuto-msg/masterworker.c source file. It contains 3 functions: + - @c master: that's the code executed by the master process.
It creates a large array containing all tasks, dispatches all tasks to the workers and then dispatch specific tasks which name is "finalize". - - \c worker: each workers will execute this function.
+ - @c worker: each workers will execute this function.
That's an infinite loop waiting for incomming tasks. We exit the loop if the name of the received task is "finalize", or process the task otherwise. - - \c main: this setups the simulation. + - @c main: this setups the simulation. How does SimGrid know that we need one master and several workers? -Because it's written in the deployment file (called \c +Because it's written in the deployment file (called @c deployment0.xml), that we pass to MSG_create_environment() during the setup. -\include doc/tuto-msg/deployment0.xml +@include doc/tuto-msg/deployment0.xml -\section tuto-msg-exo1 Exercise 1: Simplifying the deployment file +@section tuto-msg-exo1 Exercise 1: Simplifying the deployment file In the provided example, the deployment file `deployment0.xml` is tightly connected to the platform file `small_platform.xml` and adding @@ -205,7 +205,7 @@ so that the master launches a worker process on all the other machines at startup. The new deployment file `deployment1.xml` should be as simple as: -\include doc/tuto-msg/deployment1.xml +@include doc/tuto-msg/deployment1.xml For that, the master needs to retrieve the list of hosts declared in the platform, with the following functions (follow the links for their @@ -223,7 +223,7 @@ Then, the master should start the worker processes with the following function: msg_process_t MSG_process_create(const char *name, xbt_main_func_t code, void *data, msg_host_t host); ~~~~ -\subsection tuto-msg-exo1-config Increasing configurability +@subsection tuto-msg-exo1-config Increasing configurability The worker processes wait for incomming messages on a channel which name they need to know beforehand. In the provided code, each worker @@ -256,7 +256,7 @@ A third possibility would be to inverse the communication architecture and have the workers pulling work from the master. This require to pass the master's channel to the workers. -\subsection tuto-msg-exo1-wrapup Wrap up +@subsection tuto-msg-exo1-wrapup Wrap up In this exercise, we reduced the amount of configuration that our simulator requests. This is both a good idea, and a dangerous @@ -274,10 +274,10 @@ separation of concerns between things that are of very different nature. If you struggle with this exercise, have a look at -our solution in \ref doc/tuto-msg/masterworker-sol1.c +our solution in @ref doc/tuto-msg/masterworker-sol1.c This is not perfect at all, and many other solutions would have been possible, of course. -\section tuto-msg-exo2 Exercise 2: Infinite amount of work, fixed experiment duration +@section tuto-msg-exo2 Exercise 2: Infinite amount of work, fixed experiment duration In the current version, the number of tasks is defined through the worker arguments. Hence, tasks are created at the very beginning of @@ -304,9 +304,9 @@ int MSG_process_killall(int reset_PIDs); Anyway, the new deployment `deployment2.xml` file should thus look like this: -\include doc/tuto-msg/deployment2.xml +@include doc/tuto-msg/deployment2.xml -\subsection tuto-msg-exo2-verbosity Controlling the message verbosity +@subsection tuto-msg-exo2-verbosity Controlling the message verbosity Not all messages are equally informative, so you probably want to change most of the `XBT_INFO` into `XBT_DEBUG` so that they are hidden @@ -317,16 +317,16 @@ processed by default. You can still see the debug messages as follows: ./masterworker examples/platforms/small_platform.xml deployment2.xml --log=msg_test.thres:debug ~~~~ -\subsection tuto-msg-exo2-wrapup Wrap up +@subsection tuto-msg-exo2-wrapup Wrap up Our imperfect solution to this exercise is available as @ref doc/tuto-msg/masterworker-sol2.c But there is still much to improve in that code. -\section tuto-msg-exo3 Exercise 3: Understanding how competing applications behave +@section tuto-msg-exo3 Exercise 3: Understanding how competing applications behave It is now time to start several applications at once, with the following `deployment3.xml` file. -\include doc/tuto-msg/deployment3.xml +@include doc/tuto-msg/deployment3.xml Things happen when you do so, but it remains utterly difficult to understand what's happening exactely. Even visualizations with pajeng @@ -345,7 +345,7 @@ The outcome can then be visualized as a Gantt-chart as follows: vite simgrid.trace ~~~~ -\subsection tuto-msg-exo3-further Going further +@subsection tuto-msg-exo3-further Going further vite is not enough to understand the situation, because it does not deal with categorization. That is why you should switch to R to @@ -355,7 +355,7 @@ page. As usual, you can explore our imperfect solution, in @ref doc/tuto-msg/masterworker-sol3.c. -\section tuto-msg-exo4 Exercise 4: Better scheduling: FCFS +@section tuto-msg-exo4 Exercise 4: Better scheduling: FCFS You don't need a very advanced visualization solution to notice that round-robin is completely suboptimal: most of the workers keep waiting @@ -378,7 +378,7 @@ time is up, and answer with a terminating task. Once it works, you will see that such as simple FCFS schema allows to double the amount of tasks handled over time in this case. -\subsection tuto-msg-exo4-further Going further +@subsection tuto-msg-exo4-further Going further From this, many things can easily be added. For example, you could: - Allow workers to have several pending requests so as to overlap @@ -391,12 +391,12 @@ From this, many things can easily be added. For example, you could: - Optimize not only for the amount of tasks handled, but also for the total energy dissipated. - And so on. If you come up with a really nice extension, please share it with us so that we can extend this tutorial. -\section tuto-msg-further Where to go from here? +@section tuto-msg-further Where to go from here? This tutorial is now terminated. You could keep reading the [online documentation][fn:4] or [tutorials][fn:7], or you could head up to the example section to read some code. -\subsection tuto-msg-further-todo TODO: Points to improve for the next time +@subsection tuto-msg-further-todo TODO: Points to improve for the next time - Propose equivalent exercises and skeleton in java. - Propose a virtualbox image with everything (simgrid, pajeng, ...) already set diff --git a/examples/msg/app-masterworker/app-masterworker.c b/examples/msg/app-masterworker/app-masterworker.c index 55aaf69d14..711bed895a 100644 --- a/examples/msg/app-masterworker/app-masterworker.c +++ b/examples/msg/app-masterworker/app-masterworker.c @@ -55,7 +55,7 @@ static int worker(int argc, char *argv[]) snprintf(mailbox,79, "worker-%ld", id); - while (1) { /* The worker wait in an infinite loop for tasks sent by the \ref master */ + while (1) { /* The worker wait in an infinite loop for tasks sent by the @ref master */ msg_task_t task = NULL; int res = MSG_task_receive(&task, mailbox); xbt_assert(res == MSG_OK, "MSG_task_get failed"); diff --git a/examples/msg/dht-pastry/dht-pastry.c b/examples/msg/dht-pastry/dht-pastry.c index ad21a404f9..e33c77bc7f 100644 --- a/examples/msg/dht-pastry/dht-pastry.c +++ b/examples/msg/dht-pastry/dht-pastry.c @@ -78,9 +78,9 @@ static int closest_in_namespace_set(node_t node, int dest); static int routing_next(node_t node, int dest); /** - * \brief Gets the mailbox name of a host given its chord id. - * \param node_id id of a node - * \param mailbox pointer to where the mailbox name should be written + * @brief Gets the mailbox name of a host given its chord id. + * @param node_id id of a node + * @param mailbox pointer to where the mailbox name should be written * (there must be enough space) */ static void get_mailbox(int node_id, char* mailbox) @@ -449,7 +449,7 @@ static int join(node_t node){ } /** - * \brief Node Function + * @brief Node Function * Arguments: * - my id * - the id of a guy I know in the system (except for the first node) @@ -546,7 +546,7 @@ static int node(int argc, char *argv[]) return 1; } -/** \brief Main function. */ +/** @brief Main function. */ int main(int argc, char *argv[]) { MSG_init(&argc, argv); diff --git a/examples/s4u/README.doc b/examples/s4u/README.doc index f4f51c2487..b2ea1b31d9 100644 --- a/examples/s4u/README.doc +++ b/examples/s4u/README.doc @@ -51,12 +51,12 @@ TODO: document here the examples about plugins @subsection s4u_ex_actors_start Starting and stoping actors - Creating actors. - @ref examples/s4u/actor-create/s4u-actor-create.cpp \n + @ref examples/s4u/actor-create/s4u-actor-create.cpp @n Most actors are started from the deployment XML file, but there is other methods. This example show them all. - Kill actors. - @ref examples/s4u/actor-kill/s4u-actor-kill.cpp \n + @ref examples/s4u/actor-kill/s4u-actor-kill.cpp @n Actors can forcefully stop other actors with the @ref simgrid::s4u::Actor::kill(void) or the @ref simgrid::s4u::Actor::kill(aid_t) methods. @@ -64,33 +64,33 @@ TODO: document here the examples about plugins - Controling the actor life cycle from the XML. @ref examples/s4u/actor-lifetime/s4u-actor-lifetime.cpp @ref examples/s4u/actor-lifetime/s4u-actor-lifetime_d.xml - \n + @n You can specify a start time and a kill time in the deployment file. - Daemonize actors - @ref examples/s4u/actor-daemon/s4u-actor-daemon.cpp \n + @ref examples/s4u/actor-daemon/s4u-actor-daemon.cpp @n Some actors may be intended to simulate daemons that run in background. This example show how to transform a regular actor into a daemon that will be automatically killed once the simulation is over. @subsection s4u_ex_actors_synchro Inter-actors interactions - Suspend and Resume actors. - @ref examples/s4u/actor-suspend/s4u-actor-suspend.cpp \n + @ref examples/s4u/actor-suspend/s4u-actor-suspend.cpp @n Actors can be suspended and resumed during their executions thanks to the @ref simgrid::s4u::Actor::suspend and @ref simgrid::s4u::Actor::resume methods. - Migrating Actors. - @ref examples/s4u/actor-migration/s4u-actor-migration.cpp \n + @ref examples/s4u/actor-migration/s4u-actor-migration.cpp @n Actors can move or be moved from a host to another with the @ref simgrid::s4u::this_actor::migrate() method. - Waiting for the termination of an actor (joining on it) - @ref examples/s4u/actor-join/s4u-actor-join.cpp \n + @ref examples/s4u/actor-join/s4u-actor-join.cpp @n The simgrid::s4u::Actor::join() method allows to block the current actor until the end of the receiving actor. - Yielding to other actor. - @ref examples/s4u/actor-yield/s4u-actor-yield.cpp\n + @ref examples/s4u/actor-yield/s4u-actor-yield.cpp@n The simgrid::s4u::this_actor::yield() function interrupts the execution of the current actor, leaving a chance to the other actors that are ready to run at this timestamp. @@ -114,12 +114,12 @@ with, but the second is more efficient on very large traces. Check also the tesh files in the example directories for details. - Communication replay. - @ref examples/s4u/replay-comm/s4u-replay-comm.cpp \n + @ref examples/s4u/replay-comm/s4u-replay-comm.cpp @n Presents a set of event handlers reproducing classical communication primitives (asynchronous send/receive at the moment). - I/O replay. - @ref examples/s4u/replay-storage/s4u-replay-storage.cpp \n + @ref examples/s4u/replay-storage/s4u-replay-storage.cpp @n Presents a set of event handlers reproducing classical I/O primitives (open, read, close). @@ -128,7 +128,7 @@ also the tesh files in the example directories for details. @subsection s4u_ex_activity_comm Communications on the network - Basic asynchronous communications. - @ref examples/s4u/async-wait/s4u-async-wait.cpp \n + @ref examples/s4u/async-wait/s4u-async-wait.cpp @n Illustrates how to have non-blocking communications, that are communications running in the background leaving the process free to do something else during their completion. The main functions @@ -136,12 +136,12 @@ also the tesh files in the example directories for details. @ref simgrid::s4u::Comm::wait(). - Waiting for all communications in a set. - @ref examples/s4u/async-waitall/s4u-async-waitall.cpp\n + @ref examples/s4u/async-waitall/s4u-async-waitall.cpp@n The @ref simgrid::s4u::Comm::wait_all() function is useful when you want to block until all activities in a given set have completed. - Waiting for the first completed communication in a set. - @ref examples/s4u/async-waitany/s4u-async-waitany.cpp\n + @ref examples/s4u/async-waitany/s4u-async-waitany.cpp@n The @ref simgrid::s4u::Comm::wait_any() function is useful when you want to block until one activity of the set completes, no matter which terminates first. @@ -149,7 +149,7 @@ also the tesh files in the example directories for details. @subsection s4u_ex_activity_exec Executions on the CPU - Basic execution. - @ref examples/s4u/exec-basic/s4u-exec-basic.cpp \n + @ref examples/s4u/exec-basic/s4u-exec-basic.cpp @n The computations done in your program are not reported to the simulated world, unless you explicitely request the simulator to pause the actor until a given amount of flops gets computed on its simulated @@ -157,27 +157,27 @@ also the tesh files in the example directories for details. get more resources. - Asynchronous execution. - @ref examples/s4u/exec-async/s4u-exec-async.cpp \n + @ref examples/s4u/exec-async/s4u-exec-async.cpp @n You can start asynchronous executions, just like you would fire background threads. - Monitoring asynchronous executions. - @ref examples/s4u/exec-monitor/s4u-exec-monitor.cpp \n + @ref examples/s4u/exec-monitor/s4u-exec-monitor.cpp @n This example shows how to start an asynchronous execution, and monitor its status. - Remote execution. - @ref examples/s4u/exec-remote/s4u-exec-remote.cpp \n + @ref examples/s4u/exec-remote/s4u-exec-remote.cpp @n Before its start, you can change the host on which a given execution will occur. - Using Pstates on a host @ref examples/s4u/exec-dvfs/s4u-exec-dvfs.cpp and - @ref examples/platforms/energy_platform.xml \n + @ref examples/platforms/energy_platform.xml @n Show how define a set of pstatesfor a host in the XML, and how the current pstate can be accessed/changed with @ref simgrid::s4u::Host::getPstateSpeed and @ref simgrid::s4u::Host::setPstate. - Parallel tasks - @ref examples/s4u/exec-ptask/s4u-exec-ptask.cpp\n + @ref examples/s4u/exec-ptask/s4u-exec-ptask.cpp@n These objects are convenient abstractions of parallel computational kernels that span over several machines. @@ -188,7 +188,7 @@ simulated storages. At the simplest level, you simply create read and write actions on the storage resources. - Access to raw storage devices. - @ref examples/s4u/io-storage-raw/s4u-io-storage-raw.cpp \n + @ref examples/s4u/io-storage-raw/s4u-io-storage-raw.cpp @n This example illustrates how to simply read and write data on a simulated storage resource. @@ -197,30 +197,30 @@ classical operations over files: open, move, unlink, and of course read and write. The file and disk sizes are also dealt with and can result in short reads and short write, as in reality. - - File Management. @ref examples/s4u/io-file-system/s4u-io-file-system.cpp \n + - File Management. @ref examples/s4u/io-file-system/s4u-io-file-system.cpp @n This example illustrates the use of operations on files (read, write, seek, tell, unlink, ...). - Remote I/O. - @ref examples/s4u/io-file-remote/s4u-io-file-remote.cpp \n + @ref examples/s4u/io-file-remote/s4u-io-file-remote.cpp @n I/O operations on files can also be done in a remote fashion, i.e. when the accessed disk is not mounted on the caller's host. @subsection s4u_ex_activity_synchro Classical synchronization objects - - Mutex: @ref examples/s4u/mutex/s4u-mutex.cpp \n + - Mutex: @ref examples/s4u/mutex/s4u-mutex.cpp @n Shows how to use simgrid::s4u::Mutex synchronization objects. @section s4u_ex_platf Interacting with the platform - Retrieving the list of hosts matching a given criteria. - @ref examples/s4u/engine-filtering/s4u-engine-filtering.cpp\n + @ref examples/s4u/engine-filtering/s4u-engine-filtering.cpp@n Filtering the actors that match a given criteria is rather simple. - User-defined properties. @ref examples/s4u/platform-properties/s4u-platform-properties.cpp and @ref examples/s4u/platform-properties/s4u-platform-properties_d.xml and - @ref examples/platforms/prop.xml \n + @ref examples/platforms/prop.xml @n You can attach arbitrary information to most platform elements from the XML file, and then interact with these values from your program. Note that the changes are not written into the XML file: they @@ -233,14 +233,14 @@ result in short reads and short write, as in reality. @section s4u_ex_energy Simulating the energy consumption - Describing the energy profiles in the platform - @ref examples/platforms/energy_platform.xml \n + @ref examples/platforms/energy_platform.xml @n This platform file contains the energy profile of each links and hosts, which is necessary to get energy consumption predictions. As usual, you should not trust our example, and you should strive to double-check that your instanciation matches your target platform. - Consumption due to the CPU - @ref examples/s4u/energy-exec/s4u-energy-exec.cpp \n + @ref examples/s4u/energy-exec/s4u-energy-exec.cpp @n This example shows how to retrieve the amount of energy consumed by the CPU during computations, and the impact of the pstate. @@ -251,7 +251,7 @@ result in short reads and short write, as in reality. - Modeling the shutdown and boot of hosts @ref examples/s4u/energy-boot/platform_boot.xml - @ref examples/s4u/energy-boot/s4u-energy-boot.cpp\n + @ref examples/s4u/energy-boot/s4u-energy-boot.cpp@n Simple example of model of model for the energy consumption during the host boot and shutdown periods. @@ -265,7 +265,7 @@ It is interesting to run the process-create example with the following options to see the task executions: - Platform tracing. - @ref examples/s4u/trace-platform/s4u-trace-platform.cpp \n + @ref examples/s4u/trace-platform/s4u-trace-platform.cpp @n This program is a toy example just loading the platform, so that you can play with the platform visualization. Recommanded options: @verbatim --cfg=tracing:yes --cfg=tracing/categorized:yes @@ -276,33 +276,33 @@ options to see the task executions: This section contains application examples that are somewhat larger than the previous examples. - - Ping Pong: @ref examples/s4u/app-pingpong/s4u-app-pingpong.cpp\n + - Ping Pong: @ref examples/s4u/app-pingpong/s4u-app-pingpong.cpp@n This simple example just sends one message back and forth. The tesh file laying in the directory show how to start the simulator binary, highlighting how to pass options to - the simulators (as detailed in Section \ref options). + the simulators (as detailed in Section @ref options). - - Token ring: @ref examples/s4u/app-token-ring/s4u-app-token-ring.cpp \n + - Token ring: @ref examples/s4u/app-token-ring/s4u-app-token-ring.cpp @n Shows how to implement a classical communication pattern, where a token is exchanged along a ring to reach every participant. - - Master Workers: @ref examples/s4u/app-masterworker/s4u-app-masterworker.cpp \n + - Master Workers: @ref examples/s4u/app-masterworker/s4u-app-masterworker.cpp @n Another good old example, where one Master process has a bunch of task to dispatch to a set of several Worker processes. @subsection s4u_ex_app_data Data diffusion - Bit Torrent - @ref examples/s4u/app-bittorrent/s4u-bittorrent.cpp\n + @ref examples/s4u/app-bittorrent/s4u-bittorrent.cpp@n Classical protocol for Peer-to-Peer data diffusion. - Chained send - @ref examples/s4u/app-chainsend/s4u-app-chainsend.cpp\n + @ref examples/s4u/app-chainsend/s4u-app-chainsend.cpp@n Data broadcast over a ring of processes. @subsection s4u_ex_app_dht Distributed Hash Tables (DHT) - Chord Protocol - @ref examples/s4u/dht-chord/s4u-dht-chord.cpp\n + @ref examples/s4u/dht-chord/s4u-dht-chord.cpp@n One of the most famous DHT protocol. */ diff --git a/examples/s4u/app-masterworker/s4u-app-masterworker.cpp b/examples/s4u/app-masterworker/s4u-app-masterworker.cpp index 68d0fa84a3..6b519cceb9 100644 --- a/examples/s4u/app-masterworker/s4u-app-masterworker.cpp +++ b/examples/s4u/app-masterworker/s4u-app-masterworker.cpp @@ -67,7 +67,7 @@ public: void operator()() { - while (1) { /* The worker waits in an infinite loop for tasks sent by the \ref master */ + while (1) { /* The worker waits in an infinite loop for tasks sent by the @ref master */ double* task = static_cast(mailbox->get()); xbt_assert(task != nullptr, "mailbox->get() failed"); double comp_size = *task; diff --git a/examples/s4u/dht-chord/s4u-dht-chord-node.cpp b/examples/s4u/dht-chord/s4u-dht-chord-node.cpp index e618a38516..90ae8c18b4 100644 --- a/examples/s4u/dht-chord/s4u-dht-chord-node.cpp +++ b/examples/s4u/dht-chord/s4u-dht-chord-node.cpp @@ -17,10 +17,10 @@ XBT_LOG_EXTERNAL_DEFAULT_CATEGORY(s4u_chord); * 24 belongs to [21, 29] * 24 does not belong to [29, 21] * - * \param id id to check - * \param start lower bound - * \param end upper bound - * \return a non-zero value if id in in [start, end] + * @param id id to check + * @param start lower bound + * @param end upper bound + * @return a non-zero value if id in in [start, end] */ static int is_in_interval(int id, int start, int end) { @@ -80,8 +80,8 @@ Node::~Node() } /* Makes the current node join the ring, knowing the id of a node already in the ring * - * \param known_id id of a node already in the ring - * \return true if the join operation succeeded + * @param known_id id of a node already in the ring + * @return true if the join operation succeeded * */ void Node::join(int known_id) @@ -157,9 +157,9 @@ void Node::randomLookup() /* Sets a finger of the current node. * - * \param node the current node - * \param finger_index index of the finger to set (0 to nb_bits - 1) - * \param id the id to set for this finger + * @param node the current node + * @param finger_index index of the finger to set (0 to nb_bits - 1) + * @param id the id to set for this finger */ void Node::setFinger(int finger_index, int id) { @@ -170,7 +170,7 @@ void Node::setFinger(int finger_index, int id) } /* Sets the predecessor of the current node. - * \param id the id to predecessor, or -1 to unset the predecessor + * @param id the id to predecessor, or -1 to unset the predecessor */ void Node::setPredecessor(int predecessor_id) { @@ -252,8 +252,8 @@ void Node::checkPredecessor() /* Asks its predecessor to a remote node * - * \param ask_to the node to ask to - * \return the id of its predecessor node, or -1 if the request failed (or if the node does not know its predecessor) + * @param ask_to the node to ask to + * @return the id of its predecessor node, or -1 if the request failed (or if the node does not know its predecessor) */ int Node::remoteGetPredecessor(int ask_to) { @@ -302,8 +302,8 @@ int Node::remoteGetPredecessor(int ask_to) /* Returns the closest preceding finger of an id with respect to the finger table of the current node. * - * \param id the id to find - * \return the closest preceding finger of that id + * @param id the id to find + * @return the closest preceding finger of that id */ int Node::closestPrecedingFinger(int id) { @@ -317,8 +317,8 @@ int Node::closestPrecedingFinger(int id) /* Makes the current node find the successor node of an id. * - * \param id the id to find - * \return the id of the successor node, or -1 if the request failed + * @param id the id to find + * @return the id of the successor node, or -1 if the request failed */ int Node::findSuccessor(int id) { @@ -419,7 +419,7 @@ void Node::stabilize() /* This function is called when a node receives a message. * - * \param message the message to handle (don't touch it afterward: it will be destroyed, reused or forwarded) + * @param message the message to handle (don't touch it afterward: it will be destroyed, reused or forwarded) */ void Node::handleMessage(ChordMessage* message) { diff --git a/include/simgrid/host.h b/include/simgrid/host.h index 30a58f5fd7..4a72056e6e 100644 --- a/include/simgrid/host.h +++ b/include/simgrid/host.h @@ -21,14 +21,14 @@ SG_BEGIN_DECL() XBT_PUBLIC sg_host_t* sg_host_list(); -/** \ingroup m_host_management - * \brief Return the current number of hosts. +/** @ingroup m_host_management + * @brief Return the current number of hosts. */ XBT_PUBLIC size_t sg_host_count(); -/** \ingroup m_host_management - * \brief Return a dynar containing all the hosts declared at a given point of time (including VMs) - * \remark The host order in the returned array is generally different from the host creation/declaration order in the +/** @ingroup m_host_management + * @brief Return a dynar containing all the hosts declared at a given point of time (including VMs) + * @remark 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 sg_hosts_as_dynar(); @@ -36,55 +36,55 @@ XBT_PUBLIC xbt_dynar_t sg_hosts_as_dynar(); XBT_PUBLIC size_t sg_host_extension_create(void (*deleter)(void*)); XBT_PUBLIC void* sg_host_extension_get(sg_host_t host, size_t rank); -/** \ingroup m_host_management - * \brief Finds a sg_host_t using its name. +/** @ingroup m_host_management + * @brief Finds a sg_host_t using its name. * * This is a name directory service - * \param name the name of an host. - * \return the corresponding host + * @param name the name of an host. + * @return the corresponding host */ XBT_PUBLIC sg_host_t sg_host_by_name(const char* name); -/** \ingroup m_host_management +/** @ingroup m_host_management * - * \brief Return the name of the #sg_host_t. */ + * @brief Return the name of the #sg_host_t. */ XBT_PUBLIC const char* sg_host_get_name(sg_host_t host); // ========== User Data ============== -/** \ingroup m_host_management +/** @ingroup m_host_management * - * \brief Return the user data of a #sg_host_t. + * @brief Return the user data of a #sg_host_t. * - * This functions returns the user data associated to \a host if it is possible. + * This functions returns the user data associated to @a host if it is possible. */ XBT_PUBLIC void* sg_host_user(sg_host_t host); -/** \ingroup m_host_management +/** @ingroup m_host_management * - * \brief Set the user data of a #sg_host_t. + * @brief Set the user data of a #sg_host_t. * - * This functions attach \a data to \a host if it is possible. + * This functions attach @a data to @a host if it is possible. */ XBT_PUBLIC void sg_host_user_set(sg_host_t host, void* userdata); XBT_PUBLIC void sg_host_user_destroy(sg_host_t host); // ========= storage related functions ============ -/** \ingroup m_host_management - * \brief Return the list of mount point names on an host. - * \param host a host - * \return a dict containing all mount point on the host (mount_name => sg_storage_t) +/** @ingroup m_host_management + * @brief Return the list of mount point names on an host. + * @param host a host + * @return a dict containing all mount point on the host (mount_name => sg_storage_t) */ XBT_PUBLIC xbt_dict_t sg_host_get_mounted_storage_list(sg_host_t host); -/** \ingroup m_host_management - * \brief Return the list of storages attached to an host. - * \param host a host - * \return a dynar containing all storages (name) attached to the host +/** @ingroup m_host_management + * @brief Return the list of storages attached to an host. + * @param host a host + * @return a dynar containing all storages (name) attached to the host */ XBT_PUBLIC xbt_dynar_t sg_host_get_attached_storage_list(sg_host_t host); // =========== user-level functions =============== -/** \ingroup m_host_management - * \brief Return the speed of the processor (in flop/s), regardless of the current load on the machine. +/** @ingroup m_host_management + * @brief Return the speed of the processor (in flop/s), regardless of the current load on the machine. */ XBT_PUBLIC double sg_host_speed(sg_host_t host); XBT_PUBLIC double sg_host_get_pstate_speed(sg_host_t host, int pstate_index); @@ -93,18 +93,18 @@ XBT_PUBLIC double sg_host_get_available_speed(sg_host_t host); XBT_PUBLIC int sg_host_core_count(sg_host_t host); -/** \ingroup m_process_management - * \brief Return the location on which a process is running. - * \return the sg_host_t corresponding to the location on which \a process is running. +/** @ingroup m_process_management + * @brief Return the location on which a process is running. + * @return the sg_host_t corresponding to the location on which @a process is running. */ XBT_PUBLIC sg_host_t sg_host_self(); XBT_PUBLIC const char* sg_host_self_get_name(); -/** \ingroup m_host_management - * \brief Return the total count of pstates defined for a host. See also @ref plugin_energy. +/** @ingroup m_host_management + * @brief Return the total count of pstates defined for a host. See also @ref plugin_energy. * - * \param host host to test + * @param host host to test */ XBT_PUBLIC int sg_host_get_nb_pstates(sg_host_t host); @@ -116,29 +116,29 @@ XBT_PUBLIC void sg_host_turn_off(sg_host_t host); XBT_PUBLIC int sg_host_is_on(sg_host_t host); XBT_PUBLIC int sg_host_is_off(sg_host_t host); -/** \ingroup m_host_management - * \brief Returns a xbt_dict_t consisting of the list of properties assigned to this host +/** @ingroup m_host_management + * @brief Returns a xbt_dict_t consisting of the list of properties assigned to this host * - * \param host a host - * \return a dict containing the properties + * @param host a host + * @return a dict containing the properties */ XBT_PUBLIC xbt_dict_t sg_host_get_properties(sg_host_t host); -/** \ingroup m_host_management - * \brief Returns the value of a given host property +/** @ingroup m_host_management + * @brief Returns the value of a given host property * - * \param host a host - * \param name a property name - * \return value of a property (or nullptr if property not set) + * @param host a host + * @param name a property name + * @return value of a property (or nullptr if property not set) */ XBT_PUBLIC const char* sg_host_get_property_value(sg_host_t host, const char* name); -/** \ingroup m_host_management - * \brief Change the value of a given host property +/** @ingroup m_host_management + * @brief Change the value of a given host property * - * \param host a host - * \param name a property name - * \param value what to change the property to + * @param host a host + * @param name a property name + * @param value what to change the property to */ XBT_PUBLIC void sg_host_set_property_value(sg_host_t host, const char* name, const char* value); diff --git a/include/simgrid/kernel/resource/Action.hpp b/include/simgrid/kernel/resource/Action.hpp index 9ed8456001..0881e68dc1 100644 --- a/include/simgrid/kernel/resource/Action.hpp +++ b/include/simgrid/kernel/resource/Action.hpp @@ -104,13 +104,13 @@ public: /** * @brief Mark that the action is now finished * - * @param state the new [state](\ref simgrid::kernel::resource::Action::State) of the current Action + * @param state the new [state](@ref simgrid::kernel::resource::Action::State) of the current Action */ void finish(Action::State state); - /** @brief Get the [state](\ref simgrid::kernel::resource::Action::State) of the current Action */ + /** @brief Get the [state](@ref simgrid::kernel::resource::Action::State) of the current Action */ Action::State get_state() const; /**< get the state*/ - /** @brief Set the [state](\ref simgrid::kernel::resource::Action::State) of the current Action */ + /** @brief Set the [state](@ref simgrid::kernel::resource::Action::State) of the current Action */ virtual void set_state(Action::State state); /** @brief Get the bound of the current Action */ diff --git a/include/simgrid/kernel/resource/Model.hpp b/include/simgrid/kernel/resource/Model.hpp index 5985e4b49b..be9ed178d2 100644 --- a/include/simgrid/kernel/resource/Model.hpp +++ b/include/simgrid/kernel/resource/Model.hpp @@ -111,8 +111,8 @@ private: } // namespace kernel } // namespace simgrid -/** \ingroup SURF_models - * \brief List of initialized models +/** @ingroup SURF_models + * @brief List of initialized models */ XBT_PUBLIC_DATA std::vector all_existing_models; diff --git a/include/simgrid/kernel/routing/FatTreeZone.hpp b/include/simgrid/kernel/routing/FatTreeZone.hpp index da365f7c0c..01a560e7e9 100644 --- a/include/simgrid/kernel/routing/FatTreeZone.hpp +++ b/include/simgrid/kernel/routing/FatTreeZone.hpp @@ -14,7 +14,7 @@ namespace routing { class XBT_PRIVATE FatTreeLink; -/** \brief A node in a fat tree (@ref FatTreeZone). +/** @brief A node in a fat tree (@ref FatTreeZone). * A FatTreeNode can either be a switch or a processing node. Switches are * identified by a negative ID. This class is closely related to fat */ @@ -25,7 +25,7 @@ public: /* Level into the tree, with 0 being the leafs. */ unsigned int level; - /* \brief Position into the level, starting from 0. + /* @brief Position into the level, starting from 0. */ unsigned int position; /** In order to link nodes between them, each one must be assigned a label, @@ -54,7 +54,7 @@ public: FatTreeNode(ClusterCreationArgs* cluster, int id, int level, int position); }; -/** \brief Link in a fat tree (@ref FatTreeZone). +/** @brief Link in a fat tree (@ref FatTreeZone). * * Represents a single, duplex link in a fat tree. This is necessary to have a tree. * It is equivalent to a physical link. @@ -102,14 +102,14 @@ public: ~FatTreeZone() override; void get_local_route(NetPoint* src, NetPoint* dst, RouteCreationArgs* into, double* latency) override; - /** \brief Generate the fat tree + /** @brief Generate the fat tree * * Once all processing nodes have been added, this will make sure the fat * tree is generated by calling generateLabels(), generateSwitches() and * then connection all nodes between them, using their label. */ void seal() override; - /** \brief Read the parameters in topo_parameters field. + /** @brief Read the parameters in topo_parameters field. * * It will also store the cluster for future use. */ diff --git a/include/simgrid/msg.h b/include/simgrid/msg.h index 66642ef622..154c19510d 100644 --- a/include/simgrid/msg.h +++ b/include/simgrid/msg.h @@ -151,12 +151,12 @@ XBT_PUBLIC void MSG_process_killall(); XBT_PUBLIC void MSG_process_set_kill_time(msg_process_t process, double kill_time); XBT_PUBLIC void MSG_process_yield(); - /** - * \brief @brief Communication action. - * \ingroup msg_task_usage + * @brief @brief Communication action. + * @ingroup msg_task_usage * - * Object representing an ongoing communication between processes. Such beast is usually obtained by using #MSG_task_isend, #MSG_task_irecv or friends. + * Object representing an ongoing communication between processes. Such beast is usually obtained by using + * #MSG_task_isend, #MSG_task_irecv or friends. */ typedef sg_msg_Comm* msg_comm_t; @@ -182,8 +182,8 @@ typedef struct msg_task { 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. + @ingroup m_task_management */ #define MSG_TASK_UNINITIALIZED NULL @@ -206,9 +206,9 @@ typedef enum { /************************** Global ******************************************/ XBT_PUBLIC void MSG_config(const char* key, const char* value); -/** \ingroup msg_simulation - * \brief Initialize the MSG internal data. - * \hideinitializer +/** @ingroup msg_simulation + * @brief Initialize the MSG internal data. + * @hideinitializer * * It also check that the link-time and compile-time versions of SimGrid do * match, so you should use this version instead of the #MSG_init_nocheck @@ -216,9 +216,10 @@ XBT_PUBLIC void MSG_config(const char* key, const char* value); * * We allow to link against compiled versions that differ in the patch level. */ -#define MSG_init(argc,argv) do { \ - sg_version_check(SIMGRID_VERSION_MAJOR,SIMGRID_VERSION_MINOR,SIMGRID_VERSION_PATCH);\ - MSG_init_nocheck(argc,argv); \ +#define MSG_init(argc, argv) \ + do { \ + sg_version_check(SIMGRID_VERSION_MAJOR, SIMGRID_VERSION_MINOR, SIMGRID_VERSION_PATCH); \ + MSG_init_nocheck(argc, argv); \ } while (0) XBT_PUBLIC void MSG_init_nocheck(int* argc, char** argv); diff --git a/include/simgrid/s4u/Link.hpp b/include/simgrid/s4u/Link.hpp index 8cb9612bcb..bd4a84bac9 100644 --- a/include/simgrid/s4u/Link.hpp +++ b/include/simgrid/s4u/Link.hpp @@ -20,7 +20,7 @@ namespace simgrid { namespace s4u { -/** @brief A Link represents the network facilities between [hosts](\ref simgrid::s4u::Host) */ +/** @brief A Link represents the network facilities between [hosts](@ref simgrid::s4u::Host) */ class XBT_PUBLIC Link : public simgrid::xbt::Extendable { friend simgrid::kernel::resource::LinkImpl; diff --git a/include/simgrid/simdag.h b/include/simgrid/simdag.h index cb54bd9b71..ebf6810bac 100644 --- a/include/simgrid/simdag.h +++ b/include/simgrid/simdag.h @@ -30,7 +30,7 @@ typedef sg_link_t SD_link_t; A task is some computing amount that can be executed in parallel on several hosts. A task may depend on other tasks, which means that the task cannot start until the other tasks are done. - Each task has a \ref e_SD_task_state_t "state" indicating whether the task is scheduled, running, done, ... + Each task has a @ref e_SD_task_state_t "state" indicating whether the task is scheduled, running, done, ... */ typedef struct s_SD_task_t* SD_task_t; @@ -66,7 +66,7 @@ typedef enum { * * A task is some working amount that can be executed in parallel on several hosts. * A task may depend on other tasks, which means that the task cannot start until the other tasks are done. - * Each task has a \ref e_SD_task_state_t "state" indicating whether the task is scheduled, running, done, ... + * Each task has a @ref e_SD_task_state_t "state" indicating whether the task is scheduled, running, done, ... * * @see SD_task_t, @see SD_task_dependency_api * @{ diff --git a/include/simgrid/simix.h b/include/simgrid/simix.h index 4f88d6b094..d2eeb7becf 100644 --- a/include/simgrid/simix.h +++ b/include/simgrid/simix.h @@ -26,7 +26,7 @@ some private data that can be only accessed by local process. - \see m_host_management + @see m_host_management @{ */ typedef enum { SIMIX_WAITING, @@ -46,9 +46,7 @@ typedef enum { /* ******************************** Synchro ************************************ */ -/** - * \ingroup simix_synchro_management - */ +/** @ingroup simix_synchro_management */ typedef struct s_smx_sem_t* smx_sem_t; /* ****************************** Process *********************************** */ diff --git a/include/xbt/config.h b/include/xbt/config.h index c111c50af9..81389f4149 100644 --- a/include/xbt/config.h +++ b/include/xbt/config.h @@ -18,8 +18,8 @@ * All modules of the SimGrid toolkit can be configured with this API. * User modules and libraries can also use these facilities to handle their own configuration. * - * A configuration set contain several \e variables which have a unique name in the set and can take a given type of - * value. For example, it may contain a \a size variable, accepting \e int values. + * A configuration set contain several @e variables which have a unique name in the set and can take a given type of + * value. For example, it may contain a @a size variable, accepting @e int values. * * It is impossible to set a value to a variable which has not been registered before. * Usually, the module registers all the options it accepts in the configuration set, during its initialization and @@ -27,17 +27,17 @@ * * The easiest way to register a variable is to use the xbt_str_register_str function, which accepts a string * representation of the config element descriptor. The syntax is the following: - * \verbatim :_to__\endverbatim + * @verbatim :_to__@endverbatim * - * For example, size:1_to_1_int describes a variable called \e size which must take exactly one value, and + * For example, size:1_to_1_int describes a variable called @e size which must take exactly one value, and * the value being an integer. Set the maximum to 0 to disable the upper bound on data count. * - * Another example could be outputfiles:0_to_10_string which describes a variable called \e outputfiles and + * Another example could be outputfiles:0_to_10_string which describes a variable called @e outputfiles and * which can take between 0 and 10 strings as value. * * To some extend, configuration sets can be seen as typed hash structures. * - * \section XBT_cfg_ex Example of use + * @section XBT_cfg_ex Example of use * * TBD */ @@ -66,7 +66,7 @@ SG_BEGIN_DECL() XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::set_parse") XBT_PUBLIC void xbt_cfg_set_parse(const char* options); -/* Set the value of the cell \a name in \a cfg with the provided value.*/ +/* Set the value of the cell @a name in @a cfg with the provided value.*/ XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::set_value") XBT_PUBLIC void xbt_cfg_set_int(const char* name, int val); XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::set_value") XBT_PUBLIC @@ -79,7 +79,7 @@ XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::set_as_string") XBT_PUBL void xbt_cfg_set_as_string(const char* name, const char* val); /* - Set the default value of the cell \a name in \a cfg with the provided value. + Set the default value of the cell @a name in @a cfg with the provided value. If it was already set to something (possibly from the command line), do nothing. */ XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::set_default") XBT_PUBLIC @@ -103,7 +103,7 @@ XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::is_default") XBT_PUBLIC * @{ */ -/** \brief Callback types. They get the name of the modified entry, and the position of the changed value */ +/** @brief Callback types. They get the name of the modified entry, and the position of the changed value */ typedef void (*xbt_cfg_cb_t)(const char* name); XBT_ATTRIB_DEPRECATED_v323("Please don't use it") XBT_PUBLIC xbt_cfg_t xbt_cfg_new(); diff --git a/include/xbt/cunit.h b/include/xbt/cunit.h index 296b582d16..5b405bb1c8 100644 --- a/include/xbt/cunit.h +++ b/include/xbt/cunit.h @@ -63,7 +63,7 @@ XBT_PUBLIC void xbt_test_exit(); * so why should we bother switching?) * * Unit testing is not intended to write integration tests. - * Please refer to \ref inside_tests_add_integration for that instead. + * Please refer to @ref inside_tests_add_integration for that instead. * * @{ */ diff --git a/include/xbt/dict.h b/include/xbt/dict.h index 3eeca4d023..89aaba22ea 100644 --- a/include/xbt/dict.h +++ b/include/xbt/dict.h @@ -25,7 +25,7 @@ SG_BEGIN_DECL() * * Here is a little example of use: -\verbatim +@verbatim xbt_dict_t mydict = xbt_dict_new_homogeneous(free); char buff[512]; @@ -34,7 +34,7 @@ SG_BEGIN_DECL() sprintf(buff,"another good stuff"); xbt_dict_set(mydict,"my data", strdup(buff), NULL); // previous data gets erased (and freed) by second add -\endverbatim +@endverbatim */ /** @defgroup XBT_dict_cons Dict constructor and destructor @@ -43,7 +43,7 @@ SG_BEGIN_DECL() * @{ */ - /** \brief Dictionary data type (opaque structure) */ +/** @brief Dictionary data type (opaque structure) */ typedef struct s_xbt_dict *xbt_dict_t; typedef struct s_xbt_dictelm *xbt_dictelm_t; typedef struct s_xbt_dictelm { @@ -111,15 +111,15 @@ struct s_xbt_dict_cursor { * * Here is an example (assuming that the dictionary contains strings, i.e., that the data argument of * xbt_dict_set was always a null-terminated char*): -\verbatim xbt_dict_cursor_t cursor=NULL; +@verbatim xbt_dict_cursor_t cursor=NULL; char *key,*data; xbt_dict_foreach(dict,cursor,key,data) { printf(" - Seen: %s->%s\n",key,data); - }\endverbatim + }@endverbatim * - * \warning Do not add or remove entries to the cache while traversing !! + * @warning Do not add or remove entries to the cache while traversing !! * * @{ */ @@ -142,14 +142,14 @@ XBT_PUBLIC void xbt_dict_cursor_first(const xbt_dict_t dict, xbt_dict_cursor_t* XBT_PUBLIC void xbt_dict_cursor_step(xbt_dict_cursor_t cursor); XBT_PUBLIC int xbt_dict_cursor_get_or_free(xbt_dict_cursor_t* cursor, char** key, void** data); /** @def xbt_dict_foreach - * @param dict a \ref xbt_dict_t iterator - * @param cursor an \ref xbt_dict_cursor_t used as cursor + * @param dict a @ref xbt_dict_t iterator + * @param cursor an @ref xbt_dict_cursor_t used as cursor * @param key a char* * @param data a void** output * @hideinitializer * - * \note An example of usage: - * \code + * @note An example of usage: + * @code xbt_dict_cursor_t cursor = NULL; char *key; char *data; @@ -157,7 +157,7 @@ char *data; xbt_dict_foreach(head, cursor, key, data) { printf("Key %s with data %s\n",key,data); } -\endcode +@endcode */ # define xbt_dict_foreach(dict,cursor,key,data) \ for (cursor=NULL, xbt_dict_cursor_first((dict),&(cursor)) ; \ diff --git a/include/xbt/dynar.h b/include/xbt/dynar.h index 095187f380..8bd1d09fd7 100644 --- a/include/xbt/dynar.h +++ b/include/xbt/dynar.h @@ -16,52 +16,52 @@ SG_BEGIN_DECL() /** @addtogroup XBT_dynar - * @brief DynArr are dynamically sized vector which may contain any type of variables. - * - * These are the SimGrid version of the dynamically size arrays, which all C programmer recode one day or another. - * - * For performance concerns, the content of DynArr must be homogeneous (in contrary to dictionnaries -- see the - * \ref XBT_dict section). You thus have to provide the function which will be used to free the content at - * structure creation (of type void_f_pvoid_t). - * - * @deprecated If you are using C++, you might want to use `std::vector` instead. - * - * \section XBT_dynar_exscal Example with scalar - * \dontinclude dynar.cpp - * - * \skip Vars_decl - * \skip dyn - * \until iptr - * \skip Populate_ints - * \skip dyn - * \until end_of_traversal - * \skip shifting - * \skip val - * \until xbt_dynar_free - * - * \section XBT_dynar_exptr Example with pointed data - * - * \skip test_dynar_string - * \skip dynar_t - * \until s2 - * \skip Populate_str - * \skip dyn - * \until } - * \skip macro - * \until dynar_free - * \skip end_of_doxygen - * \until } - * - * Note that if you use dynars to store pointed data, the xbt_dynar_search(), xbt_dynar_search_or_negative() and - * xbt_dynar_member() won't be for you. Instead of comparing your pointed elements, they compare the pointer to them. - * See the documentation of xbt_dynar_search() for more info. - */ + * @brief DynArr are dynamically sized vector which may contain any type of variables. + * + * These are the SimGrid version of the dynamically size arrays, which all C programmer recode one day or another. + * + * For performance concerns, the content of DynArr must be homogeneous (in contrary to dictionnaries -- see the + * @ref XBT_dict section). You thus have to provide the function which will be used to free the content at + * structure creation (of type void_f_pvoid_t). + * + * @deprecated If you are using C++, you might want to use `std::vector` instead. + * + * @section XBT_dynar_exscal Example with scalar + * @dontinclude dynar.cpp + * + * @skip Vars_decl + * @skip dyn + * @until iptr + * @skip Populate_ints + * @skip dyn + * @until end_of_traversal + * @skip shifting + * @skip val + * @until xbt_dynar_free + * + * @section XBT_dynar_exptr Example with pointed data + * + * @skip test_dynar_string + * @skip dynar_t + * @until s2 + * @skip Populate_str + * @skip dyn + * @until } + * @skip macro + * @until dynar_free + * @skip end_of_doxygen + * @until } + * + * Note that if you use dynars to store pointed data, the xbt_dynar_search(), xbt_dynar_search_or_negative() and + * xbt_dynar_member() won't be for you. Instead of comparing your pointed elements, they compare the pointer to them. + * See the documentation of xbt_dynar_search() for more info. + */ /** @defgroup XBT_dynar_cons Dynar constructor and destructor * @ingroup XBT_dynar * * @{ */ - /** \brief Dynar data type (opaque type) */ +/** @brief Dynar data type (opaque type) */ typedef struct xbt_dynar_s *xbt_dynar_t; XBT_PUBLIC xbt_dynar_t xbt_dynar_new(const unsigned long elm_size, void_f_pvoid_t const free_f); @@ -190,12 +190,12 @@ XBT_PUBLIC void* xbt_dynar_pop_ptr(xbt_dynar_t const dynar); XBT_PUBLIC void xbt_dynar_cursor_rm(xbt_dynar_t dynar, unsigned int* const cursor); /* - * \warning DO NOT USE THIS STRUCTURE DIRECTLY! Instead, use the public interface: + * @warning DO NOT USE THIS STRUCTURE DIRECTLY! Instead, use the public interface: * This was made public to allow: * - the inlining of the foreach elements * - sending such beasts over the network * - * \see xbt_dynar_length() + * @see xbt_dynar_length() */ typedef struct xbt_dynar_s { unsigned long size; @@ -229,14 +229,14 @@ static inline int _xbt_dynar_cursor_get(const xbt_dynar_t dynar, unsigned int id * @hideinitializer * * Here is an example of usage: - * \code + * @code xbt_dynar_t dyn; unsigned int cpt; string *str; xbt_dynar_foreach (dyn,cpt,str) { printf("Seen %s\n",str); } -\endcode +@endcode * * Note that underneath, that's a simple for loop with no real black magic involved. It's perfectly safe to interrupt * a foreach with a break or a return statement. diff --git a/include/xbt/log.h b/include/xbt/log.h index b518d99544..6c7991f5c3 100644 --- a/include/xbt/log.h +++ b/include/xbt/log.h @@ -10,15 +10,16 @@ * */ -/** \defgroup XBT_log_cats Existing log categories - * \ingroup XBT_log - * \brief (automatically extracted) +/** @defgroup XBT_log_cats Existing log categories + * @ingroup XBT_log + * @brief (automatically extracted) * * This is the list of all existing log categories in SimGrid. * This list is automatically extracted from the source code by the tools/doxygen/xbt_log_extract_hierarchy.pl utility. * * It should thus contain every categories that are defined in the SimGrid library. - * If you want to see the one defined in your code in addition, provide `--help-logs` on the command line of your simulator. + * If you want to see the one defined in your code in addition, provide `--help-logs` on the command line of your + * simulator. */ /* XBT_LOG_MAYDAY: define this to replace the logging facilities with basic @@ -32,11 +33,11 @@ #include /* NULL */ #include SG_BEGIN_DECL() -/**\brief Log priorities - * \ingroup XBT_log +/**@brief Log priorities + * @ingroup XBT_log * * The different existing priorities. -*/ + */ typedef enum { //! @cond xbt_log_priority_none = 0, /** used internally (don't poke with)*/ @@ -127,23 +128,23 @@ typedef enum { } /** - * \ingroup XBT_log - * \param catName name of new category - * \param parent father of the new category in the tree - * \param desc string describing the purpose of this category - * \hideinitializer + * @ingroup XBT_log + * @param catName name of new category + * @param parent father of the new category in the tree + * @param desc string describing the purpose of this category + * @hideinitializer * * Defines a new subcategory of the parent. */ #define XBT_LOG_NEW_SUBCATEGORY(catName, parent, desc) \ XBT_LOG_EXTERNAL_CATEGORY(parent); \ - XBT_LOG_NEW_SUBCATEGORY_helper(catName, parent, desc) \ + XBT_LOG_NEW_SUBCATEGORY_helper(catName, parent, desc) /** - * \ingroup XBT_log - * \param catName name of new category - * \param desc string describing the purpose of this category - * \hideinitializer + * @ingroup XBT_log + * @param catName name of new category + * @param desc string describing the purpose of this category + * @hideinitializer * * Creates a new subcategory of the root category. */ @@ -151,9 +152,9 @@ typedef enum { XBT_LOG_NEW_SUBCATEGORY_helper(catName, XBT_LOG_ROOT_CAT, desc) /** - * \ingroup XBT_log - * \param cname name of the cat - * \hideinitializer + * @ingroup XBT_log + * @param cname name of the cat + * @hideinitializer * * Indicates which category is the default one. */ @@ -166,10 +167,10 @@ typedef enum { #endif /** - * \ingroup XBT_log - * \param cname name of the cat - * \param desc string describing the purpose of this category - * \hideinitializer + * @ingroup XBT_log + * @param cname name of the cat + * @param desc string describing the purpose of this category + * @hideinitializer * * Creates a new subcategory of the root category and makes it the default (used by macros that don't explicitly * specify a category). @@ -179,11 +180,11 @@ typedef enum { XBT_LOG_DEFAULT_CATEGORY(cname) /** - * \ingroup XBT_log - * \param cname name of the cat - * \param parent name of the parent - * \param desc string describing the purpose of this category - * \hideinitializer + * @ingroup XBT_log + * @param cname name of the cat + * @param parent name of the parent + * @param desc string describing the purpose of this category + * @hideinitializer * * Creates a new subcategory of the parent category and makes it the default * (used by macros that don't explicitly specify a category). @@ -193,9 +194,9 @@ typedef enum { XBT_LOG_DEFAULT_CATEGORY(cname) /** - * \ingroup XBT_log - * \param cname name of the cat - * \hideinitializer + * @ingroup XBT_log + * @param cname name of the cat + * @hideinitializer * * Indicates that a category you'll use in this file (e.g., to get subcategories of it) really lives in another file. */ @@ -204,9 +205,9 @@ typedef enum { extern s_xbt_log_category_t _XBT_LOGV(cname) /** - * \ingroup XBT_log - * \param cname name of the cat - * \hideinitializer + * @ingroup XBT_log + * @param cname name of the cat + * @hideinitializer * * Indicates that the default category of this file was declared in another file. */ @@ -257,35 +258,35 @@ struct xbt_log_event_s { }; /** - * \ingroup XBT_log_implem - * \param cat the category (not only its name, but the variable) - * \param thresholdPriority the priority + * @ingroup XBT_log_implem + * @param cat the category (not only its name, but the variable) + * @param thresholdPriority the priority * * Programatically alters a category's threshold priority (don't use). */ XBT_PUBLIC void xbt_log_threshold_set(xbt_log_category_t cat, e_xbt_log_priority_t thresholdPriority); /** - * \ingroup XBT_log_implem - * \param cat the category (not only its name, but the variable) - * \param app the appender + * @ingroup XBT_log_implem + * @param cat the category (not only its name, but the variable) + * @param app the appender * * Programatically sets the category's appender. (the preferred interface is through xbt_log_control_set()) */ XBT_PUBLIC void xbt_log_appender_set(xbt_log_category_t cat, xbt_log_appender_t app); /** - * \ingroup XBT_log_implem - * \param cat the category (not only its name, but the variable) - * \param lay the layout + * @ingroup XBT_log_implem + * @param cat the category (not only its name, but the variable) + * @param lay the layout * * Programatically sets the category's layout. (the preferred interface is through xbt_log_control_set()) */ XBT_PUBLIC void xbt_log_layout_set(xbt_log_category_t cat, xbt_log_layout_t lay); /** - * \ingroup XBT_log_implem - * \param cat the category (not only its name, but the variable) - * \param additivity whether logging actions must be passed to parent. + * @ingroup XBT_log_implem + * @param cat the category (not only its name, but the variable) + * @param additivity whether logging actions must be passed to parent. * * Programatically sets whether the logging actions must be passed to the parent category. * (the preferred interface is through xbt_log_control_set()) @@ -326,10 +327,10 @@ extern xbt_log_layout_t xbt_log_default_layout; /* ********************** */ /** - * \ingroup XBT_log - * \param catName name of the category - * \param priority minimal priority to be enabled to return true (must be #e_xbt_log_priority_t) - * \hideinitializer + * @ingroup XBT_log + * @param catName name of the category + * @param priority minimal priority to be enabled to return true (must be #e_xbt_log_priority_t) + * @hideinitializer * * Returns true if the given priority is enabled for the category. * If you have expensive expressions that are computed outside of the log command and used only within it, you should @@ -405,8 +406,8 @@ extern xbt_log_layout_t xbt_log_default_layout; /** @ingroup XBT_log * @hideinitializer - * \param categ the category on which to log - * \param ... the format string and its arguments + * @param categ the category on which to log + * @param ... the format string and its arguments * @brief Log an event at the DEBUG priority on the specified category with these args. */ #define XBT_CDEBUG(categ, ...) \ @@ -511,7 +512,7 @@ extern xbt_log_layout_t xbt_log_default_layout; /** @ingroup XBT_log * @hideinitializer - * \param ... the format string and its arguments + * @param ... the format string and its arguments * @brief Log an event at the DEBUG priority on the default category with these args. */ #define XBT_DEBUG(...) \ diff --git a/include/xbt/mallocator.h b/include/xbt/mallocator.h index 7b76ed8fcc..3a390b953e 100644 --- a/include/xbt/mallocator.h +++ b/include/xbt/mallocator.h @@ -19,7 +19,7 @@ SG_BEGIN_DECL() * This section describes the API to a mallocator. * A mallocator allows you to recycle the objects you don't need anymore instead of freeing them. A mallocator is a * stack which stores the unused objects or a given type. If you often need to malloc() / free() objects of a certain - * type, you should use a mallocator and call \a xbt_mallocator_get() and \a xbt_mallocator_release() instead of + * type, you should use a mallocator and call @a xbt_mallocator_get() and @a xbt_mallocator_release() instead of * malloc() and free(). * * When you release an object, it is not freed but it is stored into the mallocator (unless the mallocator is full). @@ -31,7 +31,7 @@ SG_BEGIN_DECL() * * @{ */ -/** \brief Mallocator data type (opaque structure) */ +/** @brief Mallocator data type (opaque structure) */ typedef struct s_xbt_mallocator *xbt_mallocator_t; XBT_PUBLIC xbt_mallocator_t xbt_mallocator_new(int size, pvoid_f_void_t new_f, void_f_pvoid_t free_f, void_f_pvoid_t reset_f); diff --git a/include/xbt/parmap.h b/include/xbt/parmap.h index d8c32f8bda..69cac53e61 100644 --- a/include/xbt/parmap.h +++ b/include/xbt/parmap.h @@ -9,20 +9,20 @@ #ifndef XBT_PARMAP_H #define XBT_PARMAP_H -/** \addtogroup XBT_parmap - * \ingroup XBT_misc - * \brief Parallel map. - * - * A function is applied to all elements of a std::vector in parallel with n worker threads. The worker threads are - * persistent until the destruction of the parmap. - * - * If there are more than n elements in the vector, the worker threads are allowed to fetch themselves remaining work - * with method next() and execute it. - * - * \{ - */ +/** @addtogroup XBT_parmap + * @ingroup XBT_misc + * @brief Parallel map. + * + * A function is applied to all elements of a std::vector in parallel with n worker threads. The worker threads are + * persistent until the destruction of the parmap. + * + * If there are more than n elements in the vector, the worker threads are allowed to fetch themselves remaining work + * with method next() and execute it. + * + * @{ + */ -/** \brief Synchronization mode of the worker threads of a parmap. */ +/** @brief Synchronization mode of the worker threads of a parmap. */ typedef enum { XBT_PARMAP_POSIX, /**< use POSIX synchronization primitives */ XBT_PARMAP_FUTEX, /**< use Linux futex system call */ @@ -30,6 +30,6 @@ typedef enum { XBT_PARMAP_DEFAULT /**< futex if available, posix otherwise */ } e_xbt_parmap_mode_t; -/** \} */ +/** @} */ #endif diff --git a/include/xbt/synchro.h b/include/xbt/synchro.h index 68d0ee5a6a..a4923d257f 100644 --- a/include/xbt/synchro.h +++ b/include/xbt/synchro.h @@ -38,8 +38,8 @@ XBT_PUBLIC void xbt_mutex_acquire(xbt_mutex_t mutex); /** @brief Tries to block onto the given mutex variable * Tries to lock a mutex, return 1 if the mutex is unlocked, else 0. * This function does not block and wait for the mutex to be unlocked. - * \param mutex The mutex - * \return 1 - mutex free, 0 - mutex used + * @param mutex The mutex + * @return 1 - mutex free, 0 - mutex used */ XBT_PUBLIC int xbt_mutex_try_acquire(xbt_mutex_t mutex); diff --git a/include/xbt/sysdep.h b/include/xbt/sysdep.h index 7bcc04b738..86d62bb7a7 100644 --- a/include/xbt/sysdep.h +++ b/include/xbt/sysdep.h @@ -34,7 +34,7 @@ XBT_ATTRIB_NORETURN XBT_PUBLIC void xbt_abort(void); /** * @brief Kill the program with an error message - * \param ... a format string and its arguments + * @param ... a format string and its arguments * * Things are so messed up that the only thing to do now, is to stop the program. * @@ -54,7 +54,7 @@ XBT_LOG_EXTERNAL_CATEGORY(xbt); #endif /** @addtogroup XBT_syscall - * @brief Malloc and associated functions, killing the program on error (with \ref XBT_ex) + * @brief Malloc and associated functions, killing the program on error (with @ref XBT_ex) * * @{ */ diff --git a/include/xbt/xbt_os_thread.h b/include/xbt/xbt_os_thread.h index a3355148cf..9c63fa18e3 100644 --- a/include/xbt/xbt_os_thread.h +++ b/include/xbt/xbt_os_thread.h @@ -28,7 +28,7 @@ typedef pthread_key_t xbt_os_thread_key_t; XBT_PUBLIC int xbt_os_get_numcores(void); -/** \brief Thread data type (opaque structure) */ +/** @brief Thread data type (opaque structure) */ typedef struct xbt_os_thread_ *xbt_os_thread_t; XBT_PUBLIC xbt_os_thread_t xbt_os_thread_create(const char* name, pvoid_f_pvoid_t start_routine, void* param, void* data); @@ -50,14 +50,14 @@ XBT_PUBLIC void xbt_os_thread_setguardsize(int guard_size); XBT_PUBLIC int xbt_os_thread_bind(xbt_os_thread_t thread, int core); XBT_PUBLIC int xbt_os_thread_atfork(void (*prepare)(void), void (*parent)(void), void (*child)(void)); -/** \brief Thread mutex data type (opaque structure) */ +/** @brief Thread mutex data type (opaque structure) */ typedef struct xbt_os_mutex_ *xbt_os_mutex_t; XBT_PUBLIC xbt_os_mutex_t xbt_os_mutex_init(void); XBT_PUBLIC void xbt_os_mutex_acquire(xbt_os_mutex_t mutex); XBT_PUBLIC void xbt_os_mutex_release(xbt_os_mutex_t mutex); XBT_PUBLIC void xbt_os_mutex_destroy(xbt_os_mutex_t mutex); -/** \brief Thread condition data type (opaque structure) */ +/** @brief Thread condition data type (opaque structure) */ typedef struct xbt_os_cond_ *xbt_os_cond_t; XBT_PUBLIC xbt_os_cond_t xbt_os_cond_init(void); XBT_PUBLIC void xbt_os_cond_wait(xbt_os_cond_t cond, xbt_os_mutex_t mutex); @@ -65,7 +65,7 @@ XBT_PUBLIC void xbt_os_cond_signal(xbt_os_cond_t cond); XBT_PUBLIC void xbt_os_cond_broadcast(xbt_os_cond_t cond); XBT_PUBLIC void xbt_os_cond_destroy(xbt_os_cond_t cond); -/** \brief Semaphore data type (opaque structure) */ +/** @brief Semaphore data type (opaque structure) */ typedef struct xbt_os_sem_ *xbt_os_sem_t; XBT_PUBLIC xbt_os_sem_t xbt_os_sem_init(unsigned int value); XBT_PUBLIC void xbt_os_sem_acquire(xbt_os_sem_t sem); diff --git a/src/bindings/java/org/simgrid/msg/VM.java b/src/bindings/java/org/simgrid/msg/VM.java index 8a9b10868f..8e98ed575e 100644 --- a/src/bindings/java/org/simgrid/msg/VM.java +++ b/src/bindings/java/org/simgrid/msg/VM.java @@ -134,14 +134,14 @@ public class VM extends Host { /** Immediately suspend the execution of all processes within the given VM * - * No suspension cost occurs. If you want to simulate this too, you want to use a \ref File.write() before or + * No suspension cost occurs. If you want to simulate this too, you want to use a @ref File.write() before or * after, depending on the exact semantic of VM suspend to you. */ public native void suspend(); /** Immediately resumes the execution of all processes within the given VM * - * No resume cost occurs. If you want to simulate this too, you want to use a \ref File.read() before or after, + * No resume cost occurs. If you want to simulate this too, you want to use a @ref File.read() before or after, * depending on the exact semantic of VM resume to you. */ public native void resume(); diff --git a/src/bindings/lua/lua_debug.cpp b/src/bindings/lua/lua_debug.cpp index 120e460519..854e1adb4a 100644 --- a/src/bindings/lua/lua_debug.cpp +++ b/src/bindings/lua/lua_debug.cpp @@ -169,13 +169,13 @@ void sglua_stack_dump(lua_State* L, const char* msg) } /** - * \brief Like luaL_checkudata, with additional debug logs. + * @brief Like luaL_checkudata, with additional debug logs. * * This function is for debugging purposes only. * - * \param L a lua state - * \param ud index of the userdata to check in the stack - * \param tname key of the metatable of this userdata in the registry + * @param L a lua state + * @param ud index of the userdata to check in the stack + * @param tname key of the metatable of this userdata in the registry */ void* sglua_checkudata_debug(lua_State* L, int ud, const char* tname) { diff --git a/src/bindings/lua/lua_host.cpp b/src/bindings/lua/lua_host.cpp index 8f7cb8640f..02b55834fe 100644 --- a/src/bindings/lua/lua_host.cpp +++ b/src/bindings/lua/lua_host.cpp @@ -19,9 +19,9 @@ XBT_LOG_NEW_DEFAULT_CATEGORY(lua_host, "Lua Host module"); /** @brief Ensures that the pointed stack value is an host userdatum and returns it. * - * \param L a Lua state - * \param index an index in the Lua stack - * \return the C host corresponding to this Lua host + * @param L a Lua state + * @param index an index in the Lua stack + * @return the C host corresponding to this Lua host */ sg_host_t sglua_check_host(lua_State * L, int index) { @@ -38,10 +38,10 @@ sg_host_t sglua_check_host(lua_State * L, int index) } /** - * \brief Returns a host given its name. This is a lua function. + * @brief Returns a host given its name. This is a lua function. * - * \param L a Lua state - * \return number of values returned to Lua + * @param L a Lua state + * @return number of values returned to Lua * * - Argument 1 (string): name of a host * - Return value (host): the corresponding host will be pushed onto the stack @@ -65,9 +65,9 @@ static int l_host_get_by_name(lua_State * L) } /** - * \brief Returns the name of a host. - * \param L a Lua state - * \return number of values returned to Lua + * @brief Returns the name of a host. + * @param L a Lua state + * @return number of values returned to Lua * * - Argument 1 (host): a host * - Return value (string): name of this host @@ -80,9 +80,9 @@ static int l_host_get_name(lua_State * L) } /** - * \brief Returns the number of existing hosts. - * \param L a Lua state - * \return number of values returned to Lua + * @brief Returns the number of existing hosts. + * @param L a Lua state + * @return number of values returned to Lua * * - Return value (number): number of hosts */ @@ -95,9 +95,9 @@ static int l_host_number(lua_State * L) } /** - * \brief Returns the host given its index. - * \param L a Lua state - * \return number of values returned to Lua + * @brief Returns the host given its index. + * @param L a Lua state + * @return number of values returned to Lua * * - Argument 1 (number): an index (1 is the first) * - Return value (host): the host at this index @@ -118,9 +118,9 @@ static int l_host_at(lua_State * L) } /** - * \brief Returns the value of a host property. - * \param L a Lua state - * \return number of values returned to Lua + * @brief Returns the value of a host property. + * @param L a Lua state + * @return number of values returned to Lua * * - Argument 1 (host): a host * - Argument 2 (string): name of the property to get @@ -135,9 +135,9 @@ static int l_host_get_property_value(lua_State * L) } /** - * \brief Destroys a host. - * \param L a Lua state - * \return number of values returned to Lua + * @brief Destroys a host. + * @param L a Lua state + * @return number of values returned to Lua * * - Argument 1 (host): the host to destroy */ @@ -161,9 +161,9 @@ static const luaL_Reg host_functions[] = { }; /** - * \brief Returns a string representation of a host. - * \param L a Lua state - * \return number of values returned to Lua + * @brief Returns a string representation of a host. + * @param L a Lua state + * @return number of values returned to Lua * * - Argument 1 (userdata): a host * - Return value (string): a string describing this host @@ -180,11 +180,11 @@ static const luaL_Reg host_meta[] = { }; /** - * \brief Registers the host functions into the table simgrid.host. + * @brief Registers the host functions into the table simgrid.host. * * Also initialize the metatable of the host userdata type. * - * \param L a lua state + * @param L a lua state */ void sglua_register_host_functions(lua_State* L) { diff --git a/src/bindings/lua/lua_platf.cpp b/src/bindings/lua/lua_platf.cpp index 1b8431dce1..50df71d1d5 100644 --- a/src/bindings/lua/lua_platf.cpp +++ b/src/bindings/lua/lua_platf.cpp @@ -523,8 +523,8 @@ int console_host_set_property(lua_State *L) { } /** - * \brief Registers the platform functions into the table simgrid.platf. - * \param L a lua state + * @brief Registers the platform functions into the table simgrid.platf. + * @param L a lua state */ void sglua_register_platf_functions(lua_State* L) { diff --git a/src/bindings/lua/simgrid_lua.cpp b/src/bindings/lua/simgrid_lua.cpp index 963c10be15..6ca44badce 100644 --- a/src/bindings/lua/simgrid_lua.cpp +++ b/src/bindings/lua/simgrid_lua.cpp @@ -22,9 +22,9 @@ extern "C" int luaopen_simgrid(lua_State* L); /* ********************************************************************************* */ /** - * \brief Prints a log string with debug level. - * \param L a Lua state - * \return number of values returned to Lua + * @brief Prints a log string with debug level. + * @param L a Lua state + * @return number of values returned to Lua * * - Argument 1 (string): the text to print */ @@ -36,9 +36,9 @@ static int debug(lua_State* L) { } /** - * \brief Prints a log string with info level. - * \param L a Lua state - * \return number of values returned to Lua + * @brief Prints a log string with info level. + * @param L a Lua state + * @return number of values returned to Lua * * - Argument 1 (string): the text to print */ @@ -110,8 +110,8 @@ static const luaL_Reg simgrid_functions[] = { /* ********************************************************************************* */ /** - * \brief Makes the core functions available to the Lua world. - * \param L a Lua world + * @brief Makes the core functions available to the Lua world. + * @param L a Lua world */ static void sglua_register_core_functions(lua_State *L) { @@ -122,12 +122,12 @@ static void sglua_register_core_functions(lua_State *L) } /** - * \brief Opens the simgrid Lua module. + * @brief Opens the simgrid Lua module. * * This function is called automatically by the Lua interpreter when some * Lua code requires the "simgrid" module. * - * \param L the Lua state + * @param L the Lua state */ int luaopen_simgrid(lua_State *L) { diff --git a/src/include/surf/surf.hpp b/src/include/surf/surf.hpp index 6c7e702508..fc415ec81e 100644 --- a/src/include/surf/surf.hpp +++ b/src/include/surf/surf.hpp @@ -8,20 +8,20 @@ #include "simgrid/forward.h" -/** \ingroup SURF_models - * \brief The CPU model object for the physical machine layer +/** @ingroup SURF_models + * @brief The CPU model object for the physical machine layer */ XBT_PUBLIC_DATA simgrid::surf::CpuModel* surf_cpu_model_pm; -/** \ingroup SURF_models - * \brief The CPU model object for the virtual machine layer +/** @ingroup SURF_models + * @brief The CPU model object for the virtual machine layer */ XBT_PUBLIC_DATA simgrid::surf::CpuModel* surf_cpu_model_vm; XBT_PUBLIC_DATA simgrid::surf::StorageModel* surf_storage_model; -/** \ingroup SURF_models - * \brief The host model +/** @ingroup SURF_models + * @brief The host model * * Note that when you create an API on top of SURF, the host model should be the only one you use * because depending on the platform model, the network model and the CPU model may not exist. @@ -31,29 +31,29 @@ XBT_PUBLIC_DATA simgrid::surf::HostModel* surf_host_model; /*** SURF Globals **************************/ -/** \ingroup SURF_simulation - * \brief Initialize SURF - * \param argc argument number - * \param argv arguments +/** @ingroup SURF_simulation + * @brief Initialize SURF + * @param argc argument number + * @param argv arguments * * This function has to be called to initialize the common structures. Then you will have to create the environment by * calling e.g. surf_host_model_init_CM02() * - * \see surf_host_model_init_CM02(), surf_host_model_init_compound(), surf_exit() + * @see surf_host_model_init_CM02(), surf_host_model_init_compound(), surf_exit() */ XBT_PUBLIC void surf_init(int* argc, char** argv); /* initialize common structures */ -/** \ingroup SURF_simulation - * \brief Finish simulation initialization +/** @ingroup SURF_simulation + * @brief Finish simulation initialization * * This function must be called before the first call to surf_solve() */ XBT_PUBLIC void surf_presolve(); -/** \ingroup SURF_simulation - * \brief Performs a part of the simulation - * \param max_date Maximum date to update the simulation to, or -1 - * \return the elapsed time, or -1.0 if no event could be executed +/** @ingroup SURF_simulation + * @brief Performs a part of the simulation + * @param max_date Maximum date to update the simulation to, or -1 + * @return the elapsed time, or -1.0 if no event could be executed * * This function execute all possible events, update the action states and returns the time elapsed. * When you call execute or communicate on a model, the corresponding actions are not executed immediately but only @@ -62,19 +62,19 @@ XBT_PUBLIC void surf_presolve(); */ XBT_PUBLIC double surf_solve(double max_date); -/** \ingroup SURF_simulation - * \brief Return the current time +/** @ingroup SURF_simulation + * @brief Return the current time * * Return the current time in millisecond. */ XBT_PUBLIC double surf_get_clock(); -/** \ingroup SURF_simulation - * \brief Exit SURF +/** @ingroup SURF_simulation + * @brief Exit SURF * * Clean everything. * - * \see surf_init() + * @see surf_init() */ XBT_PUBLIC void surf_exit(); diff --git a/src/include/xbt/parmap.hpp b/src/include/xbt/parmap.hpp index 1bde553e5c..18c0392b31 100644 --- a/src/include/xbt/parmap.hpp +++ b/src/include/xbt/parmap.hpp @@ -24,11 +24,11 @@ XBT_LOG_EXTERNAL_CATEGORY(xbt_parmap); namespace simgrid { namespace xbt { -/** \addtogroup XBT_parmap - * \ingroup XBT_misc - * \brief Parallel map class - * \{ - */ +/** @addtogroup XBT_parmap + * @ingroup XBT_misc + * @brief Parallel map class + * @{ + */ template class Parmap { public: Parmap(unsigned num_workers, e_xbt_parmap_mode_t mode); @@ -42,7 +42,7 @@ private: enum Flag { PARMAP_WORK, PARMAP_DESTROY }; /** - * \brief Thread data transmission structure + * @brief Thread data transmission structure */ class ThreadData { public: @@ -52,36 +52,36 @@ private: }; /** - * \brief Synchronization object (different specializations). + * @brief Synchronization object (different specializations). */ class Synchro { public: explicit Synchro(Parmap& parmap) : parmap(parmap) {} virtual ~Synchro() = default; /** - * \brief Wakes all workers and waits for them to finish the tasks. + * @brief Wakes all workers and waits for them to finish the tasks. * * This function is called by the controller thread. */ virtual void master_signal() = 0; /** - * \brief Starts the parmap: waits for all workers to be ready and returns. + * @brief Starts the parmap: waits for all workers to be ready and returns. * * This function is called by the controller thread. */ virtual void master_wait() = 0; /** - * \brief Ends the parmap: wakes the controller thread when all workers terminate. + * @brief Ends the parmap: wakes the controller thread when all workers terminate. * * This function is called by all worker threads when they end (not including the controller). */ virtual void worker_signal() = 0; /** - * \brief Waits for some work to process. + * @brief Waits for some work to process. * * This function is called by each worker thread (not including the controller) when it has no more work to do. * - * \param round the expected round number + * @param round the expected round number */ virtual void worker_wait(unsigned) = 0; @@ -145,9 +145,9 @@ private: }; /** - * \brief Creates a parallel map object - * \param num_workers number of worker threads to create - * \param mode how to synchronize the worker threads + * @brief Creates a parallel map object + * @param num_workers number of worker threads to create + * @param mode how to synchronize the worker threads */ template Parmap::Parmap(unsigned num_workers, e_xbt_parmap_mode_t mode) { @@ -179,7 +179,7 @@ template Parmap::Parmap(unsigned num_workers, e_xbt_parmap_mode_ } /** - * \brief Destroys a parmap + * @brief Destroys a parmap */ template Parmap::~Parmap() { @@ -194,9 +194,9 @@ template Parmap::~Parmap() } /** - * \brief Applies a list of tasks in parallel. - * \param fun the function to call in parallel - * \param data each element of this vector will be passed as an argument to fun + * @brief Applies a list of tasks in parallel. + * @param fun the function to call in parallel + * @param data each element of this vector will be passed as an argument to fun */ template void Parmap::apply(void (*fun)(T), const std::vector& data) { @@ -211,11 +211,11 @@ template void Parmap::apply(void (*fun)(T), const std::vector } /** - * \brief Returns a next task to process. + * @brief Returns a next task to process. * * Worker threads call this function to get more work. * - * \return the next task to process, or throws a std::out_of_range exception if there is no more work + * @return the next task to process, or throws a std::out_of_range exception if there is no more work */ template boost::optional Parmap::next() { @@ -227,7 +227,7 @@ template boost::optional Parmap::next() } /** - * \brief Main work loop: applies fun to elements in turn. + * @brief Main work loop: applies fun to elements in turn. */ template void Parmap::work() { @@ -241,7 +241,7 @@ template void Parmap::work() /** * Get a synchronization object for given mode. - * \param mode the synchronization mode + * @param mode the synchronization mode */ template typename Parmap::Synchro* Parmap::new_synchro(e_xbt_parmap_mode_t mode) { @@ -274,7 +274,7 @@ template typename Parmap::Synchro* Parmap::new_synchro(e_xbt_ } /** - * \brief Main function of a worker thread. + * @brief Main function of a worker thread. */ template void* Parmap::worker_main(void* arg) { @@ -438,7 +438,7 @@ template void Parmap::BusyWaitSynchro::worker_wait(unsigned roun } } -/** \} */ +/** @} */ } } diff --git a/src/instr/instr_interface.cpp b/src/instr/instr_interface.cpp index 67cd9306c5..5881002392 100644 --- a/src/instr/instr_interface.cpp +++ b/src/instr/instr_interface.cpp @@ -34,8 +34,8 @@ static xbt_dynar_t instr_set_to_dynar(std::set* filter) return ret; } -/** \ingroup TRACE_category - * \brief Declare a new category with a random color. +/** @ingroup TRACE_category + * @brief Declare a new category with a random color. * * This function should be used to define a user category. The category can be used to differentiate the tasks that * are created during the simulation (for example, tasks from server1, server2, or request tasks, computation tasks, @@ -43,31 +43,31 @@ static xbt_dynar_t instr_set_to_dynar(std::set* filter) * task category. Tasks that do not belong to a category are not traced. The color for the category that is being * declared is random. This function has no effect if a category with the same name has been already declared. * - * See \ref outcomes_vizu for details on how to trace the (categorized) resource utilization. + * See @ref outcomes_vizu for details on how to trace the (categorized) resource utilization. * - * \param category The name of the new tracing category to be created. + * @param category The name of the new tracing category to be created. * - * \see TRACE_category_with_color, MSG_task_set_category, SD_task_set_category + * @see TRACE_category_with_color, MSG_task_set_category, SD_task_set_category */ void TRACE_category(const char *category) { TRACE_category_with_color (category, nullptr); } -/** \ingroup TRACE_category - * \brief Declare a new category with a color. +/** @ingroup TRACE_category + * @brief Declare a new category with a color. * * Same as #TRACE_category, but let user specify a color encoded as a RGB-like string with three floats from 0 to 1. * So, to specify a red color, pass "1 0 0" as color parameter. A light-gray color can be specified using "0.7 0.7 0.7" * as color. This function has no effect if a category with the same name has been already declared. * - * See \ref outcomes_vizu for details on how to trace the (categorized) resource utilization. + * See @ref outcomes_vizu for details on how to trace the (categorized) resource utilization. * - * \param category The name of the new tracing category to be created. - * \param color The color of the category (see \ref outcomes_vizu to + * @param category The name of the new tracing category to be created. + * @param color The color of the category (see @ref outcomes_vizu to * know how to correctly specify the color) * - * \see MSG_task_set_category, SD_task_set_category + * @see MSG_task_set_category, SD_task_set_category */ void TRACE_category_with_color (const char *category, const char *color) { @@ -102,17 +102,17 @@ void TRACE_category_with_color (const char *category, const char *color) instr_new_variable_type (category, final_color); } -/** \ingroup TRACE_category - * \brief Get declared categories +/** @ingroup TRACE_category + * @brief Get declared categories * * This function should be used to get categories that were already declared with #TRACE_category or with * #TRACE_category_with_color. * - * See \ref outcomes_vizu for details on how to trace the (categorized) resource utilization. + * See @ref outcomes_vizu for details on how to trace the (categorized) resource utilization. * - * \return A dynar with the declared categories, must be freed with xbt_dynar_free. + * @return A dynar with the declared categories, must be freed with xbt_dynar_free. * - * \see MSG_task_set_category, SD_task_set_category + * @see MSG_task_set_category, SD_task_set_category */ xbt_dynar_t TRACE_get_categories () { @@ -121,15 +121,15 @@ xbt_dynar_t TRACE_get_categories () return instr_set_to_dynar(&created_categories); } -/** \ingroup TRACE_mark - * \brief Declare a new type for tracing mark. +/** @ingroup TRACE_mark + * @brief Declare a new type for tracing mark. * * This function declares a new Paje event type in the trace file that can be used by simulators to declare * application-level marks. This function is independent of which API is used in SimGrid. * - * \param mark_type The name of the new type. + * @param mark_type The name of the new type. * - * \see TRACE_mark + * @see TRACE_mark */ void TRACE_declare_mark(const char *mark_type) { @@ -150,8 +150,8 @@ void TRACE_declare_mark(const char *mark_type) declared_marks.insert(mark_type); } -/** \ingroup TRACE_mark - * \brief Declare a new colored value for a previously declared mark type. +/** @ingroup TRACE_mark + * @brief Declare a new colored value for a previously declared mark type. * * This function declares a new colored value for a Paje event type in the trace file that can be used by simulators to * declare application-level marks. This function is independent of which API is used in SimGrid. The color needs to be @@ -159,11 +159,11 @@ void TRACE_declare_mark(const char *mark_type) * A light-gray color can be specified using "0.7 0.7 0.7" as color. If a nullptr color is provided, the color used will * be white ("1 1 1"). * - * \param mark_type The name of the new type. - * \param mark_value The name of the new value for this type. - * \param mark_color The color of the new value for this type. + * @param mark_type The name of the new type. + * @param mark_value The name of the new value for this type. + * @param mark_color The color of the new value for this type. * - * \see TRACE_mark + * @see TRACE_mark */ void TRACE_declare_mark_value_with_color (const char *mark_type, const char *mark_value, const char *mark_color) { @@ -189,17 +189,17 @@ void TRACE_declare_mark_value_with_color (const char *mark_type, const char *mar } } -/** \ingroup TRACE_mark - * \brief Declare a new value for a previously declared mark type. +/** @ingroup TRACE_mark + * @brief Declare a new value for a previously declared mark type. * * This function declares a new value for a Paje event type in the trace file that can be used by simulators to declare * application-level marks. This function is independent of which API is used in SimGrid. Calling this function is the - * same as calling \ref TRACE_declare_mark_value_with_color with a nullptr color. + * same as calling @ref TRACE_declare_mark_value_with_color with a nullptr color. * - * \param mark_type The name of the new type. - * \param mark_value The name of the new value for this type. + * @param mark_type The name of the new type. + * @param mark_value The name of the new value for this type. * - * \see TRACE_mark + * @see TRACE_mark */ void TRACE_declare_mark_value (const char *mark_type, const char *mark_value) { @@ -207,18 +207,18 @@ void TRACE_declare_mark_value (const char *mark_type, const char *mark_value) } /** - * \ingroup TRACE_mark - * \brief Create a new instance of a tracing mark type. + * @ingroup TRACE_mark + * @brief Create a new instance of a tracing mark type. * * This function creates a mark in the trace file. The first parameter had to be previously declared using * #TRACE_declare_mark, the second is the identifier for this mark instance. We recommend that the mark_value is a * unique value for the whole simulation. Nevertheless, this is not a strong requirement: the trace will be valid even * if there are multiple mark identifiers for the same trace. * - * \param mark_type The name of the type for which the new instance will belong. - * \param mark_value The name of the new instance mark. + * @param mark_type The name of the type for which the new instance will belong. + * @param mark_value The name of the new instance mark. * - * \see TRACE_declare_mark + * @see TRACE_declare_mark */ void TRACE_mark(const char *mark_type, const char *mark_value) { @@ -243,12 +243,12 @@ void TRACE_mark(const char *mark_type, const char *mark_value) } } -/** \ingroup TRACE_mark - * \brief Get declared marks +/** @ingroup TRACE_mark + * @brief Get declared marks * * This function should be used to get marks that were already declared with #TRACE_declare_mark. * - * \return A dynar with the declared marks, must be freed with xbt_dynar_free. + * @return A dynar with the declared marks, must be freed with xbt_dynar_free. */ xbt_dynar_t TRACE_get_marks () { @@ -311,16 +311,16 @@ static void instr_user_srcdst_variable(double time, const char *src, const char instr_user_variable(time, link->get_cname(), variable, father_type, value, what, nullptr, &user_link_variables); } -/** \ingroup TRACE_API - * \brief Creates a file with the topology of the platform file used for the simulator. +/** @ingroup TRACE_API + * @brief Creates a file with the topology of the platform file used for the simulator. * * The graph topology will have the following properties: all hosts, links and routers of the platform file are mapped * to graph nodes; routes are mapped to edges. * The platform's AS are not represented in the output. * - * \param filename The name of the file that will hold the graph. + * @param filename The name of the file that will hold the graph. * - * \return 1 of successful, 0 otherwise. + * @return 1 of successful, 0 otherwise. */ int TRACE_platform_graph_export_graphviz (const char *filename) { @@ -341,133 +341,133 @@ int TRACE_platform_graph_export_graphviz (const char *filename) */ /* for VM variables */ -/** \ingroup TRACE_user_variables - * \brief Declare a new user variable associated to VMs. +/** @ingroup TRACE_user_variables + * @brief Declare a new user variable associated to VMs. * * Declare a user variable that will be associated to VMs. A user vm variable can be used to trace user variables * such as the number of tasks in a VM, the number of clients in an application (for VMs), and so on. The color * associated to this new variable will be random. * - * \param variable The name of the new variable to be declared. + * @param variable The name of the new variable to be declared. * - * \see TRACE_vm_variable_declare_with_color + * @see TRACE_vm_variable_declare_with_color */ void TRACE_vm_variable_declare (const char *variable) { instr_user_variable(0, nullptr, variable, "VM", 0, InstrUserVariable::DECLARE, nullptr, &user_vm_variables); } -/** \ingroup TRACE_user_variables - * \brief Declare a new user variable associated to VMs with a color. +/** @ingroup TRACE_user_variables + * @brief Declare a new user variable associated to VMs with a color. * * Same as #TRACE_vm_variable_declare, but associated a color to the newly created user host variable. The color needs * to be a string with three numbers separated by spaces in the range [0,1]. * A light-gray color can be specified using "0.7 0.7 0.7" as color. * - * \param variable The name of the new variable to be declared. - * \param color The color for the new variable. + * @param variable The name of the new variable to be declared. + * @param color The color for the new variable. */ void TRACE_vm_variable_declare_with_color (const char *variable, const char *color) { instr_user_variable(0, nullptr, variable, "VM", 0, InstrUserVariable::DECLARE, color, &user_vm_variables); } -/** \ingroup TRACE_user_variables - * \brief Set the value of a variable of a host. +/** @ingroup TRACE_user_variables + * @brief Set the value of a variable of a host. * - * \param vm The name of the VM to be considered. - * \param variable The name of the variable to be considered. - * \param value The new value of the variable. + * @param vm The name of the VM to be considered. + * @param variable The name of the variable to be considered. + * @param value The new value of the variable. * - * \see TRACE_vm_variable_declare, TRACE_vm_variable_add, TRACE_vm_variable_sub + * @see TRACE_vm_variable_declare, TRACE_vm_variable_add, TRACE_vm_variable_sub */ void TRACE_vm_variable_set (const char *vm, const char *variable, double value) { TRACE_vm_variable_set_with_time (MSG_get_clock(), vm, variable, value); } -/** \ingroup TRACE_user_variables - * \brief Add a value to a variable of a VM. +/** @ingroup TRACE_user_variables + * @brief Add a value to a variable of a VM. * - * \param vm The name of the VM to be considered. - * \param variable The name of the variable to be considered. - * \param value The value to be added to the variable. + * @param vm The name of the VM to be considered. + * @param variable The name of the variable to be considered. + * @param value The value to be added to the variable. * - * \see TRACE_vm_variable_declare, TRACE_vm_variable_set, TRACE_vm_variable_sub + * @see TRACE_vm_variable_declare, TRACE_vm_variable_set, TRACE_vm_variable_sub */ void TRACE_vm_variable_add (const char *vm, const char *variable, double value) { TRACE_vm_variable_add_with_time (MSG_get_clock(), vm, variable, value); } -/** \ingroup TRACE_user_variables - * \brief Subtract a value from a variable of a VM. +/** @ingroup TRACE_user_variables + * @brief Subtract a value from a variable of a VM. * - * \param vm The name of the vm to be considered. - * \param variable The name of the variable to be considered. - * \param value The value to be subtracted from the variable. + * @param vm The name of the vm to be considered. + * @param variable The name of the variable to be considered. + * @param value The value to be subtracted from the variable. * - * \see TRACE_vm_variable_declare, TRACE_vm_variable_set, TRACE_vm_variable_add + * @see TRACE_vm_variable_declare, TRACE_vm_variable_set, TRACE_vm_variable_add */ void TRACE_vm_variable_sub (const char *vm, const char *variable, double value) { TRACE_vm_variable_sub_with_time (MSG_get_clock(), vm, variable, value); } -/** \ingroup TRACE_user_variables - * \brief Set the value of a variable of a VM at a given timestamp. +/** @ingroup TRACE_user_variables + * @brief Set the value of a variable of a VM at a given timestamp. * * Same as #TRACE_vm_variable_set, but let user specify the time used to trace it. Users can specify a time that * is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are * also traced. * - * \param time The timestamp to be used to tag this change of value. - * \param vm The name of the VM to be considered. - * \param variable The name of the variable to be considered. - * \param value The new value of the variable. + * @param time The timestamp to be used to tag this change of value. + * @param vm The name of the VM to be considered. + * @param variable The name of the variable to be considered. + * @param value The new value of the variable. * - * \see TRACE_vm_variable_declare, TRACE_vm_variable_add_with_time, TRACE_vm_variable_sub_with_time + * @see TRACE_vm_variable_declare, TRACE_vm_variable_add_with_time, TRACE_vm_variable_sub_with_time */ void TRACE_vm_variable_set_with_time (double time, const char *vm, const char *variable, double value) { instr_user_variable(time, vm, variable, "VM", value, InstrUserVariable::SET, nullptr, &user_vm_variables); } -/** \ingroup TRACE_user_variables - * \brief Add a value to a variable of a VM at a given timestamp. +/** @ingroup TRACE_user_variables + * @brief Add a value to a variable of a VM at a given timestamp. * * Same as #TRACE_vm_variable_add, but let user specify the time used to trace it. Users can specify a time that * is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are * also traced. * - * \param time The timestamp to be used to tag this change of value. - * \param vm The name of the VM to be considered. - * \param variable The name of the variable to be considered. - * \param value The value to be added to the variable. + * @param time The timestamp to be used to tag this change of value. + * @param vm The name of the VM to be considered. + * @param variable The name of the variable to be considered. + * @param value The value to be added to the variable. * - * \see TRACE_vm_variable_declare, TRACE_vm_variable_set_with_time, TRACE_vm_variable_sub_with_time + * @see TRACE_vm_variable_declare, TRACE_vm_variable_set_with_time, TRACE_vm_variable_sub_with_time */ void TRACE_vm_variable_add_with_time (double time, const char *vm, const char *variable, double value) { instr_user_variable(time, vm, variable, "VM", value, InstrUserVariable::ADD, nullptr, &user_vm_variables); } -/** \ingroup TRACE_user_variables - * \brief Subtract a value from a variable of a VM at a given timestamp. +/** @ingroup TRACE_user_variables + * @brief Subtract a value from a variable of a VM at a given timestamp. * * Same as #TRACE_vm_variable_sub, but let user specify the time used to trace it. Users can specify a time that * is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are * also traced. * - * \param time The timestamp to be used to tag this change of value. - * \param vm The name of the VM to be considered. - * \param variable The name of the variable to be considered. - * \param value The value to be subtracted from the variable. + * @param time The timestamp to be used to tag this change of value. + * @param vm The name of the VM to be considered. + * @param variable The name of the variable to be considered. + * @param value The value to be subtracted from the variable. * - * \see TRACE_vm_variable_declare, TRACE_vm_variable_set_with_time, TRACE_vm_variable_add_with_time + * @see TRACE_vm_variable_declare, TRACE_vm_variable_set_with_time, TRACE_vm_variable_add_with_time */ void TRACE_vm_variable_sub_with_time (double time, const char *vm, const char *variable, double value) { @@ -475,146 +475,146 @@ void TRACE_vm_variable_sub_with_time (double time, const char *vm, const char *v } /* for host variables */ -/** \ingroup TRACE_user_variables - * \brief Declare a new user variable associated to hosts. +/** @ingroup TRACE_user_variables + * @brief Declare a new user variable associated to hosts. * * Declare a user variable that will be associated to hosts. * A user host variable can be used to trace user variables such as the number of tasks in a server, the number of * clients in an application (for hosts), and so on. The color associated to this new variable will be random. * - * \param variable The name of the new variable to be declared. + * @param variable The name of the new variable to be declared. * - * \see TRACE_host_variable_declare_with_color + * @see TRACE_host_variable_declare_with_color */ void TRACE_host_variable_declare (const char *variable) { instr_user_variable(0, nullptr, variable, "HOST", 0, InstrUserVariable::DECLARE, nullptr, &user_host_variables); } -/** \ingroup TRACE_user_variables - * \brief Declare a new user variable associated to hosts with a color. +/** @ingroup TRACE_user_variables + * @brief Declare a new user variable associated to hosts with a color. * * Same as #TRACE_host_variable_declare, but associated a color to the newly created user host variable. The color * needs to be a string with three numbers separated by spaces in the range [0,1]. * A light-gray color can be specified using "0.7 0.7 0.7" as color. * - * \param variable The name of the new variable to be declared. - * \param color The color for the new variable. + * @param variable The name of the new variable to be declared. + * @param color The color for the new variable. */ void TRACE_host_variable_declare_with_color (const char *variable, const char *color) { instr_user_variable(0, nullptr, variable, "HOST", 0, InstrUserVariable::DECLARE, color, &user_host_variables); } -/** \ingroup TRACE_user_variables - * \brief Set the value of a variable of a host. +/** @ingroup TRACE_user_variables + * @brief Set the value of a variable of a host. * - * \param host The name of the host to be considered. - * \param variable The name of the variable to be considered. - * \param value The new value of the variable. + * @param host The name of the host to be considered. + * @param variable The name of the variable to be considered. + * @param value The new value of the variable. * - * \see TRACE_host_variable_declare, TRACE_host_variable_add, TRACE_host_variable_sub + * @see TRACE_host_variable_declare, TRACE_host_variable_add, TRACE_host_variable_sub */ void TRACE_host_variable_set (const char *host, const char *variable, double value) { TRACE_host_variable_set_with_time (MSG_get_clock(), host, variable, value); } -/** \ingroup TRACE_user_variables - * \brief Add a value to a variable of a host. +/** @ingroup TRACE_user_variables + * @brief Add a value to a variable of a host. * - * \param host The name of the host to be considered. - * \param variable The name of the variable to be considered. - * \param value The value to be added to the variable. + * @param host The name of the host to be considered. + * @param variable The name of the variable to be considered. + * @param value The value to be added to the variable. * - * \see TRACE_host_variable_declare, TRACE_host_variable_set, TRACE_host_variable_sub + * @see TRACE_host_variable_declare, TRACE_host_variable_set, TRACE_host_variable_sub */ void TRACE_host_variable_add (const char *host, const char *variable, double value) { TRACE_host_variable_add_with_time (MSG_get_clock(), host, variable, value); } -/** \ingroup TRACE_user_variables - * \brief Subtract a value from a variable of a host. +/** @ingroup TRACE_user_variables + * @brief Subtract a value from a variable of a host. * - * \param host The name of the host to be considered. - * \param variable The name of the variable to be considered. - * \param value The value to be subtracted from the variable. + * @param host The name of the host to be considered. + * @param variable The name of the variable to be considered. + * @param value The value to be subtracted from the variable. * - * \see TRACE_host_variable_declare, TRACE_host_variable_set, TRACE_host_variable_add + * @see TRACE_host_variable_declare, TRACE_host_variable_set, TRACE_host_variable_add */ void TRACE_host_variable_sub (const char *host, const char *variable, double value) { TRACE_host_variable_sub_with_time (MSG_get_clock(), host, variable, value); } -/** \ingroup TRACE_user_variables - * \brief Set the value of a variable of a host at a given timestamp. +/** @ingroup TRACE_user_variables + * @brief Set the value of a variable of a host at a given timestamp. * * Same as #TRACE_host_variable_set, but let user specify the time used to trace it. Users can specify a time that * is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are * also traced. * - * \param time The timestamp to be used to tag this change of value. - * \param host The name of the host to be considered. - * \param variable The name of the variable to be considered. - * \param value The new value of the variable. + * @param time The timestamp to be used to tag this change of value. + * @param host The name of the host to be considered. + * @param variable The name of the variable to be considered. + * @param value The new value of the variable. * - * \see TRACE_host_variable_declare, TRACE_host_variable_add_with_time, TRACE_host_variable_sub_with_time + * @see TRACE_host_variable_declare, TRACE_host_variable_add_with_time, TRACE_host_variable_sub_with_time */ void TRACE_host_variable_set_with_time (double time, const char *host, const char *variable, double value) { instr_user_variable(time, host, variable, "HOST", value, InstrUserVariable::SET, nullptr, &user_host_variables); } -/** \ingroup TRACE_user_variables - * \brief Add a value to a variable of a host at a given timestamp. +/** @ingroup TRACE_user_variables + * @brief Add a value to a variable of a host at a given timestamp. * * Same as #TRACE_host_variable_add, but let user specify the time used to trace it. Users can specify a time that * is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are * also traced. * - * \param time The timestamp to be used to tag this change of value. - * \param host The name of the host to be considered. - * \param variable The name of the variable to be considered. - * \param value The value to be added to the variable. + * @param time The timestamp to be used to tag this change of value. + * @param host The name of the host to be considered. + * @param variable The name of the variable to be considered. + * @param value The value to be added to the variable. * - * \see TRACE_host_variable_declare, TRACE_host_variable_set_with_time, TRACE_host_variable_sub_with_time + * @see TRACE_host_variable_declare, TRACE_host_variable_set_with_time, TRACE_host_variable_sub_with_time */ void TRACE_host_variable_add_with_time (double time, const char *host, const char *variable, double value) { instr_user_variable(time, host, variable, "HOST", value, InstrUserVariable::ADD, nullptr, &user_host_variables); } -/** \ingroup TRACE_user_variables - * \brief Subtract a value from a variable of a host at a given timestamp. +/** @ingroup TRACE_user_variables + * @brief Subtract a value from a variable of a host at a given timestamp. * * Same as #TRACE_host_variable_sub, but let user specify the time used to trace it. Users can specify a time that * is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are * also traced. * - * \param time The timestamp to be used to tag this change of value. - * \param host The name of the host to be considered. - * \param variable The name of the variable to be considered. - * \param value The value to be subtracted from the variable. + * @param time The timestamp to be used to tag this change of value. + * @param host The name of the host to be considered. + * @param variable The name of the variable to be considered. + * @param value The value to be subtracted from the variable. * - * \see TRACE_host_variable_declare, TRACE_host_variable_set_with_time, TRACE_host_variable_add_with_time + * @see TRACE_host_variable_declare, TRACE_host_variable_set_with_time, TRACE_host_variable_add_with_time */ void TRACE_host_variable_sub_with_time (double time, const char *host, const char *variable, double value) { instr_user_variable(time, host, variable, "HOST", value, InstrUserVariable::SUB, nullptr, &user_host_variables); } -/** \ingroup TRACE_user_variables - * \brief Get declared user host variables +/** @ingroup TRACE_user_variables + * @brief Get declared user host variables * * This function should be used to get host variables that were already declared with #TRACE_host_variable_declare or * with #TRACE_host_variable_declare_with_color. * - * \return A dynar with the declared host variables, must be freed with xbt_dynar_free. + * @return A dynar with the declared host variables, must be freed with xbt_dynar_free. */ xbt_dynar_t TRACE_get_host_variables () { @@ -622,133 +622,133 @@ xbt_dynar_t TRACE_get_host_variables () } /* for link variables */ -/** \ingroup TRACE_user_variables - * \brief Declare a new user variable associated to links. +/** @ingroup TRACE_user_variables + * @brief Declare a new user variable associated to links. * * Declare a user variable that will be associated to links. * A user link variable can be used, for example, to trace user variables such as the number of messages being * transferred through network links. The color associated to this new variable will be random. * - * \param variable The name of the new variable to be declared. + * @param variable The name of the new variable to be declared. * - * \see TRACE_link_variable_declare_with_color + * @see TRACE_link_variable_declare_with_color */ void TRACE_link_variable_declare (const char *variable) { instr_user_variable(0, nullptr, variable, "LINK", 0, InstrUserVariable::DECLARE, nullptr, &user_link_variables); } -/** \ingroup TRACE_user_variables - * \brief Declare a new user variable associated to links with a color. +/** @ingroup TRACE_user_variables + * @brief Declare a new user variable associated to links with a color. * * Same as #TRACE_link_variable_declare, but associated a color to the newly created user link variable. The color * needs to be a string with three numbers separated by spaces in the range [0,1]. * A light-gray color can be specified using "0.7 0.7 0.7" as color. * - * \param variable The name of the new variable to be declared. - * \param color The color for the new variable. + * @param variable The name of the new variable to be declared. + * @param color The color for the new variable. */ void TRACE_link_variable_declare_with_color (const char *variable, const char *color) { instr_user_variable(0, nullptr, variable, "LINK", 0, InstrUserVariable::DECLARE, color, &user_link_variables); } -/** \ingroup TRACE_user_variables - * \brief Set the value of a variable of a link. +/** @ingroup TRACE_user_variables + * @brief Set the value of a variable of a link. * - * \param link The name of the link to be considered. - * \param variable The name of the variable to be considered. - * \param value The new value of the variable. + * @param link The name of the link to be considered. + * @param variable The name of the variable to be considered. + * @param value The new value of the variable. * - * \see TRACE_link_variable_declare, TRACE_link_variable_add, TRACE_link_variable_sub + * @see TRACE_link_variable_declare, TRACE_link_variable_add, TRACE_link_variable_sub */ void TRACE_link_variable_set (const char *link, const char *variable, double value) { TRACE_link_variable_set_with_time (MSG_get_clock(), link, variable, value); } -/** \ingroup TRACE_user_variables - * \brief Add a value to a variable of a link. +/** @ingroup TRACE_user_variables + * @brief Add a value to a variable of a link. * - * \param link The name of the link to be considered. - * \param variable The name of the variable to be considered. - * \param value The value to be added to the variable. + * @param link The name of the link to be considered. + * @param variable The name of the variable to be considered. + * @param value The value to be added to the variable. * - * \see TRACE_link_variable_declare, TRACE_link_variable_set, TRACE_link_variable_sub + * @see TRACE_link_variable_declare, TRACE_link_variable_set, TRACE_link_variable_sub */ void TRACE_link_variable_add (const char *link, const char *variable, double value) { TRACE_link_variable_add_with_time (MSG_get_clock(), link, variable, value); } -/** \ingroup TRACE_user_variables - * \brief Subtract a value from a variable of a link. +/** @ingroup TRACE_user_variables + * @brief Subtract a value from a variable of a link. * - * \param link The name of the link to be considered. - * \param variable The name of the variable to be considered. - * \param value The value to be subtracted from the variable. + * @param link The name of the link to be considered. + * @param variable The name of the variable to be considered. + * @param value The value to be subtracted from the variable. * - * \see TRACE_link_variable_declare, TRACE_link_variable_set, TRACE_link_variable_add + * @see TRACE_link_variable_declare, TRACE_link_variable_set, TRACE_link_variable_add */ void TRACE_link_variable_sub (const char *link, const char *variable, double value) { TRACE_link_variable_sub_with_time (MSG_get_clock(), link, variable, value); } -/** \ingroup TRACE_user_variables - * \brief Set the value of a variable of a link at a given timestamp. +/** @ingroup TRACE_user_variables + * @brief Set the value of a variable of a link at a given timestamp. * * Same as #TRACE_link_variable_set, but let user specify the time used to trace it. Users can specify a time that * is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are * also traced. * - * \param time The timestamp to be used to tag this change of value. - * \param link The name of the link to be considered. - * \param variable The name of the variable to be considered. - * \param value The new value of the variable. + * @param time The timestamp to be used to tag this change of value. + * @param link The name of the link to be considered. + * @param variable The name of the variable to be considered. + * @param value The new value of the variable. * - * \see TRACE_link_variable_declare, TRACE_link_variable_add_with_time, TRACE_link_variable_sub_with_time + * @see TRACE_link_variable_declare, TRACE_link_variable_add_with_time, TRACE_link_variable_sub_with_time */ void TRACE_link_variable_set_with_time (double time, const char *link, const char *variable, double value) { instr_user_variable(time, link, variable, "LINK", value, InstrUserVariable::SET, nullptr, &user_link_variables); } -/** \ingroup TRACE_user_variables - * \brief Add a value to a variable of a link at a given timestamp. +/** @ingroup TRACE_user_variables + * @brief Add a value to a variable of a link at a given timestamp. * * Same as #TRACE_link_variable_add, but let user specify the time used to trace it. Users can specify a time that * is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are * also traced. * - * \param time The timestamp to be used to tag this change of value. - * \param link The name of the link to be considered. - * \param variable The name of the variable to be considered. - * \param value The value to be added to the variable. + * @param time The timestamp to be used to tag this change of value. + * @param link The name of the link to be considered. + * @param variable The name of the variable to be considered. + * @param value The value to be added to the variable. * - * \see TRACE_link_variable_declare, TRACE_link_variable_set_with_time, TRACE_link_variable_sub_with_time + * @see TRACE_link_variable_declare, TRACE_link_variable_set_with_time, TRACE_link_variable_sub_with_time */ void TRACE_link_variable_add_with_time (double time, const char *link, const char *variable, double value) { instr_user_variable(time, link, variable, "LINK", value, InstrUserVariable::ADD, nullptr, &user_link_variables); } -/** \ingroup TRACE_user_variables - * \brief Subtract a value from a variable of a link at a given timestamp. +/** @ingroup TRACE_user_variables + * @brief Subtract a value from a variable of a link at a given timestamp. * * Same as #TRACE_link_variable_sub, but let user specify the time used to trace it. Users can specify a time that * is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are * also traced. * - * \param time The timestamp to be used to tag this change of value. - * \param link The name of the link to be considered. - * \param variable The name of the variable to be considered. - * \param value The value to be subtracted from the variable. + * @param time The timestamp to be used to tag this change of value. + * @param link The name of the link to be considered. + * @param variable The name of the variable to be considered. + * @param value The value to be subtracted from the variable. * - * \see TRACE_link_variable_declare, TRACE_link_variable_set_with_time, TRACE_link_variable_add_with_time + * @see TRACE_link_variable_declare, TRACE_link_variable_set_with_time, TRACE_link_variable_add_with_time */ void TRACE_link_variable_sub_with_time (double time, const char *link, const char *variable, double value) { @@ -756,78 +756,78 @@ void TRACE_link_variable_sub_with_time (double time, const char *link, const cha } /* for link variables, but with src and dst used for get_route */ -/** \ingroup TRACE_user_variables - * \brief Set the value of the variable present in the links connecting source and destination. +/** @ingroup TRACE_user_variables + * @brief Set the value of the variable present in the links connecting source and destination. * * Same as #TRACE_link_variable_set, but instead of providing the name of link to be considered, provide the source * and destination hosts. All links that are part of the route between source and destination will have the variable * set to the provided value. * - * \param src The name of the source host for get route. - * \param dst The name of the destination host for get route. - * \param variable The name of the variable to be considered. - * \param value The new value of the variable. + * @param src The name of the source host for get route. + * @param dst The name of the destination host for get route. + * @param variable The name of the variable to be considered. + * @param value The new value of the variable. * - * \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_add, TRACE_link_srcdst_variable_sub + * @see TRACE_link_variable_declare, TRACE_link_srcdst_variable_add, TRACE_link_srcdst_variable_sub */ void TRACE_link_srcdst_variable_set (const char *src, const char *dst, const char *variable, double value) { TRACE_link_srcdst_variable_set_with_time (MSG_get_clock(), src, dst, variable, value); } -/** \ingroup TRACE_user_variables - * \brief Add a value to the variable present in the links connecting source and destination. +/** @ingroup TRACE_user_variables + * @brief Add a value to the variable present in the links connecting source and destination. * * Same as #TRACE_link_variable_add, but instead of providing the name of link to be considered, provide the source * and destination hosts. All links that are part of the route between source and destination will have the value * passed as parameter added to the current value of the variable name to be considered. * - * \param src The name of the source host for get route. - * \param dst The name of the destination host for get route. - * \param variable The name of the variable to be considered. - * \param value The value to be added to the variable. + * @param src The name of the source host for get route. + * @param dst The name of the destination host for get route. + * @param variable The name of the variable to be considered. + * @param value The value to be added to the variable. * - * \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set, TRACE_link_srcdst_variable_sub + * @see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set, TRACE_link_srcdst_variable_sub */ void TRACE_link_srcdst_variable_add (const char *src, const char *dst, const char *variable, double value) { TRACE_link_srcdst_variable_add_with_time (MSG_get_clock(), src, dst, variable, value); } -/** \ingroup TRACE_user_variables - * \brief Subtract a value from the variable present in the links connecting source and destination. +/** @ingroup TRACE_user_variables + * @brief Subtract a value from the variable present in the links connecting source and destination. * * Same as #TRACE_link_variable_sub, but instead of providing the name of link to be considered, provide the source * and destination hosts. All links that are part of the route between source and destination will have the value * passed as parameter subtracted from the current value of the variable name to be considered. * - * \param src The name of the source host for get route. - * \param dst The name of the destination host for get route. - * \param variable The name of the variable to be considered. - * \param value The value to be subtracted from the variable. + * @param src The name of the source host for get route. + * @param dst The name of the destination host for get route. + * @param variable The name of the variable to be considered. + * @param value The value to be subtracted from the variable. * - * \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set, TRACE_link_srcdst_variable_add + * @see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set, TRACE_link_srcdst_variable_add */ void TRACE_link_srcdst_variable_sub (const char *src, const char *dst, const char *variable, double value) { TRACE_link_srcdst_variable_sub_with_time (MSG_get_clock(), src, dst, variable, value); } -/** \ingroup TRACE_user_variables - * \brief Set the value of the variable present in the links connecting source and destination at a given timestamp. +/** @ingroup TRACE_user_variables + * @brief Set the value of the variable present in the links connecting source and destination at a given timestamp. * * Same as #TRACE_link_srcdst_variable_set, but let user specify the time used to trace it. Users can specify a time * that is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are * also traced. * - * \param time The timestamp to be used to tag this change of value. - * \param src The name of the source host for get route. - * \param dst The name of the destination host for get route. - * \param variable The name of the variable to be considered. - * \param value The new value of the variable. + * @param time The timestamp to be used to tag this change of value. + * @param src The name of the source host for get route. + * @param dst The name of the destination host for get route. + * @param variable The name of the variable to be considered. + * @param value The new value of the variable. * - * \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_add_with_time, TRACE_link_srcdst_variable_sub_with_time + * @see TRACE_link_variable_declare, TRACE_link_srcdst_variable_add_with_time, TRACE_link_srcdst_variable_sub_with_time */ void TRACE_link_srcdst_variable_set_with_time (double time, const char *src, const char *dst, const char *variable, double value) @@ -835,21 +835,21 @@ void TRACE_link_srcdst_variable_set_with_time (double time, const char *src, con instr_user_srcdst_variable(time, src, dst, variable, "LINK", value, InstrUserVariable::SET); } -/** \ingroup TRACE_user_variables - * \brief Add a value to the variable present in the links connecting source and destination at a given timestamp. +/** @ingroup TRACE_user_variables + * @brief Add a value to the variable present in the links connecting source and destination at a given timestamp. * * Same as #TRACE_link_srcdst_variable_add, but let user specify the time used to trace it. Users can specify a time * that is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are * also traced. * - * \param time The timestamp to be used to tag this change of value. - * \param src The name of the source host for get route. - * \param dst The name of the destination host for get route. - * \param variable The name of the variable to be considered. - * \param value The value to be added to the variable. + * @param time The timestamp to be used to tag this change of value. + * @param src The name of the source host for get route. + * @param dst The name of the destination host for get route. + * @param variable The name of the variable to be considered. + * @param value The value to be added to the variable. * - * \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set_with_time, TRACE_link_srcdst_variable_sub_with_time + * @see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set_with_time, TRACE_link_srcdst_variable_sub_with_time */ void TRACE_link_srcdst_variable_add_with_time (double time, const char *src, const char *dst, const char *variable, double value) @@ -857,21 +857,21 @@ void TRACE_link_srcdst_variable_add_with_time (double time, const char *src, con instr_user_srcdst_variable(time, src, dst, variable, "LINK", value, InstrUserVariable::ADD); } -/** \ingroup TRACE_user_variables - * \brief Subtract a value from the variable present in the links connecting source and dest. at a given timestamp. +/** @ingroup TRACE_user_variables + * @brief Subtract a value from the variable present in the links connecting source and dest. at a given timestamp. * * Same as #TRACE_link_srcdst_variable_sub, but let user specify the time used to trace it. Users can specify a time * that is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are * also traced. * - * \param time The timestamp to be used to tag this change of value. - * \param src The name of the source host for get route. - * \param dst The name of the destination host for get route. - * \param variable The name of the variable to be considered. - * \param value The value to be subtracted from the variable. + * @param time The timestamp to be used to tag this change of value. + * @param src The name of the source host for get route. + * @param dst The name of the destination host for get route. + * @param variable The name of the variable to be considered. + * @param value The value to be subtracted from the variable. * - * \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set_with_time, TRACE_link_srcdst_variable_add_with_time + * @see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set_with_time, TRACE_link_srcdst_variable_add_with_time */ void TRACE_link_srcdst_variable_sub_with_time (double time, const char *src, const char *dst, const char *variable, double value) @@ -879,61 +879,61 @@ void TRACE_link_srcdst_variable_sub_with_time (double time, const char *src, con instr_user_srcdst_variable(time, src, dst, variable, "LINK", value, InstrUserVariable::SUB); } -/** \ingroup TRACE_user_variables - * \brief Get declared user link variables +/** @ingroup TRACE_user_variables + * @brief Get declared user link variables * * This function should be used to get link variables that were already declared with #TRACE_link_variable_declare or * with #TRACE_link_variable_declare_with_color. * - * \return A dynar with the declared link variables, must be freed with xbt_dynar_free. + * @return A dynar with the declared link variables, must be freed with xbt_dynar_free. */ xbt_dynar_t TRACE_get_link_variables () { return instr_set_to_dynar(&user_link_variables); } -/** \ingroup TRACE_user_variables - * \brief Declare a new user state associated to hosts. +/** @ingroup TRACE_user_variables + * @brief Declare a new user state associated to hosts. * * Declare a user state that will be associated to hosts. * A user host state can be used to trace application states. * - * \param state The name of the new state to be declared. + * @param state The name of the new state to be declared. * - * \see TRACE_host_state_declare_value + * @see TRACE_host_state_declare_value */ void TRACE_host_state_declare (const char *state) { instr_new_user_state_type("HOST", state); } -/** \ingroup TRACE_user_variables - * \brief Declare a new value for a user state associated to hosts. +/** @ingroup TRACE_user_variables + * @brief Declare a new value for a user state associated to hosts. * * Declare a value for a state. The color needs to be a string with 3 numbers separated by spaces in the range [0,1]. * A light-gray color can be specified using "0.7 0.7 0.7" as color. * - * \param state The name of the new state to be declared. - * \param value The name of the value - * \param color The color of the value + * @param state The name of the new state to be declared. + * @param value The name of the value + * @param color The color of the value * - * \see TRACE_host_state_declare + * @see TRACE_host_state_declare */ void TRACE_host_state_declare_value (const char *state, const char *value, const char *color) { instr_new_value_for_user_state_type (state, value, color); } -/** \ingroup TRACE_user_variables - * \brief Set the user state to the given value. +/** @ingroup TRACE_user_variables + * @brief Set the user state to the given value. * * Change a user state previously declared to the given value. * - * \param host The name of the host to be considered. - * \param state_name The name of the state previously declared. - * \param value_name The new value of the state. + * @param host The name of the host to be considered. + * @param state_name The name of the state previously declared. + * @param value_name The new value of the state. * - * \see TRACE_host_state_declare, TRACE_host_push_state, TRACE_host_pop_state, TRACE_host_reset_state + * @see TRACE_host_state_declare, TRACE_host_push_state, TRACE_host_pop_state, TRACE_host_reset_state */ void TRACE_host_set_state(const char* host, const char* state_name, const char* value_name) { @@ -942,57 +942,57 @@ void TRACE_host_set_state(const char* host, const char* state_name, const char* state->set_event(value_name); } -/** \ingroup TRACE_user_variables - * \brief Push a new value for a state of a given host. +/** @ingroup TRACE_user_variables + * @brief Push a new value for a state of a given host. * * Change a user state previously declared by pushing the new value to the state. * - * \param host The name of the host to be considered. - * \param state_name The name of the state previously declared. - * \param value_name The value to be pushed. + * @param host The name of the host to be considered. + * @param state_name The name of the state previously declared. + * @param value_name The value to be pushed. * - * \see TRACE_host_state_declare, TRACE_host_set_state, TRACE_host_pop_state, TRACE_host_reset_state + * @see TRACE_host_state_declare, TRACE_host_set_state, TRACE_host_pop_state, TRACE_host_reset_state */ void TRACE_host_push_state(const char* host, const char* state_name, const char* value_name) { simgrid::instr::Container::by_name(host)->get_state(state_name)->push_event(value_name); } -/** \ingroup TRACE_user_variables - * \brief Pop the last value of a state of a given host. +/** @ingroup TRACE_user_variables + * @brief Pop the last value of a state of a given host. * * Change a user state previously declared by removing the last value of the state. * - * \param host The name of the host to be considered. - * \param state_name The name of the state to be popped. + * @param host The name of the host to be considered. + * @param state_name The name of the state to be popped. * - * \see TRACE_host_state_declare, TRACE_host_set_state, TRACE_host_push_state, TRACE_host_reset_state + * @see TRACE_host_state_declare, TRACE_host_set_state, TRACE_host_push_state, TRACE_host_reset_state */ void TRACE_host_pop_state(const char* host, const char* state_name) { simgrid::instr::Container::by_name(host)->get_state(state_name)->pop_event(); } -/** \ingroup TRACE_API - * \brief Get Paje container types that can be mapped to the nodes of a graph. +/** @ingroup TRACE_API + * @brief Get Paje container types that can be mapped to the nodes of a graph. * * This function can be used to create a user made graph configuration file for Triva. Normally, it is used with the - * functions defined in \ref TRACE_user_variables. + * functions defined in @ref TRACE_user_variables. * - * \return A dynar with the types, must be freed with xbt_dynar_free. + * @return A dynar with the types, must be freed with xbt_dynar_free. */ xbt_dynar_t TRACE_get_node_types () { return instr_set_to_dynar(&trivaNodeTypes); } -/** \ingroup TRACE_API - * \brief Get Paje container types that can be mapped to the edges of a graph. +/** @ingroup TRACE_API + * @brief Get Paje container types that can be mapped to the edges of a graph. * * This function can be used to create a user made graph configuration file for Triva. Normally, it is used with the - * functions defined in \ref TRACE_user_variables. + * functions defined in @ref TRACE_user_variables. * - * \return A dynar with the types, must be freed with xbt_dynar_free. + * @return A dynar with the types, must be freed with xbt_dynar_free. */ xbt_dynar_t TRACE_get_edge_types () { diff --git a/src/kernel/activity/ConditionVariableImpl.cpp b/src/kernel/activity/ConditionVariableImpl.cpp index d59d8997e9..ddd34cd6b2 100644 --- a/src/kernel/activity/ConditionVariableImpl.cpp +++ b/src/kernel/activity/ConditionVariableImpl.cpp @@ -36,7 +36,7 @@ static void _SIMIX_cond_wait(smx_cond_t cond, smx_mutex_t mutex, double timeout, } /** - * \brief Handle a condition waiting simcall without timeouts + * @brief Handle a condition waiting simcall without timeouts */ void simcall_HANDLER_cond_wait(smx_simcall_t simcall, smx_cond_t cond, smx_mutex_t mutex) { @@ -48,7 +48,7 @@ void simcall_HANDLER_cond_wait(smx_simcall_t simcall, smx_cond_t cond, smx_mutex } /** - * \brief Handle a condition waiting simcall with timeouts + * @brief Handle a condition waiting simcall with timeouts */ void simcall_HANDLER_cond_wait_timeout(smx_simcall_t simcall, smx_cond_t cond, smx_mutex_t mutex, double timeout) { @@ -67,7 +67,7 @@ ConditionVariableImpl::ConditionVariableImpl() : cond_(this) {} ConditionVariableImpl::~ConditionVariableImpl() = default; /** - * \brief Signalizes a condition. + * @brief Signalizes a condition. * * Signalizes a condition and wakes up a sleeping process. * If there are no process sleeping, no action is done. @@ -100,7 +100,7 @@ void ConditionVariableImpl::signal() } /** - * \brief Broadcasts a condition. + * @brief Broadcasts a condition. * * Signal ALL processes waiting on a condition. * If there are no process waiting, no action is done. diff --git a/src/kernel/activity/MailboxImpl.cpp b/src/kernel/activity/MailboxImpl.cpp index f519fa224d..2a1d9d0081 100644 --- a/src/kernel/activity/MailboxImpl.cpp +++ b/src/kernel/activity/MailboxImpl.cpp @@ -47,7 +47,7 @@ MailboxImpl* MailboxImpl::by_name_or_create(std::string name) return m->second; } /** @brief set the receiver of the mailbox to allow eager sends - * \param actor The receiving dude + * @param actor The receiving dude */ void MailboxImpl::set_receiver(s4u::ActorPtr actor) { diff --git a/src/kernel/activity/MutexImpl.cpp b/src/kernel/activity/MutexImpl.cpp index 9581637a40..6eed2dd23e 100644 --- a/src/kernel/activity/MutexImpl.cpp +++ b/src/kernel/activity/MutexImpl.cpp @@ -49,8 +49,8 @@ void MutexImpl::lock(smx_actor_t issuer) /** Tries to lock the mutex for a process * - * \param issuer the process that tries to acquire the mutex - * \return whether we managed to lock the mutex + * @param issuer the process that tries to acquire the mutex + * @return whether we managed to lock the mutex */ bool MutexImpl::try_lock(smx_actor_t issuer) { diff --git a/src/kernel/lmm/lagrange.cpp b/src/kernel/lmm/lagrange.cpp index e7f71edf3b..9df29c0408 100644 --- a/src/kernel/lmm/lagrange.cpp +++ b/src/kernel/lmm/lagrange.cpp @@ -217,7 +217,7 @@ void Lagrange::lagrange_solve() obj = new_obj; } - /* Now computes the values of each variable (\rho) based on the values of \lambda and \mu. */ + /* Now computes the values of each variable (@rho) based on the values of @lambda and @mu. */ XBT_DEBUG("-------------- Check convergence ----------"); overall_modification = 0; for (Variable& var : variable_set) { @@ -255,10 +255,10 @@ void Lagrange::lagrange_solve() /* * Returns a double value corresponding to the result of a dichotomy process with respect to a given - * variable/constraint (\mu in the case of a variable or \lambda in case of a constraint) and a initial value init. + * variable/constraint (@mu in the case of a variable or @lambda in case of a constraint) and a initial value init. * - * @param init initial value for \mu or \lambda - * @param diff a function that computes the differential of with respect a \mu or \lambda + * @param init initial value for @mu or @lambda + * @param diff a function that computes the differential of with respect a @mu or @lambda * @param var_cnst a pointer to a variable or constraint * @param min_erro a minimum error tolerated * @@ -401,11 +401,11 @@ double Lagrange::partial_diff_lambda(double lambda, const Constraint& cnst) return diff; } -/** \brief Attribute the value bound to var->bound. +/** @brief Attribute the value bound to var->bound. * - * \param func_f function (f) - * \param func_fp partial differential of f (f prime, (f')) - * \param func_fpi inverse of the partial differential of f (f prime inverse, (f')^{-1}) + * @param func_f function (f) + * @param func_fp partial differential of f (f prime, (f')) + * @param func_fpi inverse of the partial differential of f (f prime inverse, (f')^{-1}) * * Set default functions to the ones passed as parameters. */ @@ -426,9 +426,9 @@ double (*Lagrange::func_fpi)(const Variable&, double); /* NOTE for Reno: all functions consider the network coefficient (alpha) equal to 1. */ /* - * For Vegas: $f(x) = \alpha D_f\ln(x)$ - * Therefore: $fp(x) = \frac{\alpha D_f}{x}$ - * Therefore: $fpi(x) = \frac{\alpha D_f}{x}$ + * For Vegas: $f(x) = @alpha D_f@ln(x)$ + * Therefore: $fp(x) = @frac{@alpha D_f}{x}$ + * Therefore: $fpi(x) = @frac{@alpha D_f}{x}$ */ double func_vegas_f(const Variable& var, double x) { @@ -449,9 +449,9 @@ double func_vegas_fpi(const Variable& var, double x) } /* - * For Reno: $f(x) = \frac{\sqrt{3/2}}{D_f} atan(\sqrt{3/2}D_f x)$ - * Therefore: $fp(x) = \frac{3}{3 D_f^2 x^2+2}$ - * Therefore: $fpi(x) = \sqrt{\frac{1}{{D_f}^2 x} - \frac{2}{3{D_f}^2}}$ + * For Reno: $f(x) = @frac{@sqrt{3/2}}{D_f} atan(@sqrt{3/2}D_f x)$ + * Therefore: $fp(x) = @frac{3}{3 D_f^2 x^2+2}$ + * Therefore: $fpi(x) = @sqrt{@frac{1}{{D_f}^2 x} - @frac{2}{3{D_f}^2}}$ */ double func_reno_f(const Variable& var, double x) { @@ -480,7 +480,7 @@ double func_reno_fpi(const Variable& var, double x) } /* Implementing new Reno-2 - * For Reno-2: $f(x) = U_f(x_f) = \frac{{2}{D_f}}*ln(2+x*D_f)$ + * For Reno-2: $f(x) = U_f(x_f) = @frac{{2}{D_f}}*ln(2+x*D_f)$ * Therefore: $fp(x) = 2/(Weight*x + 2) * Therefore: $fpi(x) = (2*Weight)/x - 4 */ diff --git a/src/kernel/lmm/maxmin.cpp b/src/kernel/lmm/maxmin.cpp index 6eab5be5ce..62d9c4d0c4 100644 --- a/src/kernel/lmm/maxmin.cpp +++ b/src/kernel/lmm/maxmin.cpp @@ -681,10 +681,10 @@ template void System::lmm_solve(CnstList& cnst_list) delete[] cnst_light_tab; } -/** \brief Attribute the value bound to var->bound. +/** @brief Attribute the value bound to var->bound. * - * \param var the Variable* - * \param bound the new bound to associate with var + * @param var the Variable* + * @param bound the new bound to associate with var * * Makes var->bound equal to bound. Whenever this function is called a change is signed in the system. To * avoid false system changing detection it is a good idea to test (bound != 0) before calling it. @@ -832,7 +832,7 @@ void System::on_disabled_var(Constraint* cnstr) // Anyway, caller functions all call check_concurrency() in the end. } -/* \brief update the weight of a variable, and enable/disable it. +/* @brief update the weight of a variable, and enable/disable it. * @return Returns whether a change was made */ void System::update_variable_weight(Variable* var, double weight) @@ -880,10 +880,10 @@ void System::update_constraint_bound(Constraint* cnst, double bound) cnst->bound = bound; } -/** \brief Update the constraint set propagating recursively to other constraints so the system should not be entirely +/** @brief Update the constraint set propagating recursively to other constraints so the system should not be entirely * computed. * - * \param cnst the Constraint* affected by the change + * @param cnst the Constraint* affected by the change * * A recursive algorithm to optimize the system recalculation selecting only constraints that have changed. Each * constraint change is propagated to the list of constraints for each variable. diff --git a/src/mc/VisitedState.cpp b/src/mc/VisitedState.cpp index 517a6b06d5..6b833dc2e6 100644 --- a/src/mc/VisitedState.cpp +++ b/src/mc/VisitedState.cpp @@ -62,8 +62,7 @@ void VisitedStates::prune() } } -/** \brief Checks whether a given state has already been visited by the algorithm. - */ +/** @brief Checks whether a given state has already been visited by the algorithm. */ std::unique_ptr VisitedStates::addVisitedState( unsigned long state_number, simgrid::mc::State* graph_state, bool compare_snpashots) { diff --git a/src/mc/checker/LivenessChecker.cpp b/src/mc/checker/LivenessChecker.cpp index ee00b66ec6..e82ea1b5a4 100644 --- a/src/mc/checker/LivenessChecker.cpp +++ b/src/mc/checker/LivenessChecker.cpp @@ -202,7 +202,7 @@ void LivenessChecker::replay() } /** - * \brief Checks whether a given pair has already been visited by the algorithm. + * @brief Checks whether a given pair has already been visited by the algorithm. */ int LivenessChecker::insertVisitedPair(std::shared_ptr visited_pair, simgrid::mc::Pair* pair) { diff --git a/src/mc/mc_dwarf.cpp b/src/mc/mc_dwarf.cpp index e27f54f6fe..40886255d8 100644 --- a/src/mc/mc_dwarf.cpp +++ b/src/mc/mc_dwarf.cpp @@ -1,5 +1,4 @@ -/* Copyright (c) 2008-2018. The SimGrid Team. - * All rights reserved. */ +/* Copyright (c) 2008-2018. The SimGrid Team. All rights reserved. */ /* This program is free software; you can redistribute it and/or modify it * under the terms of the license (GNU LGPL) which comes with this package. */ @@ -33,15 +32,15 @@ XBT_LOG_NEW_DEFAULT_SUBCATEGORY(mc_dwarf, mc, "DWARF processing"); -/** \brief The default DW_TAG_lower_bound for a given DW_AT_language. +/** @brief The default DW_TAG_lower_bound for a given DW_AT_language. * * The default for a given language is defined in the DWARF spec. * - * \param language constant as defined by the DWARf spec + * @param language constant as defined by the DWARf spec */ static uint64_t MC_dwarf_default_lower_bound(int lang); -/** \brief Computes the the element_count of a DW_TAG_enumeration_type DIE +/** @brief Computes the the element_count of a DW_TAG_enumeration_type DIE * * This is the number of elements in a given array dimension. * @@ -49,60 +48,60 @@ static uint64_t MC_dwarf_default_lower_bound(int lang); * needed because the default lower bound (when there is no DW_AT_lower_bound) * depends of the language of the compilation unit (DW_AT_language). * - * \param die DIE for the DW_TAG_enumeration_type or DW_TAG_subrange_type - * \param unit DIE of the DW_TAG_compile_unit + * @param die DIE for the DW_TAG_enumeration_type or DW_TAG_subrange_type + * @param unit DIE of the DW_TAG_compile_unit */ static uint64_t MC_dwarf_subrange_element_count(Dwarf_Die* die, Dwarf_Die* unit); -/** \brief Computes the number of elements of a given DW_TAG_array_type. +/** @brief Computes the number of elements of a given DW_TAG_array_type. * - * \param die DIE for the DW_TAG_array_type + * @param die DIE for the DW_TAG_array_type */ static uint64_t MC_dwarf_array_element_count(Dwarf_Die * die, Dwarf_Die * unit); -/** \brief Process a DIE +/** @brief Process a DIE * - * \param info the resulting object fot the library/binary file (output) - * \param die the current DIE - * \param unit the DIE of the compile unit of the current DIE - * \param frame containing frame if any + * @param info the resulting object fot the library/binary file (output) + * @param die the current DIE + * @param unit the DIE of the compile unit of the current DIE + * @param frame containing frame if any */ static void MC_dwarf_handle_die(simgrid::mc::ObjectInformation* info, Dwarf_Die * die, Dwarf_Die * unit, simgrid::mc::Frame* frame, const char *ns); -/** \brief Process a type DIE +/** @brief Process a type DIE */ static void MC_dwarf_handle_type_die(simgrid::mc::ObjectInformation* info, Dwarf_Die * die, Dwarf_Die * unit, simgrid::mc::Frame* frame, const char *ns); -/** \brief Calls MC_dwarf_handle_die on all children of the given die +/** @brief Calls MC_dwarf_handle_die on all children of the given die * - * \param info the resulting object fot the library/binary file (output) - * \param die the current DIE - * \param unit the DIE of the compile unit of the current DIE - * \param frame containing frame if any + * @param info the resulting object fot the library/binary file (output) + * @param die the current DIE + * @param unit the DIE of the compile unit of the current DIE + * @param frame containing frame if any */ static void MC_dwarf_handle_children(simgrid::mc::ObjectInformation* info, Dwarf_Die * die, Dwarf_Die * unit, simgrid::mc::Frame* frame, const char *ns); -/** \brief Handle a variable (DW_TAG_variable or other) +/** @brief Handle a variable (DW_TAG_variable or other) * - * \param info the resulting object fot the library/binary file (output) - * \param die the current DIE - * \param unit the DIE of the compile unit of the current DIE - * \param frame containing frame if any + * @param info the resulting object fot the library/binary file (output) + * @param die the current DIE + * @param unit the DIE of the compile unit of the current DIE + * @param frame containing frame if any */ static void MC_dwarf_handle_variable_die(simgrid::mc::ObjectInformation* info, Dwarf_Die * die, Dwarf_Die * unit, simgrid::mc::Frame* frame, const char *ns); -/** \brief Get the DW_TAG_type of the DIE +/** @brief Get the DW_TAG_type of the DIE * - * \param die DIE - * \return DW_TAG_type attribute as a new string (nullptr if none) + * @param die DIE + * @return DW_TAG_type attribute as a new string (nullptr if none) */ static std::uint64_t MC_dwarf_at_type(Dwarf_Die * die); @@ -186,12 +185,12 @@ TagClass classify_tag(int tag) } } -/** \brief Find the DWARF data class for a given DWARF data form +/** @brief Find the DWARF data class for a given DWARF data form * * This mapping is defined in the DWARF spec. * - * \param form The form (values taken from the DWARF spec) - * \return An internal representation for the corresponding class + * @param form The form (values taken from the DWARF spec) + * @return An internal representation for the corresponding class * */ static FormClass classify_form(int form) @@ -233,10 +232,10 @@ FormClass classify_form(int form) } } -/** \brief Get the name of the tag of a given DIE +/** @brief Get the name of the tag of a given DIE * - * \param die DIE - * \return name of the tag of this DIE + * @param die DIE + * @return name of the tag of this DIE */ inline XBT_PRIVATE const char *tagname(Dwarf_Die * die) @@ -249,11 +248,11 @@ const char *tagname(Dwarf_Die * die) // ***** Attributes -/** \brief Get an attribute of a given DIE as a string +/** @brief Get an attribute of a given DIE as a string * - * \param die the DIE - * \param attribute attribute - * \return value of the given attribute of the given DIE + * @param die the DIE + * @param attribute attribute + * @return value of the given attribute of the given DIE */ static const char *MC_dwarf_attr_integrate_string(Dwarf_Die * die, int attribute) @@ -290,10 +289,10 @@ static Dwarf_Off MC_dwarf_attr_integrate_dieoffset(Dwarf_Die * die, return dwarf_dieoffset(&subtype_die); } -/** \brief Find the type/subtype (DW_AT_type) for a DIE +/** @brief Find the type/subtype (DW_AT_type) for a DIE * - * \param die the DIE - * \return DW_AT_type reference as a global offset in hexadecimal (or nullptr) + * @param die the DIE + * @return DW_AT_type reference as a global offset in hexadecimal (or nullptr) */ static std::uint64_t MC_dwarf_at_type(Dwarf_Die * die) @@ -378,11 +377,11 @@ static uint64_t MC_dwarf_default_lower_bound(int lang) } } -/** \brief Finds the number of elements in a DW_TAG_subrange_type or DW_TAG_enumeration_type DIE +/** @brief Finds the number of elements in a DW_TAG_subrange_type or DW_TAG_enumeration_type DIE * - * \param die the DIE - * \param unit DIE of the compilation unit - * \return number of elements in the range + * @param die the DIE + * @param unit DIE of the compilation unit + * @return number of elements in the range * */ static uint64_t MC_dwarf_subrange_element_count(Dwarf_Die * die, Dwarf_Die * unit) @@ -411,14 +410,14 @@ static uint64_t MC_dwarf_subrange_element_count(Dwarf_Die * die, return upper_bound - lower_bound + 1; } -/** \brief Finds the number of elements in a array type (DW_TAG_array_type) +/** @brief Finds the number of elements in a array type (DW_TAG_array_type) * * The compilation unit might be needed because the default lower * bound depends on the language of the compilation unit. * - * \param die the DIE of the DW_TAG_array_type - * \param unit the DIE of the compilation unit - * \return number of elements in this array type + * @param die the DIE of the DW_TAG_array_type + * @param unit the DIE of the compilation unit + * @return number of elements in this array type * */ static uint64_t MC_dwarf_array_element_count(Dwarf_Die * die, Dwarf_Die * unit) { @@ -459,12 +458,12 @@ static bool MC_compare_variable( // ***** simgrid::mc::Type* -/** \brief Initialize the location of a member of a type +/** @brief Initialize the location of a member of a type * (DW_AT_data_member_location of a DW_TAG_member). * - * \param type a type (struct, class) - * \param member the member of the type - * \param child DIE of the member (DW_TAG_member) + * @param type a type (struct, class) + * @param member the member of the type + * @param child DIE of the member (DW_TAG_member) */ static void MC_dwarf_fill_member_location( simgrid::mc::Type* type, simgrid::mc::Member* member, Dwarf_Die * child) @@ -521,12 +520,12 @@ static void MC_dwarf_fill_member_location( } -/** \brief Populate the list of members of a type +/** @brief Populate the list of members of a type * - * \param info ELF object containing the type DIE - * \param die DIE of the type - * \param unit DIE of the compilation unit containing the type DIE - * \param type the type + * @param info ELF object containing the type DIE + * @param die DIE of the type + * @param unit DIE of the compilation unit containing the type DIE + * @param type the type */ static void MC_dwarf_add_members(simgrid::mc::ObjectInformation* /*info*/, Dwarf_Die* die, Dwarf_Die* /*unit*/, simgrid::mc::Type* type) @@ -597,12 +596,12 @@ static void MC_dwarf_add_members(simgrid::mc::ObjectInformation* /*info*/, Dwarf } } -/** \brief Create a MC type object from a DIE +/** @brief Create a MC type object from a DIE * - * \param info current object info object - * \param die DIE (for a given type) - * \param unit compilation unit of the current DIE - * \return MC representation of the type + * @param info current object info object + * @param die DIE (for a given type) + * @param unit compilation unit of the current DIE + * @return MC representation of the type */ static simgrid::mc::Type MC_dwarf_die_to_type( simgrid::mc::ObjectInformation* info, Dwarf_Die * die, @@ -1121,7 +1120,7 @@ std::string find_by_build_id(std::vector id) return std::string(); } -/** \brief Populate the debugging informations of the given ELF object +/** @brief Populate the debugging informations of the given ELF object * * Read the DWARf information of the EFFL object and populate the * lists of types, variables, functions. @@ -1203,8 +1202,8 @@ void MC_load_dwarf(simgrid::mc::ObjectInformation* info) elf_end(elf); close(fd); xbt_die("Debugging information not found for %s\n" - "Try recompiling with -g\n", - info->file_name.c_str()); + "Try recompiling with -g\nn", + info->file_name.c_str()); } // ***** Functions index @@ -1307,7 +1306,7 @@ static void MC_post_process_types(simgrid::mc::ObjectInformation* info) namespace simgrid { namespace mc { -/** \brief Finds informations about a given shared object/executable */ +/** @brief Finds informations about a given shared object/executable */ std::shared_ptr createObjectInformation( std::vector const& maps, const char *name) { diff --git a/src/mc/mc_dwarf_attrnames.cpp b/src/mc/mc_dwarf_attrnames.cpp index a678222d69..b9f8eea72c 100644 --- a/src/mc/mc_dwarf_attrnames.cpp +++ b/src/mc/mc_dwarf_attrnames.cpp @@ -160,10 +160,10 @@ const std::unordered_map attrname_map = { namespace simgrid { namespace dwarf { -/** \brief Get the name of an attribute (DW_AT_*) from its code +/** @brief Get the name of an attribute (DW_AT_*) from its code * - * \param attr attribute code (see the DWARF specification) - * \return name of the attribute + * @param attr attribute code (see the DWARF specification) + * @return name of the attribute */ XBT_PRIVATE const char *attrname(int attr) diff --git a/src/mc/mc_dwarf_tagnames.cpp b/src/mc/mc_dwarf_tagnames.cpp index f593912a96..7f9221063a 100644 --- a/src/mc/mc_dwarf_tagnames.cpp +++ b/src/mc/mc_dwarf_tagnames.cpp @@ -94,10 +94,10 @@ const std::unordered_map tagname_map = { namespace simgrid { namespace dwarf { -/** \brief Get the name of a dwarf tag (DW_TAG_*) from its code +/** @brief Get the name of a dwarf tag (DW_TAG_*) from its code * - * \param tag tag code (see the DWARF specification) - * \return name of the tag + * @param tag tag code (see the DWARF specification) + * @return name of the tag */ XBT_PRIVATE const char *tagname(int tag) diff --git a/src/mc/sosp/mc_checkpoint.cpp b/src/mc/sosp/mc_checkpoint.cpp index f5d279fb45..09cb6aefb9 100644 --- a/src/mc/sosp/mc_checkpoint.cpp +++ b/src/mc/sosp/mc_checkpoint.cpp @@ -158,7 +158,7 @@ static void get_memory_regions(simgrid::mc::RemoteClient* process, simgrid::mc:: snapshot->privatization_index = simgrid::mc::ProcessIndexMissing; } -/** \brief Fills the position of the segments (executable, read-only, read/write). +/** @brief Fills the position of the segments (executable, read-only, read/write). * */ // TODO, use the ELF segment information for more robustness void find_object_address(std::vector const& maps, simgrid::mc::ObjectInformation* result) @@ -226,14 +226,14 @@ void find_object_address(std::vector const& maps, simgrid:: /************************************* Take Snapshot ************************************/ /****************************************************************************************/ -/** \brief Checks whether the variable is in scope for a given IP. +/** @brief Checks whether the variable is in scope for a given IP. * * A variable may be defined only from a given value of IP. * - * \param var Variable description - * \param scope Scope description - * \param ip Instruction pointer - * \return true if the variable is valid + * @param var Variable description + * @param scope Scope description + * @param ip Instruction pointer + * @return true if the variable is valid * */ static bool valid_variable(simgrid::mc::Variable* var, simgrid::mc::Frame* scope, const void* ip) { diff --git a/src/msg/msg_global.cpp b/src/msg/msg_global.cpp index e6dd156a7d..06c261a777 100644 --- a/src/msg/msg_global.cpp +++ b/src/msg/msg_global.cpp @@ -20,8 +20,8 @@ static void MSG_exit(); /********************************* MSG **************************************/ /** - * \ingroup msg_simulation - * \brief Initialize MSG with less verifications + * @ingroup msg_simulation + * @brief Initialize MSG with less verifications * You should use the MSG_init() function instead. Failing to do so may turn into PEBKAC some day. You've been warned. */ void MSG_init_nocheck(int *argc, char **argv) { @@ -55,10 +55,11 @@ void MSG_init_nocheck(int *argc, char **argv) { atexit(MSG_exit); } -/** \ingroup msg_simulation - * \brief set a configuration variable +/** @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. + * 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"); @@ -78,7 +79,7 @@ unsigned long int MSG_get_sent_msg() return msg_global->sent_msg; } -/** \brief register functions bypassing the parser */ +/** @brief register functions bypassing the parser */ void MSG_set_function(const char* host_id, const char* function_name, xbt_dynar_t arguments) { SIMIX_process_set_function(host_id, function_name, arguments, -1, -1); diff --git a/src/msg/msg_gos.cpp b/src/msg/msg_gos.cpp index 65d91fc4f3..b7429cb092 100644 --- a/src/msg/msg_gos.cpp +++ b/src/msg/msg_gos.cpp @@ -13,24 +13,24 @@ 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. +/** @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. - * \param task a #msg_task_t to execute on the location on which the process is running. - * \return #MSG_OK if the task was successfully completed, #MSG_TASK_CANCELED or #MSG_HOST_FAILURE otherwise + * @param task a #msg_task_t to execute on the location on which the process is running. + * @return #MSG_OK if the task was successfully completed, #MSG_TASK_CANCELED or #MSG_HOST_FAILURE otherwise */ 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. +/** @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. + * @param task a #msg_task_t to execute on the location on which the process is running. * - * \return #MSG_OK if the task was successfully completed, #MSG_TASK_CANCELED + * @return #MSG_OK if the task was successfully completed, #MSG_TASK_CANCELED * or #MSG_HOST_FAILURE otherwise */ msg_error_t MSG_parallel_task_execute(msg_task_t task) @@ -102,12 +102,12 @@ 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 +/** @ingroup msg_task_usage + * @brief Sleep for the specified number of seconds * - * Makes the current process sleep until \a time seconds have elapsed. + * Makes the current process sleep until @a time seconds have elapsed. * - * \param nb_sec a number of second + * @param nb_sec a number of second */ msg_error_t MSG_process_sleep(double nb_sec) { @@ -133,16 +133,16 @@ msg_error_t MSG_process_sleep(double nb_sec) return status; } -/** \ingroup msg_task_usage - * \brief Receives a task from a mailbox. +/** @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 * for receiving tasks asynchronously. * - * \param task a memory location for storing a #msg_task_t. - * \param alias name of the mailbox to receive the task from + * @param task a memory location for storing a #msg_task_t. + * @param alias name of the mailbox to receive the task from * - * \return Returns + * @return Returns * #MSG_OK if the task was successfully received, * #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE otherwise. */ @@ -151,19 +151,19 @@ 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. +/** @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. - * \param alias name of the mailbox to receive the task from - * \param rate limit the reception to rate bandwidth (byte/sec) + * @param task a memory location for storing a #msg_task_t. + * @param alias name of the mailbox to receive the task from + * @param rate limit the reception to rate bandwidth (byte/sec) * * The rate parameter can be used to receive a task with a limited * bandwidth (smaller than the physical available value). Use * MSG_task_receive() if you don't limit the rate (or pass -1 as a * rate value do disable this feature). * - * \return Returns + * @return Returns * #MSG_OK if the task was successfully received, * #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE otherwise. */ @@ -172,18 +172,18 @@ 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. +/** @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 * timeout is achieved. See #MSG_task_irecv for receiving tasks asynchronously. You can provide a -1 timeout * to obtain an infinite timeout. * - * \param task a memory location for storing a #msg_task_t. - * \param alias name of the mailbox to receive the task from - * \param timeout is the maximum wait time for completion (if -1, this call is the same as #MSG_task_receive) + * @param task a memory location for storing a #msg_task_t. + * @param alias name of the mailbox to receive the task from + * @param timeout is the maximum wait time for completion (if -1, this call is the same as #MSG_task_receive) * - * \return Returns + * @return Returns * #MSG_OK if the task was successfully received, * #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE, or #MSG_TIMEOUT otherwise. */ @@ -192,20 +192,20 @@ 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. +/** @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. - * \param alias name of the mailbox to receive the task from - * \param timeout is the maximum wait time for completion (if -1, this call is the same as #MSG_task_receive) - * \param rate limit the reception to rate bandwidth (byte/sec) + * @param task a memory location for storing a #msg_task_t. + * @param alias name of the mailbox to receive the task from + * @param timeout is the maximum wait time for completion (if -1, this call is the same as #MSG_task_receive) + * @param rate limit the reception to rate bandwidth (byte/sec) * * The rate parameter can be used to send a task with a limited * bandwidth (smaller than the physical available value). Use * MSG_task_receive() if you don't limit the rate (or pass -1 as a * rate value do disable this feature). * - * \return Returns + * @return Returns * #MSG_OK if the task was successfully received, * #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE, or #MSG_TIMEOUT otherwise. */ @@ -214,21 +214,21 @@ 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. +/** @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 * timeout is achieved. See #MSG_task_irecv for receiving tasks asynchronously. You can provide a -1 timeout * to obtain an infinite timeout. * - * \param task a memory location for storing a #msg_task_t. - * \param alias name of the mailbox to receive the task from - * \param timeout is the maximum wait time for completion (provide -1 for no timeout) - * \param host a #msg_host_t host from where the task was sent + * @param task a memory location for storing a #msg_task_t. + * @param alias name of the mailbox to receive the task from + * @param timeout is the maximum wait time for completion (provide -1 for no timeout) + * @param host a #msg_host_t host from where the task was sent * - * \return Returns + * @return Returns * #MSG_OK if the task was successfully received, -* #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE, or #MSG_TIMEOUT otherwise. + * #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE, or #MSG_TIMEOUT otherwise. */ msg_error_t MSG_task_receive_ext(msg_task_t * task, const char *alias, double timeout, msg_host_t host) { @@ -236,21 +236,21 @@ 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. +/** @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. - * \param alias name of the mailbox to receive the task from - * \param timeout is the maximum wait time for completion (provide -1 for no timeout) - * \param host a #msg_host_t host from where the task was sent - * \param rate limit the reception to rate bandwidth (byte/sec) + * @param task a memory location for storing a #msg_task_t. + * @param alias name of the mailbox to receive the task from + * @param timeout is the maximum wait time for completion (provide -1 for no timeout) + * @param host a #msg_host_t host from where the task was sent + * @param rate limit the reception to rate bandwidth (byte/sec) * * The rate parameter can be used to receive a task with a limited * bandwidth (smaller than the physical available value). Use * MSG_task_receive_ext() if you don't limit the rate (or pass -1 as a * rate value do disable this feature). * - * \return Returns + * @return Returns * #MSG_OK if the task was successfully received, * #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE, or #MSG_TIMEOUT otherwise. */ @@ -337,30 +337,30 @@ 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. +/** @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. * - * \param task a #msg_task_t to send on another location. - * \param alias name of the mailbox to sent the task to - * \return the msg_comm_t communication created + * @param task a #msg_task_t to send on another location. + * @param alias name of the mailbox to sent the task to + * @return the msg_comm_t communication created */ 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 +/** @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 * parameter allows the application to limit the bandwidth utilization of network links when sending the task. * - * \param task a #msg_task_t to send on another location. - * \param alias name of the mailbox to sent the task to - * \param maxrate the maximum communication rate for sending this task (byte/sec). - * \return the msg_comm_t communication created + * @param task a #msg_task_t to send on another location. + * @param alias name of the mailbox to sent the task to + * @param maxrate the maximum communication rate for sending this task (byte/sec). + * @return the msg_comm_t communication created */ msg_comm_t MSG_task_isend_bounded(msg_task_t task, const char *alias, double maxrate) { @@ -368,8 +368,8 @@ 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. +/** @ingroup msg_task_usage + * @brief Sends a task on a mailbox. * * This is a non blocking detached send function. * Think of it as a best effort send. Keep in mind that the third parameter is only called if the communication fails. @@ -378,9 +378,9 @@ msg_comm_t MSG_task_isend_bounded(msg_task_t task, const char *alias, double max * this thread * in the SimGrid-user mailing list archive. * - * \param task a #msg_task_t to send on another location. - * \param alias name of the mailbox to sent the task to - * \param cleanup a function to destroy the task if the communication fails, e.g. MSG_task_destroy + * @param task a #msg_task_t to send on another location. + * @param alias name of the mailbox to sent the task to + * @param cleanup a function to destroy the task if the communication fails, e.g. MSG_task_destroy * (if nullptr, no function will be called) */ void MSG_task_dsend(msg_task_t task, const char *alias, void_f_pvoid_t cleanup) @@ -389,8 +389,8 @@ 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. +/** @ingroup msg_task_usage + * @brief Sends a task on a mailbox with a maximal rate. * * This is a non blocking detached send function. * Think of it as a best effort send. Keep in mind that the third parameter is only called if the communication fails. @@ -404,12 +404,12 @@ void MSG_task_dsend(msg_task_t task, const char *alias, void_f_pvoid_t cleanup) * MSG_task_dsend() if you don't limit the rate (or pass -1 as a rate * value do disable this feature). * - * \param task a #msg_task_t to send on another location. - * \param alias name of the mailbox to sent the task to - * \param cleanup a function to destroy the task if the + * @param task a #msg_task_t to send on another location. + * @param alias name of the mailbox to sent the task to + * @param cleanup a function to destroy the task if the * communication fails, e.g. MSG_task_destroy * (if nullptr, no function will be called) - * \param maxrate the maximum communication rate for sending this task (byte/sec) + * @param maxrate the maximum communication rate for sending this task (byte/sec) * */ void MSG_task_dsend_bounded(msg_task_t task, const char *alias, void_f_pvoid_t cleanup, double maxrate) @@ -418,32 +418,32 @@ 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. +/** @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. * - * \param task a memory location for storing a #msg_task_t. has to be valid until the end of the communication. - * \param name of the mailbox to receive the task on - * \return the msg_comm_t communication created + * @param task a memory location for storing a #msg_task_t. has to be valid until the end of the communication. + * @param name of the mailbox to receive the task on + * @return the msg_comm_t communication created */ 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. +/** @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 * bandwidth (smaller than the physical available value). Use * MSG_task_irecv() if you don't limit the rate (or pass -1 as a rate * value do disable this feature). * - * \param task a memory location for storing a #msg_task_t. has to be valid until the end of the communication. - * \param name of the mailbox to receive the task on - * \param rate limit the bandwidth to the given rate (byte/sec) - * \return the msg_comm_t communication created + * @param task a memory location for storing a #msg_task_t. has to be valid until the end of the communication. + * @param name of the mailbox to receive the task on + * @param rate limit the bandwidth to the given rate (byte/sec) + * @return the msg_comm_t communication created */ msg_comm_t MSG_task_irecv_bounded(msg_task_t *task, const char *name, double rate) { @@ -464,10 +464,10 @@ 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 +/** @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 * (but it may have failed, use MSG_comm_get_status() to know its status) * or 'false' if the communication is not finished yet * If the status is 'false', don't forget to use MSG_process_sleep() after the test. @@ -501,10 +501,10 @@ 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 +/** @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 * (but it may have failed, use MSG_comm_get_status() to know its status), * or -1 if none is finished */ @@ -554,23 +554,23 @@ 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. +/** @ingroup msg_task_usage + * @brief Destroys a communication. + * @param comm the communication to destroy. */ void MSG_comm_destroy(msg_comm_t comm) { delete comm; } -/** \ingroup msg_task_usage - * \brief Wait for the completion of a communication. +/** @ingroup msg_task_usage + * @brief Wait for the completion of a communication. * * It takes two parameters. - * \param comm the communication to wait. - * \param timeout Wait until the communication terminates or the timeout occurs. + * @param comm the communication to wait. + * @param timeout Wait until the communication terminates or the timeout occurs. * You can provide a -1 timeout to obtain an infinite timeout. - * \return msg_error_t + * @return msg_error_t */ msg_error_t MSG_comm_wait(msg_comm_t comm, double timeout) { @@ -600,23 +600,23 @@ 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 -* -* \param comm a vector of communication -* \param nb_elem is the size of the comm vector -* \param timeout for each call of MSG_comm_wait -*/ +/** @ingroup msg_task_usage + * @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 + * @param timeout for each call of MSG_comm_wait + */ void MSG_comm_waitall(msg_comm_t * comm, int nb_elem, double timeout) { for (int i = 0; i < nb_elem; i++) MSG_comm_wait(comm[i], timeout); } -/** \ingroup msg_task_usage - * \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 +/** @ingroup msg_task_usage + * @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) */ int MSG_comm_waitany(xbt_dynar_t comms) @@ -669,10 +669,10 @@ 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 + * @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 * during the communication */ msg_error_t MSG_comm_get_status(msg_comm_t comm) { @@ -680,11 +680,11 @@ 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 +/** @ingroup msg_task_usage + * @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 + * @param comm the communication where to get the task + * @return the task from the communication */ msg_task_t MSG_comm_get_task(msg_comm_t comm) { @@ -694,10 +694,10 @@ msg_task_t MSG_comm_get_task(msg_comm_t comm) } /** - * \brief This function is called by SIMIX in kernel mode to copy the data of a comm. - * \param synchro the comm - * \param buff the data copied - * \param buff_size size of the buffer + * @brief This function is called by SIMIX in kernel mode to copy the data of a comm. + * @param synchro the comm + * @param buff the data copied + * @param buff_size size of the buffer */ void MSG_comm_copy_data_from_SIMIX(smx_activity_t synchro, void* buff, size_t buff_size) { @@ -713,17 +713,17 @@ 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 +/** @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 * side if #MSG_task_receive is used). * See #MSG_task_isend for sending tasks asynchronously. * - * \param task the task to be sent - * \param alias the mailbox name to where the task is sent + * @param task the task to be sent + * @param alias the mailbox name to where the task is sent * - * \return Returns #MSG_OK if the task was successfully sent, + * @return Returns #MSG_OK if the task was successfully sent, * #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE otherwise. */ msg_error_t MSG_task_send(msg_task_t task, const char *alias) @@ -732,8 +732,8 @@ 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 +/** @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 * the application to limit the bandwidth utilization of network links when sending the task. @@ -743,11 +743,11 @@ msg_error_t MSG_task_send(msg_task_t task, const char *alias) * MSG_task_send() if you don't limit the rate (or pass -1 as a rate * value do disable this feature). * - * \param task the task to be sent - * \param alias the mailbox name to where the task is sent - * \param maxrate the maximum communication rate for sending this task (byte/sec) + * @param task the task to be sent + * @param alias the mailbox name to where the task is sent + * @param maxrate the maximum communication rate for sending this task (byte/sec) * - * \return Returns #MSG_OK if the task was successfully sent, + * @return Returns #MSG_OK if the task was successfully sent, * #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE otherwise. */ msg_error_t MSG_task_send_bounded(msg_task_t task, const char *alias, double maxrate) @@ -756,16 +756,16 @@ 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 +/** @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. * - * \param task the task to be sent - * \param alias the mailbox name to where the task is sent - * \param timeout is the maximum wait time for completion (if -1, this call is the same as #MSG_task_send) + * @param task the task to be sent + * @param alias the mailbox name to where the task is sent + * @param timeout is the maximum wait time for completion (if -1, this call is the same as #MSG_task_send) * - * \return Returns #MSG_OK if the task was successfully sent, + * @return Returns #MSG_OK if the task was successfully sent, * #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE, or #MSG_TIMEOUT otherwise. */ msg_error_t MSG_task_send_with_timeout(msg_task_t task, const char *alias, double timeout) @@ -820,8 +820,8 @@ 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 +/** @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. * @@ -830,12 +830,12 @@ msg_error_t MSG_task_send_with_timeout(msg_task_t task, const char *alias, doubl * MSG_task_send_with_timeout() if you don't limit the rate (or pass -1 as a rate * value do disable this feature). * - * \param task the task to be sent - * \param alias the mailbox name to where the task is sent - * \param timeout is the maximum wait time for completion (if -1, this call is the same as #MSG_task_send) - * \param maxrate the maximum communication rate for sending this task (byte/sec) + * @param task the task to be sent + * @param alias the mailbox name to where the task is sent + * @param timeout is the maximum wait time for completion (if -1, this call is the same as #MSG_task_send) + * @param maxrate the maximum communication rate for sending this task (byte/sec) * - * \return Returns #MSG_OK if the task was successfully sent, + * @return Returns #MSG_OK if the task was successfully sent, * #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE, or #MSG_TIMEOUT otherwise. */ msg_error_t MSG_task_send_with_timeout_bounded(msg_task_t task, const char *alias, double timeout, double maxrate) @@ -844,12 +844,12 @@ 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. +/** @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 + * @param alias the name of the mailbox to be considered * - * \return Returns the PID of sender process, + * @return Returns the PID of sender process, * -1 if there is no communication in the mailbox. */ int MSG_task_listen_from(const char *alias) @@ -864,35 +864,35 @@ 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. +/** @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 * first parameter task must contain a task that was created with the function #MSG_task_create. The second * parameter category must contain a category that was previously declared with the function #TRACE_category * (or with #TRACE_category_with_color). * - * See \ref outcomes_vizu for details on how to trace the (categorized) resource utilization. + * See @ref outcomes_vizu for details on how to trace the (categorized) resource utilization. * - * \param task the task that is going to be categorized - * \param category the name of the category to be associated to the task + * @param task the task that is going to be categorized + * @param category the name of the category to be associated to the task * - * \see MSG_task_get_category, TRACE_category, TRACE_category_with_color + * @see MSG_task_get_category, TRACE_category, TRACE_category_with_color */ void MSG_task_set_category (msg_task_t task, const char *category) { TRACE_msg_set_task_category (task, category); } -/** \ingroup msg_task_usage +/** @ingroup msg_task_usage * - * \brief Gets the current tracing category of a task. + * @brief Gets the current tracing category of a task. * - * \param task the task to be considered + * @param task the task to be considered * - * \see MSG_task_set_category + * @see MSG_task_set_category * - * \return Returns the name of the tracing category of the given task, nullptr otherwise + * @return Returns the name of the tracing category of the given task, nullptr otherwise */ const char *MSG_task_get_category (msg_task_t task) { diff --git a/src/msg/msg_process.cpp b/src/msg/msg_process.cpp index 422f653ab5..16311deb63 100644 --- a/src/msg/msg_process.cpp +++ b/src/msg/msg_process.cpp @@ -27,8 +27,8 @@ std::string instr_pid(msg_process_t proc) /******************************** Process ************************************/ /** - * \brief Cleans the MSG data of an actor - * \param smx_actor a SIMIX actor + * @brief Cleans the MSG data of an actor + * @param smx_actor a SIMIX actor */ void MSG_process_cleanup_from_SIMIX(smx_actor_t smx_actor) { @@ -53,36 +53,36 @@ 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. +/** @ingroup m_process_management + * @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 + * (@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. +/** @ingroup m_process_management + * @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 name a name for the object. It is for user-level information and can be nullptr. - * \param code is a function describing the behavior of the process. It should then only use functions described - * in \ref m_process_management (to create a new #msg_process_t for example), - in \ref m_host_management (only the read-only functions i.e. whose name contains the word get), - in \ref m_task_management (to create or destroy some #msg_task_t for example) and - in \ref msg_task_usage (to handle file transfers and task processing). - * \param data a pointer to any data one may want to attach to the new object. It is for user-level information and - * can be nullptr. It can be retrieved with the function \ref MSG_process_get_data. - * \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. + * @param name a name for the object. It is for user-level information and can be nullptr. + * @param code is a function describing the behavior of the process. It should then only use functions described + * in @ref m_process_management (to create a new #msg_process_t for example), + in @ref m_host_management (only the read-only functions i.e. whose name contains the word get), + in @ref m_task_management (to create or destroy some #msg_task_t for example) and + in @ref msg_task_usage (to handle file transfers and task processing). + * @param data a pointer to any data one may want to attach to the new object. It is for user-level information and + * can be nullptr. It can be retrieved with the function @ref MSG_process_get_data. + * @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, @@ -91,26 +91,26 @@ msg_process_t MSG_process_create_with_arguments(const char *name, xbt_main_func_ return MSG_process_create_with_environment(name, code, data, host, argc, argv, nullptr); } -/** \ingroup m_process_management - * \brief Creates and runs a new #msg_process_t. +/** @ingroup m_process_management + * @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 name a name for the object. It is for user-level information and can be nullptr. - * \param code is a function describing the behavior of the process. It should then only use functions described - * in \ref m_process_management (to create a new #msg_process_t for example), - in \ref m_host_management (only the read-only functions i.e. whose name contains the word get), - in \ref m_task_management (to create or destroy some #msg_task_t for example) and - in \ref msg_task_usage (to handle file transfers and task processing). - * \param data a pointer to any data one may want to attach to the new object. It is for user-level information and - * can be nullptr. It can be retrieved with the function \ref MSG_process_get_data. - * \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. WARNING, these strings are freed by the SimGrid kernel when the + * @param name a name for the object. It is for user-level information and can be nullptr. + * @param code is a function describing the behavior of the process. It should then only use functions described + * in @ref m_process_management (to create a new #msg_process_t for example), + in @ref m_host_management (only the read-only functions i.e. whose name contains the word get), + in @ref m_task_management (to create or destroy some #msg_task_t for example) and + in @ref msg_task_usage (to handle file transfers and task processing). + * @param data a pointer to any data one may want to attach to the new object. It is for user-level information and + * can be nullptr. It can be retrieved with the function @ref MSG_process_get_data. + * @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. WARNING, these strings are freed by the SimGrid kernel when the * process exits, so they cannot be static nor shared between several processes. - * \param properties list a properties defined for this process - * \see msg_process_t - * \return The new corresponding object. + * @param properties list a properties defined for this process + * @see msg_process_t + * @return The new corresponding object. */ msg_process_t MSG_process_create_with_environment(const char *name, xbt_main_func_t code, void *data, msg_host_t host, int argc, char **argv, xbt_dict_t properties) @@ -185,10 +185,10 @@ void MSG_process_detach() SIMIX_process_detach(); } -/** \ingroup m_process_management - * \brief Returns the user data of a process. +/** @ingroup m_process_management + * @brief Returns the user data of a process. * - * This function checks whether \a process is a valid pointer and returns the user data associated to this process. + * This function checks whether @a process is a valid pointer and returns the user data associated to this process. */ void* MSG_process_get_data(msg_process_t process) { @@ -198,10 +198,10 @@ void* MSG_process_get_data(msg_process_t process) return process->get_impl()->get_user_data(); } -/** \ingroup m_process_management - * \brief Sets the user data of a process. +/** @ingroup m_process_management + * @brief Sets the user data of a process. * - * This function checks whether \a process is a valid pointer and sets the user data associated to this process. + * This function checks whether @a process is a valid pointer and sets the user data associated to this process. */ msg_error_t MSG_process_set_data(msg_process_t process, void *data) { @@ -212,9 +212,9 @@ msg_error_t MSG_process_set_data(msg_process_t process, void *data) return MSG_OK; } -/** \ingroup m_process_management - * \brief Sets a cleanup function to be called to free the userdata of a process when a process is destroyed. - * \param data_cleanup a cleanup function for the userdata of a process, or nullptr to call no function +/** @ingroup m_process_management + * @brief Sets a cleanup function to be called to free the userdata of a process when a process is destroyed. + * @param data_cleanup a cleanup function for the userdata of a process, or nullptr to call no function */ XBT_PUBLIC void MSG_process_set_data_cleanup(void_f_pvoid_t data_cleanup) { @@ -237,8 +237,8 @@ int MSG_process_get_number() return SIMIX_process_count(); } -/** \ingroup m_process_management - * \brief Return the PID of the current process. +/** @ingroup m_process_management + * @brief Return the PID of the current process. * * This function returns the PID of the currently running #msg_process_t. */ @@ -248,8 +248,8 @@ int MSG_process_self_PID() return self == nullptr ? 0 : self->pid_; } -/** \ingroup m_process_management - * \brief Return the PPID of the current process. +/** @ingroup m_process_management + * @brief Return the PPID of the current process. * * This function returns the PID of the parent of the currently running #msg_process_t. */ @@ -258,16 +258,16 @@ int MSG_process_self_PPID() return MSG_process_get_PPID(MSG_process_self()); } -/** \ingroup m_process_management - * \brief Return the name of the current process. +/** @ingroup m_process_management + * @brief Return the name of the current process. */ const char* MSG_process_self_name() { return SIMIX_process_self_get_name(); } -/** \ingroup m_process_management - * \brief Return the current process. +/** @ingroup m_process_management + * @brief Return the current process. * * This function returns the currently running #msg_process_t. */ @@ -280,8 +280,8 @@ smx_context_t MSG_process_get_smx_ctx(msg_process_t process) { // deprecated -- return process->get_impl()->context_; } /** - * \ingroup m_process_management - * \brief Add a function to the list of "on_exit" functions for the current process. + * @ingroup m_process_management + * @brief Add a function to the list of "on_exit" functions for the current process. * The on_exit functions are the functions executed when your process is killed. * You should use them to free the data used by your process. */ diff --git a/src/msg/msg_task.cpp b/src/msg/msg_task.cpp index 57b1636953..1ae411724b 100644 --- a/src/msg/msg_task.cpp +++ b/src/msg/msg_task.cpp @@ -32,19 +32,19 @@ void s_simdata_task_t::reportMultipleUse() const } /********************************* Task **************************************/ -/** \ingroup m_task_management - * \brief Creates a new #msg_task_t. +/** @ingroup m_task_management + * @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. - * \param flop_amount a value of the processing amount (in flop) needed to process this new task. + * @param name a name for the object. It is for user-level information and can be nullptr. + * @param flop_amount a value of the processing amount (in flop) needed to process this new task. * If 0, then it cannot be executed with MSG_task_execute(). This value has to be >=0. - * \param message_size a value of the amount of data (in bytes) needed to transfer this new task. If 0, then it cannot + * @param message_size a value of the amount of data (in bytes) needed to transfer this new task. If 0, then it cannot * be transfered with MSG_task_send() and MSG_task_recv(). This value has to be >=0. - * \param data a pointer to any data may want to attach to the new object. It is for user-level information and can - * be nullptr. It can be retrieved with the function \ref MSG_task_get_data. - * \see msg_task_t - * \return The new corresponding object. + * @param data a pointer to any data may want to attach to the new object. It is for user-level information and can + * be nullptr. It can be retrieved with the function @ref MSG_task_get_data. + * @see msg_task_t + * @return The new corresponding object. */ msg_task_t MSG_task_create(const char *name, double flop_amount, double message_size, void *data) { @@ -65,21 +65,21 @@ 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....). +/** @ingroup m_task_management + * @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. - * \param host_nb the number of hosts implied in the parallel task. - * \param host_list an array of \p host_nb msg_host_t. - * \param flops_amount an array of \p host_nb doubles. + * @param name a name for the object. It is for user-level information and can be nullptr. + * @param host_nb the number of hosts implied in the parallel task. + * @param host_list an array of @p host_nb msg_host_t. + * @param flops_amount an array of @p host_nb doubles. * flops_amount[i] is the total number of operations that have to be performed on host_list[i]. - * \param bytes_amount an array of \p host_nb* \p host_nb doubles. - * \param data a pointer to any data may want to attach to the new object. + * @param bytes_amount an array of @p host_nb* @p host_nb doubles. + * @param data a pointer to any data may want to attach to the new object. * It is for user-level information and can be nullptr. - * It can be retrieved with the function \ref MSG_task_get_data. - * \see msg_task_t - * \return The new corresponding object. + * It can be retrieved with the function @ref MSG_task_get_data. + * @see msg_task_t + * @return The new corresponding object. */ msg_task_t MSG_parallel_task_create(const char *name, int host_nb, const msg_host_t * host_list, double *flops_amount, double *bytes_amount, void *data) @@ -105,29 +105,29 @@ 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. +/** @ingroup m_task_management + * @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. + * This function checks whether @a task is a valid pointer and return the user data associated to @a task if possible. */ void *MSG_task_get_data(msg_task_t task) { return (task->data); } -/** \ingroup m_task_management - * \brief Sets the user data of a #msg_task_t. +/** @ingroup m_task_management + * @brief Sets the user data of a #msg_task_t. * - * This function allows to associate a new pointer to the user data associated of \a task. + * This function allows to associate a new pointer to the user data associated of @a task. */ 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. - * \param callback a callback function +/** @ingroup m_task_management + * @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 +140,8 @@ 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. +/** @ingroup m_task_management + * @brief Return the sender of a #msg_task_t. * * This functions returns the #msg_process_t which sent this task */ @@ -150,8 +150,8 @@ 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. +/** @ingroup m_task_management + * @brief Return the source of a #msg_task_t. * * This functions returns the #msg_host_t from which this task was sent */ @@ -160,8 +160,8 @@ 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. +/** @ingroup m_task_management + * @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 +170,8 @@ 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. +/** @ingroup m_task_management + * @brief Sets the name of a #msg_task_t. * * This functions allows to associate a name to a task */ @@ -180,10 +180,10 @@ 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. +/** @ingroup m_task_management + * @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. + * Destructor for #msg_task_t. Note that you should free user data, if any, @b before calling this function. * * Only the process that owns the task can destroy it. * The owner changes after a successful send. @@ -208,9 +208,9 @@ msg_error_t MSG_task_destroy(msg_task_t task) return MSG_OK; } -/** \ingroup m_task_usage - * \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. +/** @ingroup m_task_usage + * @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 +226,8 @@ 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 +/** @ingroup m_task_management + * @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 +244,8 @@ 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 +/** @ingroup m_task_management + * @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,10 +263,10 @@ 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. +/** @ingroup m_task_management + * @brief set the computation amount needed to process a task #msg_task_t. * - * \warning If the computation is ongoing (already started and not finished), + * @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 * zero, overriding any value set during the execution. */ @@ -275,18 +275,18 @@ 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. +/** @ingroup m_task_management + * @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. + * @warning If the transfer is ongoing (already started and not finished), it is not modified by this call. */ 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. +/** @ingroup m_task_management + * @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 +296,8 @@ 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. +/** @ingroup m_task_management + * @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 +305,8 @@ 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 +/** @ingroup m_task_management + * @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 +316,8 @@ 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. +/** @ingroup m_task_management + * @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/src/plugins/file_system/s4u_FileSystem.cpp b/src/plugins/file_system/s4u_FileSystem.cpp index 744ae26352..e65a763f1f 100644 --- a/src/plugins/file_system/s4u_FileSystem.cpp +++ b/src/plugins/file_system/s4u_FileSystem.cpp @@ -115,10 +115,10 @@ sg_size_t File::read(sg_size_t size) return read_size; } -/** \brief Write into a file (local or remote) +/** @brief Write into a file (local or remote) * - * \param size of the file to write - * \return the number of bytes successfully write or -1 if an error occurred + * @param size of the file to write + * @return the number of bytes successfully write or -1 if an error occurred */ sg_size_t File::write(sg_size_t size) { @@ -404,12 +404,12 @@ void sg_file_set_data(sg_file_t fd, void* data) } /** - * \brief Set the file position indicator in the sg_file_t by adding offset bytes + * @brief Set the file position indicator in the sg_file_t by adding offset bytes * to the position specified by origin (either SEEK_SET, SEEK_CUR, or SEEK_END). * - * \param fd : file object that identifies the stream - * \param offset : number of bytes to offset from origin - * \param origin : Position used as reference for the offset. It is specified by one of the following constants defined + * @param fd : file object that identifies the stream + * @param offset : number of bytes to offset from origin + * @param origin : Position used as reference for the offset. It is specified by one of the following constants defined * in \ exclusively to be used as arguments for this function (SEEK_SET = beginning of file, * SEEK_CUR = current position of the file pointer, SEEK_END = end of file) */ @@ -435,11 +435,11 @@ void sg_file_unlink(sg_file_t fd) } /** - * \brief Copy a file to another location on a remote host. - * \param file : the file to move - * \param host : the remote host where the file has to be copied - * \param fullpath : the complete path destination on the remote host - * \return If successful, the function returns 0. Otherwise, it returns -1. + * @brief Copy a file to another location on a remote host. + * @param file : the file to move + * @param host : the remote host where the file has to be copied + * @param fullpath : the complete path destination on the remote host + * @return If successful, the function returns 0. Otherwise, it returns -1. */ int sg_file_rcopy(sg_file_t file, sg_host_t host, const char* fullpath) { @@ -447,11 +447,11 @@ int sg_file_rcopy(sg_file_t file, sg_host_t host, const char* fullpath) } /** - * \brief Move a file to another location on a remote host. - * \param file : the file to move - * \param host : the remote host where the file has to be moved - * \param fullpath : the complete path destination on the remote host - * \return If successful, the function returns 0. Otherwise, it returns -1. + * @brief Move a file to another location on a remote host. + * @param file : the file to move + * @param host : the remote host where the file has to be moved + * @param fullpath : the complete path destination on the remote host + * @return If successful, the function returns 0. Otherwise, it returns -1. */ int sg_file_rmove(sg_file_t file, sg_host_t host, const char* fullpath) { diff --git a/src/plugins/host_dvfs.cpp b/src/plugins/host_dvfs.cpp index b62cc98a93..9e09300f93 100644 --- a/src/plugins/host_dvfs.cpp +++ b/src/plugins/host_dvfs.cpp @@ -291,10 +291,9 @@ static void on_host_added(simgrid::s4u::Host& host) /* **************************** Public interface *************************** */ - -/** \ingroup SURF_plugin_load - * \brief Initializes the HostDvfs plugin - * \details The HostDvfs plugin provides an API to get the current load of each host. +/** @ingroup SURF_plugin_load + * @brief Initializes the HostDvfs plugin + * @details The HostDvfs plugin provides an API to get the current load of each host. */ void sg_host_dvfs_plugin_init() { diff --git a/src/plugins/host_energy.cpp b/src/plugins/host_energy.cpp index e166ac5bed..74417363b6 100644 --- a/src/plugins/host_energy.cpp +++ b/src/plugins/host_energy.cpp @@ -29,26 +29,26 @@ abnormality when all the cores are idle. The full details are in As a result, our energy model takes 4 parameters: - - \b Idle: instantaneous consumption (in Watt) when your host is up and running, but without anything to do. - - \b OneCore: instantaneous consumption (in Watt) when only one core is active, at 100%. - - \b AllCores: instantaneous consumption (in Watt) when all cores of the host are at 100%. - - \b Off: instantaneous consumption (in Watt) when the host is turned off. + - @b Idle: instantaneous consumption (in Watt) when your host is up and running, but without anything to do. + - @b OneCore: instantaneous consumption (in Watt) when only one core is active, at 100%. + - @b AllCores: instantaneous consumption (in Watt) when all cores of the host are at 100%. + - @b Off: instantaneous consumption (in Watt) when the host is turned off. Here is an example of XML declaration: -\code{.xml} +@code{.xml} -\endcode +@endcode -This example gives the following parameters: \b Off is 10 Watts; \b Idle is 100 Watts; \b OneCore is 120 Watts and \b +This example gives the following parameters: @b Off is 10 Watts; @b Idle is 100 Watts; @b OneCore is 120 Watts and @b AllCores is 200 Watts. This is enough to compute the consumption as a function of the amount of loaded cores: - + @@ -64,27 +64,27 @@ the time, and our model holds. ### What if the host has only one core? -In this case, the parameters \b OneCore and \b AllCores are obviously the same. +In this case, the parameters @b OneCore and @b AllCores are obviously the same. Actually, SimGrid expect an energetic profile formatted as 'Idle:Running' for mono-cores hosts. -If you insist on passing 3 parameters in this case, then you must have the same value for \b OneCore and \b AllCores. +If you insist on passing 3 parameters in this case, then you must have the same value for @b OneCore and @b AllCores. -\code{.xml} +@code{.xml} -\endcode +@endcode ### How does DVFS interact with the host energy model? If your host has several DVFS levels (several pstates), then you should give the energetic profile of each pstate level: -\code{.xml} +@code{.xml} -\endcode +@endcode This encodes the following values
\#Cores loadedConsumptionExplanation
@#Cores loadedConsumptionExplanation
0 100 WattsIdle value
1 120 WattsOneCore value
2 147 Wattslinear extrapolation between OneCore and AllCores
@@ -450,9 +450,9 @@ static void on_simulation_end() /* **************************** Public interface *************************** */ -/** \ingroup plugin_energy - * \brief Enable host energy plugin - * \details Enable energy plugin to get joules consumption of each cpu. Call this function before #MSG_init(). +/** @ingroup plugin_energy + * @brief Enable host energy plugin + * @details Enable energy plugin to get joules consumption of each cpu. Call this function before #MSG_init(). */ void sg_host_energy_plugin_init() { diff --git a/src/plugins/host_load.cpp b/src/plugins/host_load.cpp index 264ea2d095..f584bbad12 100644 --- a/src/plugins/host_load.cpp +++ b/src/plugins/host_load.cpp @@ -72,7 +72,7 @@ void HostLoad::update() { double now = surf_get_clock(); - /* Current flop per second computed by the cpu; current_flops = k * pstate_speed_in_flops, k \in {0, 1, ..., cores} + /* Current flop per second computed by the cpu; current_flops = k * pstate_speed_in_flops, k @in {0, 1, ..., cores} * number of active cores */ current_flops_ = host_->pimpl_cpu->get_constraint()->get_usage(); @@ -151,9 +151,9 @@ static void on_action_state_change(simgrid::surf::CpuAction* action, simgrid::ke /* **************************** Public interface *************************** */ -/** \ingroup plugin_load - * \brief Initializes the HostLoad plugin - * \details The HostLoad plugin provides an API to get the current load of each host. +/** @ingroup plugin_load + * @brief Initializes the HostLoad plugin + * @details The HostLoad plugin provides an API to get the current load of each host. */ void sg_host_load_plugin_init() { diff --git a/src/plugins/link_energy.cpp b/src/plugins/link_energy.cpp index a0b7cd413f..8bf16970b4 100644 --- a/src/plugins/link_energy.cpp +++ b/src/plugins/link_energy.cpp @@ -22,12 +22,12 @@ SIMGRID_REGISTER_PLUGIN(link_energy, "Link energy consumption.", &sg_link_energy The energy consumption of a link depends directly on its current traffic load. Specify that consumption in your platform file as follows: - \verbatim + @verbatim - \endverbatim + @endverbatim The first property means that when your link is switched on, but without anything to do, it will dissipate 100 Watts. If it's fully loaded, it will dissipate 200 Watts. If its load is at 50%, then it will dissipate 150 Watts. @@ -178,9 +178,9 @@ int sg_link_energy_is_inited() { return LinkEnergy::EXTENSION_ID.valid(); } -/** \ingroup SURF_plugin_energy - * \brief Enable energy plugin - * \details Enable energy plugin to get joules consumption of each cpu. You should call this function before +/** @ingroup SURF_plugin_energy + * @brief Enable energy plugin + * @details Enable energy plugin to get joules consumption of each cpu. You should call this function before * #MSG_init(). */ void sg_link_energy_plugin_init() diff --git a/src/s4u/s4u_Actor.cpp b/src/s4u/s4u_Actor.cpp index 64b2758f62..3548aba60b 100644 --- a/src/s4u/s4u_Actor.cpp +++ b/src/s4u/s4u_Actor.cpp @@ -171,7 +171,7 @@ void Actor::set_kill_time(double time) simcall_process_set_kill_time(pimpl_, time); } -/** \brief Get the kill time of an actor(or 0 if unset). */ +/** @brief Get the kill time of an actor(or 0 if unset). */ double Actor::get_kill_time() { return SIMIX_timer_get_date(pimpl_->kill_timer); @@ -434,10 +434,10 @@ void kill() /* deprecated */ /* **************************** Public C interface *************************** */ -/** \ingroup m_actor_management - * \brief Returns the process ID of \a actor. +/** @ingroup m_actor_management + * @brief Returns the process ID of @a actor. * - * This function checks whether \a actor is a valid pointer and return its PID (or 0 in case of problem). + * This function checks whether @a actor is a valid pointer and return its PID (or 0 in case of problem). */ int sg_actor_get_PID(sg_actor_t actor) { @@ -448,10 +448,10 @@ int sg_actor_get_PID(sg_actor_t actor) return actor->get_pid(); } -/** \ingroup m_actor_management - * \brief Returns the process ID of the parent of \a actor. +/** @ingroup m_actor_management + * @brief Returns the process ID of the parent of @a actor. * - * This function checks whether \a actor is a valid pointer and return its parent's PID. + * This function checks whether @a actor is a valid pointer and return its parent's PID. * Returns -1 if the actor has not been created by any other actor. */ int sg_actor_get_PPID(sg_actor_t actor) @@ -459,12 +459,12 @@ int sg_actor_get_PPID(sg_actor_t actor) return actor->get_ppid(); } -/** \ingroup m_actor_management +/** @ingroup m_actor_management * - * \brief Return a #sg_actor_t given its PID. + * @brief Return a #sg_actor_t given its PID. * - * This function search in the list of all the created sg_actor_t for a sg_actor_t whose PID is equal to \a PID. - * If none is found, \c nullptr is returned. + * This function search in the list of all the created sg_actor_t for a sg_actor_t whose PID is equal to @a PID. + * If none is found, @c nullptr is returned. Note that the PID are unique in the whole simulation, not only on a given host. */ sg_actor_t sg_actor_by_PID(aid_t pid) @@ -472,8 +472,8 @@ sg_actor_t sg_actor_by_PID(aid_t pid) return simgrid::s4u::Actor::by_pid(pid).get(); } -/** \ingroup m_actor_management - * \brief Return the name of an actor. +/** @ingroup m_actor_management + * @brief Return the name of an actor. */ const char* sg_actor_get_name(sg_actor_t actor) { @@ -485,20 +485,20 @@ sg_host_t sg_actor_get_host(sg_actor_t actor) return actor->get_host(); } -/** \ingroup m_actor_management - * \brief Returns the value of a given actor property +/** @ingroup m_actor_management + * @brief Returns the value of a given actor property * - * \param actor an actor - * \param name a property name - * \return value of a property (or nullptr if the property is not set) + * @param actor an actor + * @param name a property name + * @return value of a property (or nullptr if the property is not set) */ const char* sg_actor_get_property_value(sg_actor_t actor, const char* name) { return actor->get_property(name); } -/** \ingroup m_actor_management - * \brief Return the list of properties +/** @ingroup m_actor_management + * @brief Return the list of properties * * This function returns all the parameters associated with an actor */ @@ -515,8 +515,8 @@ xbt_dict_t sg_actor_get_properties(sg_actor_t actor) return as_dict; } -/** \ingroup m_actor_management - * \brief Suspend the actor. +/** @ingroup m_actor_management + * @brief Suspend the actor. * * This function suspends the actor by suspending the task on which it was waiting for the completion. */ @@ -526,8 +526,8 @@ void sg_actor_suspend(sg_actor_t actor) actor->suspend(); } -/** \ingroup m_actor_management - * \brief Resume a suspended actor. +/** @ingroup m_actor_management + * @brief Resume a suspended actor. * * This function resumes a suspended actor by resuming the task on which it was waiting for the completion. */ @@ -537,8 +537,8 @@ void sg_actor_resume(sg_actor_t actor) actor->resume(); } -/** \ingroup m_actor_management - * \brief Returns true if the actor is suspended . +/** @ingroup m_actor_management + * @brief Returns true if the actor is suspended . * * This checks whether an actor is suspended or not by inspecting the task on which it was waiting for the completion. */ @@ -548,8 +548,8 @@ int sg_actor_is_suspended(sg_actor_t actor) } /** - * \ingroup m_actor_management - * \brief Restarts an actor from the beginning. + * @ingroup m_actor_management + * @brief Restarts an actor from the beginning. */ sg_actor_t sg_actor_restart(sg_actor_t actor) { @@ -557,8 +557,8 @@ sg_actor_t sg_actor_restart(sg_actor_t actor) } /** - * \ingroup m_actor_management - * \brief Sets the "auto-restart" flag of the actor. + * @ingroup m_actor_management + * @brief Sets the "auto-restart" flag of the actor. * If the flag is set to 1, the actor will be automatically restarted when its host comes back up. */ void sg_actor_set_auto_restart(sg_actor_t actor, int auto_restart) @@ -574,21 +574,21 @@ void sg_actor_daemonize(sg_actor_t actor) actor->daemonize(); } -/** \ingroup m_actor_management - * \brief Migrates an actor to another location. +/** @ingroup m_actor_management + * @brief Migrates an actor to another location. * - * This function changes the value of the #sg_host_t on which \a actor is running. + * This function changes the value of the #sg_host_t on which @a actor is running. */ void sg_actor_migrate(sg_actor_t process, sg_host_t host) { process->migrate(host); } -/** \ingroup m_actor_management - * \brief Wait for the completion of a #sg_actor_t. +/** @ingroup m_actor_management + * @brief Wait for the completion of a #sg_actor_t. * - * \param actor the actor to wait for - * \param timeout wait until the actor is over, or the timeout expires + * @param actor the actor to wait for + * @param timeout wait until the actor is over, or the timeout expires */ void sg_actor_join(sg_actor_t actor, double timeout) { @@ -605,11 +605,11 @@ void sg_actor_kill_all() simgrid::s4u::Actor::kill_all(); } -/** \ingroup m_actor_management - * \brief Set the kill time of an actor. +/** @ingroup m_actor_management + * @brief Set the kill time of an actor. * - * \param actor an actor - * \param kill_time the time when the actor is killed. + * @param actor an actor + * @param kill_time the time when the actor is killed. */ void sg_actor_set_kill_time(sg_actor_t actor, double kill_time) { diff --git a/src/s4u/s4u_Host.cpp b/src/s4u/s4u_Host.cpp index 4ad611bd3e..ceed115d6a 100644 --- a/src/s4u/s4u_Host.cpp +++ b/src/s4u/s4u_Host.cpp @@ -116,7 +116,7 @@ int Host::get_pstate_count() const } /** - * \brief Return a copy of the list of actors that are executing on this host. + * @brief Return a copy of the list of actors that are executing on this host. * * Daemons and regular actors are all mixed in this list. */ @@ -148,13 +148,13 @@ void Host::actorList(std::vector* whereto) } /** - * \brief Find a route toward another host + * @brief Find a route toward another host * - * \param dest [IN] where to - * \param links [OUT] where to store the list of links (must exist, cannot be nullptr). - * \param latency [OUT] where to store the latency experienced on the path (or nullptr if not interested) + * @param dest [IN] where to + * @param links [OUT] where to store the list of links (must exist, cannot be nullptr). + * @param latency [OUT] where to store the latency experienced on the path (or nullptr if not interested) * It is the caller responsibility to initialize latency to 0 (we add to provided route) - * \pre links!=nullptr + * @pre links!=nullptr * * walk through the routing components tree and find a route between hosts * by calling each "get_route" function in each routing component. @@ -255,9 +255,9 @@ int Host::get_pstate() const } /** - * \ingroup simix_storage_management - * \brief Returns the list of storages attached to an host. - * \return a vector containing all storages attached to the host + * @ingroup simix_storage_management + * @brief Returns the list of storages attached to an host. + * @return a vector containing all storages attached to the host */ std::vector Host::get_attached_storages() const { @@ -305,11 +305,11 @@ size_t sg_host_count() * * Uses sg_host_count() to know the array size. * - * \return an array of \ref sg_host_t containing all the hosts in the platform. - * \remark The host order in this array is generally different from the + * @return an array of @ref sg_host_t containing all the hosts in the platform. + * @remark The host order in this array is generally different from the * creation/declaration order in the XML platform (we use a hash table * internally). - * \see sg_host_count() + * @see sg_host_count() */ sg_host_t* sg_host_list() { @@ -409,22 +409,22 @@ double sg_host_speed(sg_host_t host) return host->get_speed(); } -/** \brief Return the speed of the processor (in flop/s) at a given pstate. See also @ref plugin_energy. +/** @brief Return the speed of the processor (in flop/s) at a given pstate. See also @ref plugin_energy. * - * \param host host to test - * \param pstate_index pstate to test - * \return Returns the processor speed associated with pstate_index + * @param host host to test + * @param pstate_index pstate to test + * @return Returns the processor speed associated with pstate_index */ double sg_host_get_pstate_speed(sg_host_t host, int pstate_index) { return host->get_pstate_speed(pstate_index); } -/** \ingroup m_host_management - * \brief Return the number of cores. +/** @ingroup m_host_management + * @brief Return the number of cores. * - * \param host a host - * \return the number of cores + * @param host a host + * @return the number of cores */ int sg_host_core_count(sg_host_t host) { @@ -462,9 +462,9 @@ void sg_host_set_pstate(sg_host_t host, int pstate) host->set_pstate(pstate); } -/** \ingroup m_host_management +/** @ingroup m_host_management * - * \brief Start the host if it is off + * @brief Start the host if it is off * * See also #sg_host_is_on() and #sg_host_is_off() to test the current state of the host and @ref plugin_energy * for more info on DVFS. @@ -474,9 +474,9 @@ void sg_host_turn_on(sg_host_t host) host->turn_on(); } -/** \ingroup m_host_management +/** @ingroup m_host_management * - * \brief Stop the host if it is on + * @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 plugin_energy * for more info on DVFS. @@ -524,13 +524,13 @@ xbt_dict_t sg_host_get_properties(sg_host_t host) return as_dict; } -/** \ingroup m_host_management - * \brief Returns the value of a given host property +/** @ingroup m_host_management + * @brief Returns the value of a given host property * - * \param host a host - * \param name a property name - * \return value of a property (or nullptr if property not set) -*/ + * @param host a host + * @param name a property name + * @return value of a property (or nullptr if property not set) + */ const char* sg_host_get_property_value(sg_host_t host, const char* name) { return host->get_property(name); @@ -542,11 +542,11 @@ void sg_host_set_property_value(sg_host_t host, const char* name, const char* va } /** - * \brief Find a route between two hosts + * @brief Find a route between two hosts * - * \param from where from - * \param to where to - * \param links [OUT] where to store the list of links (must exist, cannot be nullptr). + * @param from where from + * @param to where to + * @param links [OUT] where to store the list of links (must exist, cannot be nullptr). */ void sg_host_route(sg_host_t from, sg_host_t to, xbt_dynar_t links) { @@ -556,10 +556,10 @@ void sg_host_route(sg_host_t from, sg_host_t to, xbt_dynar_t links) xbt_dynar_push(links, &link); } /** - * \brief Find the latency of the route between two hosts + * @brief Find the latency of the route between two hosts * - * \param from where from - * \param to where to + * @param from where from + * @param to where to */ double sg_host_route_latency(sg_host_t from, sg_host_t to) { @@ -569,10 +569,10 @@ double sg_host_route_latency(sg_host_t from, sg_host_t to) return res; } /** - * \brief Find the bandwitdh of the route between two hosts + * @brief Find the bandwitdh of the route between two hosts * - * \param from where from - * \param to where to + * @param from where from + * @param to where to */ double sg_host_route_bandwidth(sg_host_t from, sg_host_t to) { @@ -604,10 +604,10 @@ void sg_host_dump(sg_host_t host) } } -/** \brief Return the list of actors attached to an host. +/** @brief Return the list of actors attached to an host. * - * \param host a host - * \param whereto a dynar in which we should push actors living on that host + * @param host a host + * @param whereto a dynar in which we should push actors living on that host */ void sg_host_get_actor_list(sg_host_t host, xbt_dynar_t whereto) { diff --git a/src/s4u/s4u_Mailbox.cpp b/src/s4u/s4u_Mailbox.cpp index a810de4770..e33292eb30 100644 --- a/src/s4u/s4u_Mailbox.cpp +++ b/src/s4u/s4u_Mailbox.cpp @@ -140,13 +140,13 @@ void* Mailbox::get(double timeout) } // namespace simgrid /* **************************** Public C interface *************************** */ -/** \brief Set the mailbox to receive in asynchronous mode +/** @brief Set the mailbox to receive in asynchronous 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. * - * \param alias The name of the mailbox + * @param alias The name of the mailbox */ void sg_mailbox_set_receiver(const char* alias) { @@ -154,10 +154,10 @@ void sg_mailbox_set_receiver(const char* alias) XBT_VERB("%s mailbox set to receive eagerly for myself\n", alias); } -/** \brief Check if there is a communication going on in a mailbox. +/** @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 + * @param alias the name of the mailbox to be considered + * @return Returns 1 if there is a communication, 0 otherwise */ int sg_mailbox_listen(const char* alias) { diff --git a/src/s4u/s4u_Storage.cpp b/src/s4u/s4u_Storage.cpp index 3c54d8655f..84319d81a6 100644 --- a/src/s4u/s4u_Storage.cpp +++ b/src/s4u/s4u_Storage.cpp @@ -81,9 +81,9 @@ void getStorageList(std::map* whereTo) * (#sg_storage_t) and the functions for managing it. */ -/** \ingroup sg_storage_management +/** @ingroup sg_storage_management * - * \brief Returns the name of the #sg_storage_t. + * @brief Returns the name of the #sg_storage_t. * * This functions checks whether a storage is a valid pointer or not and return its name. */ @@ -99,10 +99,10 @@ const char* sg_storage_get_host(sg_storage_t storage) return storage->get_host()->get_cname(); } -/** \ingroup sg_storage_management - * \brief Returns a xbt_dict_t consisting of the list of properties assigned to this storage - * \param storage a storage - * \return a dict containing the properties +/** @ingroup sg_storage_management + * @brief Returns a xbt_dict_t consisting of the list of properties assigned to this storage + * @param storage a storage + * @return a dict containing the properties */ xbt_dict_t sg_storage_get_properties(sg_storage_t storage) { @@ -117,42 +117,42 @@ xbt_dict_t sg_storage_get_properties(sg_storage_t storage) return as_dict; } -/** \ingroup sg_storage_management - * \brief Change the value of a given storage property +/** @ingroup sg_storage_management + * @brief Change the value of a given storage property * - * \param storage a storage - * \param name a property name - * \param value what to change the property to + * @param storage a storage + * @param name a property name + * @param value what to change the property to */ void sg_storage_set_property_value(sg_storage_t storage, const char* name, const char* value) { storage->set_property(name, value); } -/** \ingroup sg_storage_management - * \brief Returns the value of a given storage property +/** @ingroup sg_storage_management + * @brief Returns the value of a given storage property * - * \param storage a storage - * \param name a property name - * \return value of a property (or nullptr if property not set) + * @param storage a storage + * @param name a property name + * @return value of a property (or nullptr if property not set) */ const char* sg_storage_get_property_value(sg_storage_t storage, const char* name) { return storage->get_property(name); } -/** \ingroup sg_storage_management - * \brief Finds a sg_storage_t using its name. - * \param name the name of a storage - * \return the corresponding storage +/** @ingroup sg_storage_management + * @brief Finds a sg_storage_t using its name. + * @param name the name of a storage + * @return the corresponding storage */ sg_storage_t sg_storage_get_by_name(const char* name) { return simgrid::s4u::Storage::by_name(name); } -/** \ingroup sg_storage_management - * \brief Returns a dynar containing all the storage elements declared at a given point of time +/** @ingroup sg_storage_management + * @brief Returns a dynar containing all the storage elements declared at a given point of time */ xbt_dynar_t sg_storages_as_dynar() { diff --git a/src/simdag/sd_global.cpp b/src/simdag/sd_global.cpp index 09236e02a9..349808f26b 100644 --- a/src/simdag/sd_global.cpp +++ b/src/simdag/sd_global.cpp @@ -134,9 +134,9 @@ std::set* simulate(double how_long){ } /** - * \brief helper for pretty printing of task state - * \param state the state of a task - * \return the equivalent as a readable string + * @brief helper for pretty printing of task state + * @param state the state of a task + * @return the equivalent as a readable string */ const char *__get_state_name(e_SD_task_state_t state){ static std::string state_names[7] = @@ -145,13 +145,13 @@ const char *__get_state_name(e_SD_task_state_t state){ } /** - * \brief Initializes SD internal data + * @brief Initializes SD internal data * * This function must be called before any other SD function. Then you should call SD_create_environment(). * - * \param argc argument number - * \param argv argument list - * \see SD_create_environment(), SD_exit() + * @param argc argument number + * @param argv argument list + * @see SD_create_environment(), SD_exit() */ void SD_init_nocheck(int *argc, char **argv) { @@ -169,7 +169,7 @@ void SD_init_nocheck(int *argc, char **argv) } } -/** \brief set a configuration variable +/** @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. @@ -182,21 +182,21 @@ void SD_config(const char *key, const char *value){ } /** - * \brief Creates the environment + * @brief Creates the environment * - * The environment (i.e. the \ref SD_host_api "hosts" and the \ref SD_link_api "links") is created with + * The environment (i.e. the @ref SD_host_api "hosts" and the @ref SD_link_api "links") is created with * the data stored in the given XML platform file. * - * \param platform_file name of an XML file describing the environment to create - * \see SD_host_api, SD_link_api + * @param platform_file name of an XML file describing the environment to create + * @see SD_host_api, SD_link_api * * The XML file follows this DTD: * - * \include simgrid.dtd + * @include simgrid.dtd * * Here is a small example of such a platform: * - * \include small_platform.xml + * @include small_platform.xml */ void SD_create_environment(const char *platform_file) { @@ -211,18 +211,18 @@ void SD_create_environment(const char *platform_file) } /** - * \brief Launches the simulation. + * @brief Launches the simulation. * - * The function will execute the \ref SD_RUNNABLE runnable tasks. - * If \a how_long is positive, then the simulation will be stopped either when time reaches \a how_long or when a watch + * The function will execute the @ref SD_RUNNABLE runnable tasks. + * If @a how_long is positive, then the simulation will be stopped either when time reaches @a how_long or when a watch * point is reached. - * A non-positive value for \a how_long means no time limit, in which case the simulation will be stopped either when a + * A non-positive value for @a how_long means no time limit, in which case the simulation will be stopped either when a * watch point is reached or when no more task can be executed. * Then you can call SD_simulate() again. * - * \param how_long maximum duration of the simulation (a negative value means no time limit) - * \return a dynar of \ref SD_task_t whose state has changed. - * \see SD_task_schedule(), SD_task_watch() + * @param how_long maximum duration of the simulation (a negative value means no time limit) + * @return a dynar of @ref SD_task_t whose state has changed. + * @see SD_task_schedule(), SD_task_watch() */ void SD_simulate(double how_long) { @@ -242,9 +242,9 @@ double SD_get_clock() { } /** - * \brief Destroys all SD internal data + * @brief Destroys all SD internal data * This function should be called when the simulation is over. Don't forget to destroy too. - * \see SD_init(), SD_task_destroy() + * @see SD_init(), SD_task_destroy() */ void SD_exit() { diff --git a/src/simdag/sd_task.cpp b/src/simdag/sd_task.cpp index 2894ffa96f..aa2fb4d337 100644 --- a/src/simdag/sd_task.cpp +++ b/src/simdag/sd_task.cpp @@ -24,13 +24,13 @@ static void __SD_task_destroy_scheduling_data(SD_task_t task) } /** - * \brief Creates a new task. + * @brief Creates a new task. * - * \param name the name of the task (can be \c nullptr) - * \param data the user data you want to associate with the task (can be \c nullptr) - * \param amount amount of the task - * \return the new task - * \see SD_task_destroy() + * @param name the name of the task (can be @c nullptr) + * @param data the user data you want to associate with the task (can be @c nullptr) + * @param amount amount of the task + * @return the new task + * @see SD_task_destroy() */ SD_task_t SD_task_create(const char *name, void *data, double amount) { @@ -92,10 +92,10 @@ SD_task_t SD_task_create_comm_e2e(const char *name, void *data, double amount) * * A sequential computation must be scheduled on 1 host, and the amount specified at creation to be run on hosts[0]. * - * \param name the name of the task (can be \c nullptr) - * \param data the user data you want to associate with the task (can be \c nullptr) - * \param flops_amount amount of compute work to be done by the task - * \return the new SD_TASK_COMP_SEQ typed task + * @param name the name of the task (can be @c nullptr) + * @param data the user data you want to associate with the task (can be @c nullptr) + * @param flops_amount amount of compute work to be done by the task + * @return the new SD_TASK_COMP_SEQ typed task */ SD_task_t SD_task_create_comp_seq(const char *name, void *data, double flops_amount) { @@ -114,12 +114,12 @@ SD_task_t SD_task_create_comp_seq(const char *name, void *data, double flops_amo * * A parallel computation can be scheduled on any number of host. * The underlying speedup model is Amdahl's law. - * To be auto-scheduled, \see SD_task_distribute_comp_amdahl has to be called first. - * \param name the name of the task (can be \c nullptr) - * \param data the user data you want to associate with the task (can be \c nullptr) - * \param flops_amount amount of compute work to be done by the task - * \param alpha purely serial fraction of the work to be done (in [0.;1.[) - * \return the new task + * To be auto-scheduled, @see SD_task_distribute_comp_amdahl has to be called first. + * @param name the name of the task (can be @c nullptr) + * @param data the user data you want to associate with the task (can be @c nullptr) + * @param flops_amount amount of compute work to be done by the task + * @param alpha purely serial fraction of the work to be done (in [0.;1.[) + * @return the new task */ SD_task_t SD_task_create_comp_par_amdahl(const char *name, void *data, double flops_amount, double alpha) { @@ -139,12 +139,12 @@ SD_task_t SD_task_create_comp_par_amdahl(const char *name, void *data, double fl * specify which resource should communicate. * * A data redistribution can be scheduled on any number of host. - * The assumed distribution is a 1D block distribution. Each host owns the same share of the \see amount. - * To be auto-scheduled, \see SD_task_distribute_comm_mxn_1d_block has to be called first. - * \param name the name of the task (can be \c nullptr) - * \param data the user data you want to associate with the task (can be \c nullptr) - * \param amount amount of data to redistribute by the task - * \return the new task + * The assumed distribution is a 1D block distribution. Each host owns the same share of the @see amount. + * To be auto-scheduled, @see SD_task_distribute_comm_mxn_1d_block has to be called first. + * @param name the name of the task (can be @c nullptr) + * @param data the user data you want to associate with the task (can be @c nullptr) + * @param amount amount of data to redistribute by the task + * @return the new task */ SD_task_t SD_task_create_comm_par_mxn_1d_block(const char *name, void *data, double amount) { @@ -155,12 +155,12 @@ SD_task_t SD_task_create_comm_par_mxn_1d_block(const char *name, void *data, dou } /** - * \brief Destroys a task. + * @brief Destroys a task. * * The user data (if any) should have been destroyed first. * - * \param task the task you want to destroy - * \see SD_task_create() + * @param task the task you want to destroy + * @see SD_task_create() */ void SD_task_destroy(SD_task_t task) { @@ -197,11 +197,11 @@ void SD_task_destroy(SD_task_t task) } /** - * \brief Returns the user data of a task + * @brief Returns the user data of a task * - * \param task a task - * \return the user data associated with this task (can be \c nullptr) - * \see SD_task_set_data() + * @param task a task + * @return the user data associated with this task (can be @c nullptr) + * @see SD_task_set_data() */ void *SD_task_get_data(SD_task_t task) { @@ -209,13 +209,13 @@ void *SD_task_get_data(SD_task_t task) } /** - * \brief Sets the user data of a task + * @brief Sets the user data of a task * - * The new data can be \c nullptr. The old data should have been freed first, if it was not \c nullptr. + * The new data can be @c nullptr. The old data should have been freed first, if it was not @c nullptr. * - * \param task a task - * \param data the new data you want to associate with this task - * \see SD_task_get_data() + * @param task a task + * @param data the new data you want to associate with this task + * @see SD_task_get_data() */ void SD_task_set_data(SD_task_t task, void *data) { @@ -223,17 +223,17 @@ void SD_task_set_data(SD_task_t task, void *data) } /** - * \brief Sets the rate of a task + * @brief Sets the rate of a task * * This will change the network bandwidth a task can use. This rate cannot be dynamically changed. Once the task has * started, this call is ineffective. This rate depends on both the nominal bandwidth on the route onto which the task - * is scheduled (\see SD_task_get_current_bandwidth) and the amount of data to transfer. + * is scheduled (@see SD_task_get_current_bandwidth) and the amount of data to transfer. * * To divide the nominal bandwidth by 2, the rate then has to be : * rate = bandwidth/(2*amount) * - * \param task a \see SD_TASK_COMM_E2E task (end-to-end communication) - * \param rate the new rate you want to associate with this task. + * @param task a @see SD_TASK_COMM_E2E task (end-to-end communication) + * @param rate the new rate you want to associate with this task. */ void SD_task_set_rate(SD_task_t task, double rate) { @@ -246,12 +246,12 @@ void SD_task_set_rate(SD_task_t task, double rate) } /** - * \brief Returns the state of a task + * @brief Returns the state of a task * - * \param task a task - * \return the current \ref e_SD_task_state_t "state" of this task: + * @param task a task + * @return the current @ref e_SD_task_state_t "state" of this task: * #SD_NOT_SCHEDULED, #SD_SCHEDULED, #SD_RUNNABLE, #SD_RUNNING, #SD_DONE or #SD_FAILED - * \see e_SD_task_state_t + * @see e_SD_task_state_t */ e_SD_task_state_t SD_task_get_state(SD_task_t task) { @@ -310,10 +310,10 @@ void SD_task_set_state(SD_task_t task, e_SD_task_state_t new_state) } /** - * \brief Returns the name of a task + * @brief Returns the name of a task * - * \param task a task - * \return the name of this task (can be \c nullptr) + * @param task a task + * @return the name of this task (can be @c nullptr) */ const char *SD_task_get_name(SD_task_t task) { @@ -329,8 +329,8 @@ void SD_task_set_name(SD_task_t task, const char *name) /** @brief Returns the dynar of the parents of a task * - * \param task a task - * \return a newly allocated dynar comprising the parents of this task + * @param task a task + * @return a newly allocated dynar comprising the parents of this task */ xbt_dynar_t SD_task_get_parents(SD_task_t task) @@ -347,8 +347,8 @@ xbt_dynar_t SD_task_get_parents(SD_task_t task) /** @brief Returns the dynar of the parents of a task * - * \param task a task - * \return a newly allocated dynar comprising the parents of this task + * @param task a task + * @return a newly allocated dynar comprising the parents of this task */ xbt_dynar_t SD_task_get_children(SD_task_t task) { @@ -363,10 +363,10 @@ xbt_dynar_t SD_task_get_children(SD_task_t task) } /** - * \brief Returns the number of workstations involved in a task + * @brief Returns the number of workstations involved in a task * * Only call this on already scheduled tasks! - * \param task a task + * @param task a task */ int SD_task_get_workstation_count(SD_task_t task) { @@ -374,10 +374,10 @@ int SD_task_get_workstation_count(SD_task_t task) } /** - * \brief Returns the list of workstations involved in a task + * @brief Returns the list of workstations involved in a task * * Only call this on already scheduled tasks! - * \param task a task + * @param task a task */ sg_host_t *SD_task_get_workstation_list(SD_task_t task) { @@ -385,11 +385,11 @@ sg_host_t *SD_task_get_workstation_list(SD_task_t task) } /** - * \brief Returns the total amount of work contained in a task + * @brief Returns the total amount of work contained in a task * - * \param task a task - * \return the total amount of work (computation or data transfer) for this task - * \see SD_task_get_remaining_amount() + * @param task a task + * @return the total amount of work (computation or data transfer) for this task + * @see SD_task_get_remaining_amount() */ double SD_task_get_amount(SD_task_t task) { @@ -401,8 +401,8 @@ double SD_task_get_amount(SD_task_t task) * bytes_amount arrays respectively. Nothing more than modifying task->amount is done for parallel typed tasks * (COMP_PAR_AMDAHL and COMM_PAR_MXN_1D_BLOCK) as the distribution of the amount of work is done at scheduling time. * - * \param task a task - * \param amount the new amount of work to execute + * @param task a task + * @param amount the new amount of work to execute */ void SD_task_set_amount(SD_task_t task, double amount) { @@ -414,10 +414,10 @@ void SD_task_set_amount(SD_task_t task, double amount) } /** - * \brief Returns the alpha parameter of a SD_TASK_COMP_PAR_AMDAHL task + * @brief Returns the alpha parameter of a SD_TASK_COMP_PAR_AMDAHL task * - * \param task a parallel task assuming Amdahl's law as speedup model - * \return the alpha parameter (serial part of a task in percent) for this task + * @param task a parallel task assuming Amdahl's law as speedup model + * @return the alpha parameter (serial part of a task in percent) for this task */ double SD_task_get_alpha(SD_task_t task) { @@ -426,11 +426,11 @@ double SD_task_get_alpha(SD_task_t task) } /** - * \brief Returns the remaining amount work to do till the completion of a task + * @brief Returns the remaining amount work to do till the completion of a task * - * \param task a task - * \return the remaining amount of work (computation or data transfer) of this task - * \see SD_task_get_amount() + * @param task a task + * @return the remaining amount of work (computation or data transfer) of this task + * @see SD_task_get_amount() */ double SD_task_get_remaining_amount(SD_task_t task) { @@ -522,14 +522,14 @@ void SD_task_dotty(SD_task_t task, void *out) } /** - * \brief Adds a dependency between two tasks + * @brief Adds a dependency between two tasks * - * \a dst will depend on \a src, ie \a dst will not start before \a src is finished. - * Their \ref e_SD_task_state_t "state" must be #SD_NOT_SCHEDULED, #SD_SCHEDULED or #SD_RUNNABLE. + * @a dst will depend on @a src, ie @a dst will not start before @a src is finished. + * Their @ref e_SD_task_state_t "state" must be #SD_NOT_SCHEDULED, #SD_SCHEDULED or #SD_RUNNABLE. * - * \param src the task which must be executed first - * \param dst the task you want to make depend on \a src - * \see SD_task_dependency_remove() + * @param src the task which must be executed first + * @param dst the task you want to make depend on @a src + * @see SD_task_dependency_remove() */ void SD_task_dependency_add(SD_task_t src, SD_task_t dst) { @@ -572,10 +572,10 @@ void SD_task_dependency_add(SD_task_t src, SD_task_t dst) } /** - * \brief Indicates whether there is a dependency between two tasks. + * @brief Indicates whether there is a dependency between two tasks. * - * \param src a task - * \param dst a task depending on \a src + * @param src a task + * @param dst a task depending on @a src * * If src is nullptr, checks whether dst has any pre-dependency. * If dst is nullptr, checks whether src has any post-dependency. @@ -597,11 +597,11 @@ int SD_task_dependency_exists(SD_task_t src, SD_task_t dst) } /** - * \brief Remove a dependency between two tasks + * @brief Remove a dependency between two tasks * - * \param src a task - * \param dst a task depending on \a src - * \see SD_task_dependency_add() + * @param src a task + * @param dst a task depending on @a src + * @see SD_task_dependency_add() */ void SD_task_dependency_remove(SD_task_t src, SD_task_t dst) { @@ -631,14 +631,14 @@ void SD_task_dependency_remove(SD_task_t src, SD_task_t dst) } /** - * \brief Adds a watch point to a task + * @brief Adds a watch point to a task * - * SD_simulate() will stop as soon as the \ref e_SD_task_state_t "state" of this task becomes the one given in argument. + * SD_simulate() will stop as soon as the @ref e_SD_task_state_t "state" of this task becomes the one given in argument. * The watch point is then automatically removed. * - * \param task a task - * \param state the \ref e_SD_task_state_t "state" you want to watch (cannot be #SD_NOT_SCHEDULED) - * \see SD_task_unwatch() + * @param task a task + * @param state the @ref e_SD_task_state_t "state" you want to watch (cannot be #SD_NOT_SCHEDULED) + * @see SD_task_unwatch() */ void SD_task_watch(SD_task_t task, e_SD_task_state_t state) { @@ -649,11 +649,11 @@ void SD_task_watch(SD_task_t task, e_SD_task_state_t state) } /** - * \brief Removes a watch point from a task + * @brief Removes a watch point from a task * - * \param task a task - * \param state the \ref e_SD_task_state_t "state" you no longer want to watch - * \see SD_task_watch() + * @param task a task + * @param state the @ref e_SD_task_state_t "state" you no longer want to watch + * @see SD_task_watch() */ void SD_task_unwatch(SD_task_t task, e_SD_task_state_t state) { @@ -662,16 +662,16 @@ void SD_task_unwatch(SD_task_t task, e_SD_task_state_t state) } /** - * \brief Returns an approximative estimation of the execution time of a task. + * @brief Returns an approximative estimation of the execution time of a task. * * The estimation is very approximative because the value returned is the time the task would take if it was executed * now and if it was the only task. * - * \param host_count number of hosts on which the task would be executed - * \param host_list the hosts on which the task would be executed - * \param flops_amount computation amount for each host(i.e., an array of host_count doubles) - * \param bytes_amount communication amount between each pair of hosts (i.e., a matrix of host_count*host_count doubles) - * \see SD_schedule() + * @param host_count number of hosts on which the task would be executed + * @param host_list the hosts on which the task would be executed + * @param flops_amount computation amount for each host(i.e., an array of host_count doubles) + * @param bytes_amount communication amount between each pair of hosts (i.e., a matrix of host_count*host_count doubles) + * @see SD_schedule() */ double SD_task_get_execution_time(SD_task_t /*task*/, int host_count, const sg_host_t* host_list, const double* flops_amount, const double* bytes_amount) @@ -709,18 +709,18 @@ static inline void SD_task_do_schedule(SD_task_t task) } /** - * \brief Schedules a task + * @brief Schedules a task * * The task state must be #SD_NOT_SCHEDULED. - * Once scheduled, a task is executed as soon as possible in \see SD_simulate, i.e. when its dependencies are satisfied. + * Once scheduled, a task is executed as soon as possible in @see SD_simulate, i.e. when its dependencies are satisfied. * - * \param task the task you want to schedule - * \param host_count number of hosts on which the task will be executed - * \param host_list the hosts on which the task will be executed - * \param flops_amount computation amount for each hosts (i.e., an array of host_count doubles) - * \param bytes_amount communication amount between each pair of hosts (i.e., a matrix of host_count*host_count doubles) - * \param rate task execution speed rate - * \see SD_task_unschedule() + * @param task the task you want to schedule + * @param host_count number of hosts on which the task will be executed + * @param host_list the hosts on which the task will be executed + * @param flops_amount computation amount for each hosts (i.e., an array of host_count doubles) + * @param bytes_amount communication amount between each pair of hosts (i.e., a matrix of host_count*host_count doubles) + * @param rate task execution speed rate + * @see SD_task_unschedule() */ void SD_task_schedule(SD_task_t task, int host_count, const sg_host_t * host_list, const double *flops_amount, const double *bytes_amount, double rate) @@ -753,14 +753,14 @@ void SD_task_schedule(SD_task_t task, int host_count, const sg_host_t * host_lis } /** - * \brief Unschedules a task + * @brief Unschedules a task * * The task state must be #SD_SCHEDULED, #SD_RUNNABLE, #SD_RUNNING or #SD_FAILED. * If you call this function, the task state becomes #SD_NOT_SCHEDULED. * Call SD_task_schedule() to schedule it again. * - * \param task the task you want to unschedule - * \see SD_task_schedule() + * @param task the task you want to unschedule + * @see SD_task_schedule() */ void SD_task_unschedule(SD_task_t task) { @@ -819,12 +819,12 @@ void SD_task_run(SD_task_t task) } /** - * \brief Returns the start time of a task + * @brief Returns the start time of a task * * The task state must be SD_RUNNING, SD_DONE or SD_FAILED. * - * \param task: a task - * \return the start time of this task + * @param task: a task + * @return the start time of this task */ double SD_task_get_start_time(SD_task_t task) { @@ -835,14 +835,14 @@ double SD_task_get_start_time(SD_task_t task) } /** - * \brief Returns the finish time of a task + * @brief Returns the finish time of a task * * The task state must be SD_RUNNING, SD_DONE or SD_FAILED. * If the state is not completed yet, the returned value is an estimation of the task finish time. This value can * vary until the task is completed. * - * \param task: a task - * \return the start time of this task + * @param task: a task + * @return the start time of this task */ double SD_task_get_finish_time(SD_task_t task) { diff --git a/src/simix/ActorImpl.cpp b/src/simix/ActorImpl.cpp index dfb2f05ab3..5d337985da 100644 --- a/src/simix/ActorImpl.cpp +++ b/src/simix/ActorImpl.cpp @@ -30,11 +30,11 @@ XBT_LOG_NEW_DEFAULT_SUBCATEGORY(simix_process, simix, "Logging specific to SIMIX unsigned long simix_process_maxpid = 0; /** - * \brief Returns the current agent. + * @brief Returns the current agent. * * This functions returns the currently running SIMIX process. * - * \return The SIMIX process + * @return The SIMIX process */ smx_actor_t SIMIX_process_self() { @@ -44,8 +44,8 @@ smx_actor_t SIMIX_process_self() } /** - * \brief Returns whether a process has pending asynchronous communications. - * \return true if there are asynchronous communications in this process + * @brief Returns whether a process has pending asynchronous communications. + * @return true if there are asynchronous communications in this process */ int SIMIX_process_has_pending_comms(smx_actor_t process) { @@ -53,7 +53,7 @@ int SIMIX_process_has_pending_comms(smx_actor_t process) { } /** - * \brief Moves a process to the list of processes to destroy. + * @brief Moves a process to the list of processes to destroy. */ void SIMIX_process_cleanup(smx_actor_t process) { @@ -272,13 +272,13 @@ void SIMIX_maestro_create(void (*code)(void*), void* data) } /** - * \brief Internal function to create a process. + * @brief Internal function to create a process. * * This function actually creates the process. * It may be called when a SIMCALL_PROCESS_CREATE simcall occurs, * or directly for SIMIX internal purposes. The sure thing is that it's called from maestro context. * - * \return the process created + * @return the process created */ smx_actor_t SIMIX_process_create(std::string name, simgrid::simix::ActorCode code, void* data, simgrid::s4u::Host* host, std::unordered_map* properties, smx_actor_t parent_process) @@ -406,7 +406,7 @@ void SIMIX_process_detach() } /** - * \brief Executes the processes from simix_global->process_to_run. + * @brief Executes the processes from simix_global->process_to_run. * * The processes of simix_global->process_to_run are run (in parallel if * possible). On exit, simix_global->process_to_run is empty, and @@ -423,13 +423,13 @@ void SIMIX_process_runall() } /** - * \brief Internal function to kill a SIMIX process. + * @brief Internal function to kill a SIMIX process. * * This function may be called when a SIMCALL_PROCESS_KILL simcall occurs, * or directly for SIMIX internal purposes. * - * \param process poor victim - * \param issuer the process which has sent the PROCESS_KILL. Important to not schedule twice the same process. + * @param process poor victim + * @param issuer the process which has sent the PROCESS_KILL. Important to not schedule twice the same process. */ void SIMIX_process_kill(smx_actor_t process, smx_actor_t issuer) { @@ -555,8 +555,8 @@ void SIMIX_process_throw(smx_actor_t process, xbt_errcat_t cat, int value, const } /** - * \brief Kills all running processes. - * \param issuer this one will not be killed + * @brief Kills all running processes. + * @param issuer this one will not be killed */ void SIMIX_process_killall(smx_actor_t issuer) { @@ -677,11 +677,11 @@ void SIMIX_process_sleep_destroy(smx_activity_t synchro) } /** - * \brief Calling this function makes the process to yield. + * @brief Calling this function makes the process to yield. * * Only the current process can call this function, giving back the control to maestro. * - * \param self the current process + * @param self the current process */ void SIMIX_process_yield(smx_actor_t self) { @@ -762,20 +762,20 @@ void SIMIX_process_on_exit(smx_actor_t process, std::function /** @brief Restart a process, starting it again from the beginning. */ /** - * \ingroup simix_process_management - * \brief Creates and runs a new SIMIX process. + * @ingroup simix_process_management + * @brief Creates and runs a new SIMIX process. * * The structure and the corresponding thread are created and put in the list of ready processes. * - * \param name a name for the process. It is for user-level information and can be nullptr. - * \param code the main function of the process - * \param data a pointer to any data one may want to attach to the new object. It is for user-level information and can + * @param name a name for the process. It is for user-level information and can be nullptr. + * @param code the main function of the process + * @param data a pointer to any data one may want to attach to the new object. It is for user-level information and can * be nullptr. * It can be retrieved with the method ActorImpl::getUserData(). - * \param host where the new agent is executed. - * \param argc first argument passed to \a code - * \param argv second argument passed to \a code - * \param properties the properties of the process + * @param host where the new agent is executed. + * @param argc first argument passed to @a code + * @param argv second argument passed to @a code + * @param properties the properties of the process */ smx_actor_t simcall_process_create(std::string name, xbt_main_func_t code, void* data, sg_host_t host, int argc, char** argv, std::unordered_map* properties) diff --git a/src/simix/libsmx.cpp b/src/simix/libsmx.cpp index 2d52a42ed0..9c1a73d2a6 100644 --- a/src/simix/libsmx.cpp +++ b/src/simix/libsmx.cpp @@ -25,18 +25,18 @@ XBT_LOG_EXTERNAL_DEFAULT_CATEGORY(simix); #include "popping_bodies.cpp" /** - * \ingroup simix_process_management - * \brief Creates a synchro that executes some computation of an host. + * @ingroup simix_process_management + * @brief Creates a synchro that executes some computation of an host. * * This function creates a SURF action and allocates the data necessary * to create the SIMIX synchro. It can raise a host_error exception if the host crashed. * - * \param name Name of the execution synchro to create - * \param flops_amount amount Computation amount (in flops) - * \param priority computation priority - * \param bound - * \param host host where the synchro will be executed - * \return A new SIMIX execution synchronization + * @param name Name of the execution synchro to create + * @param flops_amount amount Computation amount (in flops) + * @param priority computation priority + * @param bound + * @param host host where the synchro will be executed + * @return A new SIMIX execution synchronization */ smx_activity_t simcall_execution_start(std::string name, double flops_amount, double priority, double bound, simgrid::s4u::Host* host) @@ -51,19 +51,19 @@ smx_activity_t simcall_execution_start(std::string name, double flops_amount, do } /** - * \ingroup simix_process_management - * \brief Creates a synchro that may involve parallel computation on + * @ingroup simix_process_management + * @brief Creates a synchro that may involve parallel computation on * several hosts and communication between them. * - * \param name Name of the execution synchro to create - * \param host_nb Number of hosts where the synchro will be executed - * \param host_list Array (of size host_nb) of hosts where the synchro will be executed - * \param flops_amount Array (of size host_nb) of computation amount of hosts (in bytes) - * \param bytes_amount Array (of size host_nb * host_nb) representing the communication + * @param name Name of the execution synchro to create + * @param host_nb Number of hosts where the synchro will be executed + * @param host_list Array (of size host_nb) of hosts where the synchro will be executed + * @param flops_amount Array (of size host_nb) of computation amount of hosts (in bytes) + * @param bytes_amount Array (of size host_nb * host_nb) representing the communication * amount between each pair of hosts - * \param rate the SURF action rate - * \param timeout timeout - * \return A new SIMIX execution synchronization + * @param rate the SURF action rate + * @param timeout timeout + * @return A new SIMIX execution synchronization */ smx_activity_t simcall_execution_parallel_start(std::string name, int host_nb, sg_host_t* host_list, double* flops_amount, double* bytes_amount, double rate, double timeout) @@ -87,11 +87,11 @@ smx_activity_t simcall_execution_parallel_start(std::string name, int host_nb, s } /** - * \ingroup simix_process_management - * \brief Cancels an execution synchro. + * @ingroup simix_process_management + * @brief Cancels an execution synchro. * * This functions stops the execution. It calls a surf function. - * \param execution The execution synchro to cancel + * @param execution The execution synchro to cancel */ void simcall_execution_cancel(smx_activity_t execution) { @@ -103,12 +103,12 @@ void simcall_execution_cancel(smx_activity_t execution) } /** - * \ingroup simix_process_management - * \brief Changes the priority of an execution synchro. + * @ingroup simix_process_management + * @brief Changes the priority of an execution synchro. * * This functions changes the priority only. It calls a surf function. - * \param execution The execution synchro - * \param priority The new priority + * @param execution The execution synchro + * @param priority The new priority */ void simcall_execution_set_priority(smx_activity_t execution, double priority) { @@ -123,12 +123,12 @@ void simcall_execution_set_priority(smx_activity_t execution, double priority) } /** - * \ingroup simix_process_management - * \brief Changes the capping (the maximum CPU utilization) of an execution synchro. + * @ingroup simix_process_management + * @brief Changes the capping (the maximum CPU utilization) of an execution synchro. * * This functions changes the capping only. It calls a surf function. - * \param execution The execution synchro - * \param bound The new bound + * @param execution The execution synchro + * @param bound The new bound */ void simcall_execution_set_bound(smx_activity_t execution, double bound) { @@ -140,10 +140,10 @@ void simcall_execution_set_bound(smx_activity_t execution, double bound) } /** - * \ingroup simix_host_management - * \brief Waits for the completion of an execution synchro and destroy it. + * @ingroup simix_host_management + * @brief Waits for the completion of an execution synchro and destroy it. * - * \param execution The execution synchro + * @param execution The execution synchro */ e_smx_state_t simcall_execution_wait(smx_activity_t execution) { @@ -161,13 +161,13 @@ void simcall_process_join(smx_actor_t process, double timeout) } /** - * \ingroup simix_process_management - * \brief Suspends a process. + * @ingroup simix_process_management + * @brief Suspends a process. * * This function suspends the process by suspending the synchro * it was waiting for completion. * - * \param process a SIMIX process + * @param process a SIMIX process */ void simcall_process_suspend(smx_actor_t process) { @@ -175,12 +175,12 @@ void simcall_process_suspend(smx_actor_t process) } /** - * \ingroup simix_process_management - * \brief Set the user data of a #smx_actor_t. + * @ingroup simix_process_management + * @brief Set the user data of a #smx_actor_t. * - * This functions sets the user data associated to \a process. - * \param process SIMIX process - * \param data User data + * This functions sets the user data associated to @a process. + * @param process SIMIX process + * @param data User data */ void simcall_process_set_data(smx_actor_t process, void *data) { @@ -188,8 +188,8 @@ void simcall_process_set_data(smx_actor_t process, void *data) } /** - * \ingroup simix_process_management - * \brief Set the kill time of a process. + * @ingroup simix_process_management + * @brief Set the kill time of a process. */ void simcall_process_set_kill_time(smx_actor_t process, double kill_time) { @@ -204,15 +204,15 @@ void simcall_process_set_kill_time(smx_actor_t process, double kill_time) } /** - * \ingroup simix_process_management - * \brief Creates a new sleep SIMIX synchro. + * @ingroup simix_process_management + * @brief Creates a new sleep SIMIX synchro. * * This function creates a SURF action and allocates the data necessary * to create the SIMIX synchro. It can raise a host_error exception if the * host crashed. The default SIMIX name of the synchro is "sleep". * - * \param duration Time duration of the sleep. - * \return A result telling whether the sleep was successful + * @param duration Time duration of the sleep. + * @return A result telling whether the sleep was successful */ e_smx_state_t simcall_process_sleep(double duration) { @@ -222,7 +222,7 @@ e_smx_state_t simcall_process_sleep(double duration) } /** - * \ingroup simix_comm_management + * @ingroup simix_comm_management */ void simcall_comm_send(smx_actor_t sender, smx_mailbox_t mbox, double task_size, double rate, void* src_buff, size_t src_buff_size, int (*match_fun)(void*, void*, simgrid::kernel::activity::CommImpl*), @@ -250,7 +250,7 @@ void simcall_comm_send(smx_actor_t sender, smx_mailbox_t mbox, double task_size, } /** - * \ingroup simix_comm_management + * @ingroup simix_comm_management */ smx_activity_t simcall_comm_isend(smx_actor_t sender, smx_mailbox_t mbox, double task_size, double rate, void* src_buff, size_t src_buff_size, @@ -270,7 +270,7 @@ smx_activity_t simcall_comm_isend(smx_actor_t sender, smx_mailbox_t mbox, double } /** - * \ingroup simix_comm_management + * @ingroup simix_comm_management */ void simcall_comm_recv(smx_actor_t receiver, smx_mailbox_t mbox, void* dst_buff, size_t* dst_buff_size, int (*match_fun)(void*, void*, simgrid::kernel::activity::CommImpl*), @@ -293,7 +293,7 @@ void simcall_comm_recv(smx_actor_t receiver, smx_mailbox_t mbox, void* dst_buff, } } /** - * \ingroup simix_comm_management + * @ingroup simix_comm_management */ smx_activity_t simcall_comm_irecv(smx_actor_t receiver, smx_mailbox_t mbox, void* dst_buff, size_t* dst_buff_size, int (*match_fun)(void*, void*, simgrid::kernel::activity::CommImpl*), @@ -306,7 +306,7 @@ smx_activity_t simcall_comm_irecv(smx_actor_t receiver, smx_mailbox_t mbox, void } /** - * \ingroup simix_comm_management + * @ingroup simix_comm_management */ smx_activity_t simcall_comm_iprobe(smx_mailbox_t mbox, int type, int (*match_fun)(void*, void*, simgrid::kernel::activity::CommImpl*), void* data) @@ -317,7 +317,7 @@ smx_activity_t simcall_comm_iprobe(smx_mailbox_t mbox, int type, } /** - * \ingroup simix_comm_management + * @ingroup simix_comm_management */ void simcall_comm_cancel(smx_activity_t synchro) { @@ -329,7 +329,7 @@ void simcall_comm_cancel(smx_activity_t synchro) } /** - * \ingroup simix_comm_management + * @ingroup simix_comm_management */ unsigned int simcall_comm_waitany(xbt_dynar_t comms, double timeout) { @@ -337,7 +337,7 @@ unsigned int simcall_comm_waitany(xbt_dynar_t comms, double timeout) } /** - * \ingroup simix_comm_management + * @ingroup simix_comm_management */ int simcall_comm_testany(smx_activity_t* comms, size_t count) { @@ -347,7 +347,7 @@ int simcall_comm_testany(smx_activity_t* comms, size_t count) } /** - * \ingroup simix_comm_management + * @ingroup simix_comm_management */ void simcall_comm_wait(smx_activity_t comm, double timeout) { @@ -356,11 +356,11 @@ void simcall_comm_wait(smx_activity_t comm, double timeout) } /** - * \brief Set the category of an synchro. + * @brief Set the category of an synchro. * * This functions changes the category only. It calls a surf function. - * \param synchro The execution synchro - * \param category The tracing category + * @param synchro The execution synchro + * @param category The tracing category */ void simcall_set_category(smx_activity_t synchro, const char *category) { @@ -371,7 +371,7 @@ void simcall_set_category(smx_activity_t synchro, const char *category) } /** - * \ingroup simix_comm_management + * @ingroup simix_comm_management * */ int simcall_comm_test(smx_activity_t comm) @@ -380,7 +380,7 @@ int simcall_comm_test(smx_activity_t comm) } /** - * \ingroup simix_synchro_management + * @ingroup simix_synchro_management * */ smx_mutex_t simcall_mutex_init() @@ -393,7 +393,7 @@ smx_mutex_t simcall_mutex_init() } /** - * \ingroup simix_synchro_management + * @ingroup simix_synchro_management * */ void simcall_mutex_lock(smx_mutex_t mutex) @@ -402,7 +402,7 @@ void simcall_mutex_lock(smx_mutex_t mutex) } /** - * \ingroup simix_synchro_management + * @ingroup simix_synchro_management * */ int simcall_mutex_trylock(smx_mutex_t mutex) @@ -411,7 +411,7 @@ int simcall_mutex_trylock(smx_mutex_t mutex) } /** - * \ingroup simix_synchro_management + * @ingroup simix_synchro_management * */ void simcall_mutex_unlock(smx_mutex_t mutex) @@ -420,7 +420,7 @@ void simcall_mutex_unlock(smx_mutex_t mutex) } /** - * \ingroup simix_synchro_management + * @ingroup simix_synchro_management * */ smx_cond_t simcall_cond_init() @@ -429,7 +429,7 @@ smx_cond_t simcall_cond_init() } /** - * \ingroup simix_synchro_management + * @ingroup simix_synchro_management * */ void simcall_cond_wait(smx_cond_t cond, smx_mutex_t mutex) @@ -438,7 +438,7 @@ void simcall_cond_wait(smx_cond_t cond, smx_mutex_t mutex) } /** - * \ingroup simix_synchro_management + * @ingroup simix_synchro_management * */ int simcall_cond_wait_timeout(smx_cond_t cond, smx_mutex_t mutex, double timeout) @@ -448,7 +448,7 @@ int simcall_cond_wait_timeout(smx_cond_t cond, smx_mutex_t mutex, double timeout } /** - * \ingroup simix_synchro_management + * @ingroup simix_synchro_management * */ void simcall_sem_acquire(smx_sem_t sem) @@ -457,7 +457,7 @@ void simcall_sem_acquire(smx_sem_t sem) } /** - * \ingroup simix_synchro_management + * @ingroup simix_synchro_management * */ int simcall_sem_acquire_timeout(smx_sem_t sem, double timeout) diff --git a/src/simix/popping_private.hpp b/src/simix/popping_private.hpp index 7e6675b566..d7742cd6d8 100644 --- a/src/simix/popping_private.hpp +++ b/src/simix/popping_private.hpp @@ -39,7 +39,7 @@ union u_smx_scalar { }; /** - * \brief Represents a simcall to the kernel. + * @brief Represents a simcall to the kernel. */ struct s_smx_simcall { e_smx_simcall_t call; diff --git a/src/simix/smx_context.cpp b/src/simix/smx_context.cpp index 55bb5e8970..bd4a7e3a1e 100644 --- a/src/simix/smx_context.cpp +++ b/src/simix/smx_context.cpp @@ -251,21 +251,21 @@ int SIMIX_context_is_parallel() { /** * @brief Returns the number of parallel threads used for the user contexts. - * \return the number of threads (1 means no parallelism) + * @return the number of threads (1 means no parallelism) */ int SIMIX_context_get_nthreads() { return smx_parallel_contexts; } /** - * \brief Sets the number of parallel threads to use + * @brief Sets the number of parallel threads to use * for the user contexts. * * This function should be called before initializing SIMIX. * A value of 1 means no parallelism (1 thread only). * If the value is greater than 1, the thread support must be enabled. * - * \param nb_threads the number of threads to use + * @param nb_threads the number of threads to use */ void SIMIX_context_set_nthreads(int nb_threads) { if (nb_threads<=0) { @@ -279,12 +279,12 @@ void SIMIX_context_set_nthreads(int nb_threads) { } /** - * \brief Returns the threshold above which user processes are run in parallel. + * @brief Returns the threshold above which user processes are run in parallel. * * If the number of threads is set to 1, there is no parallelism and this * threshold has no effect. * - * \return when the number of user processes ready to run is above + * @return when the number of user processes ready to run is above * this threshold, they are run in parallel */ int SIMIX_context_get_parallel_threshold() { @@ -292,12 +292,12 @@ int SIMIX_context_get_parallel_threshold() { } /** - * \brief Sets the threshold above which user processes are run in parallel. + * @brief Sets the threshold above which user processes are run in parallel. * * If the number of threads is set to 1, there is no parallelism and this * threshold has no effect. * - * \param threshold when the number of user processes ready to run is above + * @param threshold when the number of user processes ready to run is above * this threshold, they are run in parallel */ void SIMIX_context_set_parallel_threshold(int threshold) { @@ -305,26 +305,26 @@ void SIMIX_context_set_parallel_threshold(int threshold) { } /** - * \brief Returns the synchronization mode used when processes are run in + * @brief Returns the synchronization mode used when processes are run in * parallel. - * \return how threads are synchronized if processes are run in parallel + * @return how threads are synchronized if processes are run in parallel */ e_xbt_parmap_mode_t SIMIX_context_get_parallel_mode() { return smx_parallel_synchronization_mode; } /** - * \brief Sets the synchronization mode to use when processes are run in + * @brief Sets the synchronization mode to use when processes are run in * parallel. - * \param mode how to synchronize threads if processes are run in parallel + * @param mode how to synchronize threads if processes are run in parallel */ void SIMIX_context_set_parallel_mode(e_xbt_parmap_mode_t mode) { smx_parallel_synchronization_mode = mode; } /** - * \brief Returns the current context of this thread. - * \return the current context of this thread + * @brief Returns the current context of this thread. + * @return the current context of this thread */ smx_context_t SIMIX_context_get_current() { @@ -341,8 +341,8 @@ smx_context_t SIMIX_context_get_current() } /** - * \brief Sets the current context of this thread. - * \param context the context to set + * @brief Sets the current context of this thread. + * @param context the context to set */ void SIMIX_context_set_current(smx_context_t context) { diff --git a/src/simix/smx_deployment.cpp b/src/simix/smx_deployment.cpp index d94d87f206..aece2e987c 100644 --- a/src/simix/smx_deployment.cpp +++ b/src/simix/smx_deployment.cpp @@ -23,17 +23,17 @@ void SIMIX_init_application() } /** - * \brief An application deployer. + * @brief An application deployer. * - * Creates the process described in \a file. - * \param file a filename of a xml description of the application. This file + * Creates the process described in @a file. + * @param file a filename of a xml description of the application. This file * follows this DTD : * - * \include surfxml.dtd + * @include surfxml.dtd * * Here is a small example of such a platform * - * \include small_deployment.xml + * @include small_deployment.xml * */ void SIMIX_launch_application(std::string file) @@ -69,12 +69,12 @@ static simgrid::simix::ActorCodeFactory toActorCodeFactory(xbt_main_func_t code) } /** - * \brief Registers a #xbt_main_func_t code in a global table. + * @brief Registers a #xbt_main_func_t code in a global table. * * Registers a code function in a global table. * This table is then used by #SIMIX_launch_application. - * \param name the reference name of the function. - * \param code the function + * @param name the reference name of the function. + * @param code the function */ void SIMIX_function_register(std::string name, xbt_main_func_t code) { @@ -89,10 +89,11 @@ void SIMIX_function_register(const char* name, xbt_main_func_t code) // deprecat } /** - * \brief Registers a #xbt_main_func_t code as default value. + * @brief Registers a #xbt_main_func_t code as default value. * - * Registers a code function as being the default value. This function will get used by SIMIX_launch_application() when there is no registered function of the requested name in. - * \param code the function + * Registers a code function as being the default value. This function will get used by SIMIX_launch_application() when + * there is no registered function of the requested name in. + * @param code the function */ void SIMIX_function_register_default(xbt_main_func_t code) { @@ -101,12 +102,12 @@ void SIMIX_function_register_default(xbt_main_func_t code) } /** - * \brief Gets a #smx_actor_t code from the global table. + * @brief Gets a #smx_actor_t code from the global table. * * Gets a code function from the global table. Returns nullptr if there are no function registered with the name. * This table is then used by #SIMIX_launch_application. - * \param name the reference name of the function. - * \return The #smx_actor_t or nullptr. + * @param name the reference name of the function. + * @return The #smx_actor_t or nullptr. */ simgrid::simix::ActorCodeFactory& SIMIX_get_actor_code_factory(std::string name) { @@ -120,9 +121,7 @@ simgrid::simix::ActorCodeFactory& SIMIX_get_actor_code_factory(std::string name) return i->second; } -/** - * \brief Bypass the parser, get arguments, and set function to each process - */ +/** @brief Bypass the parser, get arguments, and set function to each process */ void SIMIX_process_set_function(const char* process_host, const char* process_function, xbt_dynar_t arguments, double process_start_time, double process_kill_time) diff --git a/src/simix/smx_environment.cpp b/src/simix/smx_environment.cpp index 94b2e6ef0c..dde40f2535 100644 --- a/src/simix/smx_environment.cpp +++ b/src/simix/smx_environment.cpp @@ -15,18 +15,18 @@ XBT_LOG_NEW_DEFAULT_SUBCATEGORY(simix_environment, simix, "Logging specific to S /********************************* SIMIX **************************************/ /** - * \brief A platform constructor. + * @brief A platform constructor. * * Creates a new platform, including hosts, links and the * routing_table. - * \param file a filename of a xml description of a platform. This file + * @param file a filename of a xml description of a platform. This file * follows this DTD : * - * \include surfxml.dtd + * @include surfxml.dtd * * Here is a small example of such a platform * - * \include small_platform.xml + * @include small_platform.xml * */ void SIMIX_create_environment(std::string file) diff --git a/src/simix/smx_global.cpp b/src/simix/smx_global.cpp index 0d7299f706..e1fbbdfff0 100644 --- a/src/simix/smx_global.cpp +++ b/src/simix/smx_global.cpp @@ -168,8 +168,8 @@ void SIMIX_set_maestro(void (*code)(void*), void* data) } /** - * \ingroup SIMIX_API - * \brief Initialize SIMIX internal data. + * @ingroup SIMIX_API + * @brief Initialize SIMIX internal data. */ void SIMIX_global_init(int *argc, char **argv) { @@ -219,8 +219,8 @@ void SIMIX_global_init(int *argc, char **argv) int smx_cleaned = 0; /** - * \ingroup SIMIX_API - * \brief Clean the SIMIX simulation + * @ingroup SIMIX_API + * @brief Clean the SIMIX simulation * * This functions remove the memory used by SIMIX */ @@ -288,12 +288,11 @@ void SIMIX_clean() simix_global = nullptr; } - /** - * \ingroup SIMIX_API - * \brief A clock (in second). + * @ingroup SIMIX_API + * @brief A clock (in second). * - * \return Return the clock. + * @return Return the clock. */ double SIMIX_get_clock() { @@ -373,8 +372,8 @@ static bool SIMIX_execute_tasks() } /** - * \ingroup SIMIX_API - * \brief Run the main simulation loop. + * @ingroup SIMIX_API + * @brief Run the main simulation loop. */ void SIMIX_run() { @@ -538,12 +537,12 @@ void SIMIX_run() } /** - * \brief Set the date to execute a function + * @brief Set the date to execute a function * * Set the date to execute the function on the surf. - * \param date Date to execute function - * \param callback Function to be executed - * \param arg Parameters of the function + * @param date Date to execute function + * @param callback Function to be executed + * @param arg Parameters of the function * */ smx_timer_t SIMIX_timer_set(double date, void (*callback)(void*), void *arg) @@ -572,12 +571,12 @@ double SIMIX_timer_get_date(smx_timer_t timer) { } /** - * \brief Registers a function to create a process. + * @brief Registers a function to create a process. * * This function registers a function to be called * when a new process is created. The function has * to call SIMIX_process_create(). - * \param function create process function + * @param function create process function */ void SIMIX_function_register_process_create(smx_creation_func_t function) { @@ -585,12 +584,12 @@ void SIMIX_function_register_process_create(smx_creation_func_t function) } /** - * \brief Registers a function to kill a process. + * @brief Registers a function to kill a process. * * This function registers a function to be called when a process is killed. The function has to call the * SIMIX_process_kill(). * - * \param function Kill process function + * @param function Kill process function */ void SIMIX_function_register_process_kill(void_pfn_smxprocess_t function) { @@ -598,11 +597,11 @@ void SIMIX_function_register_process_kill(void_pfn_smxprocess_t function) } /** - * \brief Registers a function to cleanup a process. + * @brief Registers a function to cleanup a process. * * This function registers a user function to be called when a process ends properly. * - * \param function cleanup process function + * @param function cleanup process function */ void SIMIX_function_register_process_cleanup(void_pfn_smxprocess_t function) { diff --git a/src/simix/smx_host.cpp b/src/simix/smx_host.cpp index 6b1ce5d107..9f317fbaf5 100644 --- a/src/simix/smx_host.cpp +++ b/src/simix/smx_host.cpp @@ -25,7 +25,7 @@ const char* sg_host_self_get_name() } /** - * \brief Add a process to the list of the processes that the host will restart when it comes back + * @brief Add a process to the list of the processes that the host will restart when it comes back * This function add a process to the list of the processes that will be restarted when the host comes * back. It is expected that this function is called when the host is down. * The processes will only be restarted once, meaning that you will have to register the process diff --git a/src/simix/smx_network.cpp b/src/simix/smx_network.cpp index da781c865e..a295cae8b0 100644 --- a/src/simix/smx_network.cpp +++ b/src/simix/smx_network.cpp @@ -21,14 +21,14 @@ static void SIMIX_comm_copy_data(smx_activity_t comm); static void SIMIX_comm_start(simgrid::kernel::activity::CommImplPtr synchro); /** - * \brief Checks if there is a communication activity queued in a deque matching our needs - * \param deque where to search into - * \param type The type of communication we are looking for (comm_send, comm_recv) - * \param match_fun the function to apply - * \param this_user_data additional parameter to the match_fun - * \param my_synchro what to compare against - * \param remove_matching whether or not to clean the found object from the queue - * \return The communication activity if found, nullptr otherwise + * @brief Checks if there is a communication activity queued in a deque matching our needs + * @param deque where to search into + * @param type The type of communication we are looking for (comm_send, comm_recv) + * @param match_fun the function to apply + * @param this_user_data additional parameter to the match_fun + * @param my_synchro what to compare against + * @param remove_matching whether or not to clean the found object from the queue + * @return The communication activity if found, nullptr otherwise */ static simgrid::kernel::activity::CommImplPtr _find_matching_comm(boost::circular_buffer_space_optimized* deque, e_smx_comm_type_t type, @@ -438,8 +438,8 @@ void SIMIX_waitany_remove_simcall_from_actions(smx_simcall_t simcall) } /** - * \brief Starts the simulation of a communication synchro. - * \param comm the communication that will be started + * @brief Starts the simulation of a communication synchro. + * @param comm the communication that will be started */ static inline void SIMIX_comm_start(simgrid::kernel::activity::CommImplPtr comm) { @@ -482,8 +482,8 @@ static inline void SIMIX_comm_start(simgrid::kernel::activity::CommImplPtr comm) } /** - * \brief Answers the SIMIX simcalls associated to a communication synchro. - * \param synchro a finished communication synchro + * @brief Answers the SIMIX simcalls associated to a communication synchro. + * @param synchro a finished communication synchro */ void SIMIX_comm_finish(smx_activity_t synchro) { diff --git a/src/simix/smx_synchro.cpp b/src/simix/smx_synchro.cpp index d7deecfa12..28dafe31da 100644 --- a/src/simix/smx_synchro.cpp +++ b/src/simix/smx_synchro.cpp @@ -157,7 +157,7 @@ static void _SIMIX_sem_wait(smx_sem_t sem, double timeout, smx_actor_t issuer, } /** - * \brief Handles a sem acquire simcall without timeout. + * @brief Handles a sem acquire simcall without timeout. */ void simcall_HANDLER_sem_acquire(smx_simcall_t simcall, smx_sem_t sem) { @@ -167,7 +167,7 @@ void simcall_HANDLER_sem_acquire(smx_simcall_t simcall, smx_sem_t sem) } /** - * \brief Handles a sem acquire simcall with timeout. + * @brief Handles a sem acquire simcall with timeout. */ void simcall_HANDLER_sem_acquire_timeout(smx_simcall_t simcall, smx_sem_t sem, double timeout) { diff --git a/src/smpi/include/smpi_coll.hpp b/src/smpi/include/smpi_coll.hpp index a88a16b863..7f468aaa5b 100644 --- a/src/smpi/include/smpi_coll.hpp +++ b/src/smpi/include/smpi_coll.hpp @@ -11,7 +11,7 @@ #include "private.hpp" #include "xbt/base.h" -/** \brief MPI collective description */ +/** @brief MPI collective description */ #define COLL_DEFS(cat, ret, args, args2) \ static void set_##cat(std::string name); \ diff --git a/src/smpi/internals/smpi_actor.cpp b/src/smpi/internals/smpi_actor.cpp index b7bf6e6036..376f966b1b 100644 --- a/src/smpi/internals/smpi_actor.cpp +++ b/src/smpi/internals/smpi_actor.cpp @@ -133,9 +133,9 @@ ActorPtr ActorExt::get_actor() } /** - * \brief Returns a structure that stores the location (filename + linenumber) of the last calls to MPI_* functions. + * @brief Returns a structure that stores the location (filename + linenumber) of the last calls to MPI_* functions. * - * \see smpi_trace_set_call_location + * @see smpi_trace_set_call_location */ smpi_trace_call_location_t* ActorExt::call_location() { diff --git a/src/smpi/internals/smpi_deployment.cpp b/src/smpi/internals/smpi_deployment.cpp index 203ed2aea6..f7eea95887 100644 --- a/src/smpi/internals/smpi_deployment.cpp +++ b/src/smpi/internals/smpi_deployment.cpp @@ -40,12 +40,12 @@ using simgrid::smpi::app::Instance; static std::map smpi_instances; extern int process_count; // How many processes have been allocated over all instances? -/** \ingroup smpi_simulation - * \brief Registers a running instance of a MPI program. +/** @ingroup smpi_simulation + * @brief Registers a running instance of a MPI program. * - * \param name the reference name of the function. - * \param code the main mpi function (must have a int ..(int argc, char *argv[])) prototype - * \param num_processes the size of the instance we want to deploy + * @param name the reference name of the function. + * @param code the main mpi function (must have a int ..(int argc, char *argv[])) prototype + * @param num_processes the size of the instance we want to deploy */ void SMPI_app_instance_register(const char *name, xbt_main_func_t code, int num_processes) { diff --git a/src/smpi/internals/smpi_dvfs.cpp b/src/smpi/internals/smpi_dvfs.cpp index 9d2c98d076..c490f82d9a 100644 --- a/src/smpi/internals/smpi_dvfs.cpp +++ b/src/smpi/internals/smpi_dvfs.cpp @@ -17,10 +17,10 @@ XBT_LOG_NEW_DEFAULT_SUBCATEGORY(smpi_dvfs, smpi, "Logging specific to SMPI (experimental DVFS support)"); /** - * \brief Return the speed of the processor (in flop/s) at a given pstate + * @brief Return the speed of the processor (in flop/s) at a given pstate * - * \param pstate_index pstate to test - * \return Returns the processor speed associated with pstate_index + * @param pstate_index pstate to test + * @return Returns the processor speed associated with pstate_index */ double smpi_get_host_power_peak_at(int pstate_index) { @@ -28,9 +28,9 @@ double smpi_get_host_power_peak_at(int pstate_index) } /** - * \brief Return the current speed of the processor (in flop/s) + * @brief Return the current speed of the processor (in flop/s) * - * \return Returns the current processor speed + * @return Returns the current processor speed */ double smpi_get_host_current_power_peak() { @@ -38,7 +38,7 @@ double smpi_get_host_current_power_peak() } /** - * \brief Return the number of pstates defined for the current host + * @brief Return the number of pstates defined for the current host */ int smpi_get_host_nb_pstates() { @@ -46,9 +46,9 @@ int smpi_get_host_nb_pstates() } /** - * \brief Sets the pstate at which the processor should run + * @brief Sets the pstate at which the processor should run * - * \param pstate_index pstate to switch to + * @param pstate_index pstate to switch to */ void smpi_set_host_pstate(int pstate_index) { @@ -60,9 +60,9 @@ int smpi_get_host_pstate() { } /** - * \brief Return the total energy consumed by a host (in Joules) + * @brief Return the total energy consumed by a host (in Joules) * - * \return Returns the consumed energy + * @return Returns the consumed energy */ double smpi_get_host_consumed_energy() { return sg_host_get_consumed_energy(sg_host_self()); diff --git a/src/smpi/internals/smpi_static_variables.cpp b/src/smpi/internals/smpi_static_variables.cpp index 03e289ec19..6ec9ef646f 100644 --- a/src/smpi/internals/smpi_static_variables.cpp +++ b/src/smpi/internals/smpi_static_variables.cpp @@ -12,7 +12,7 @@ struct s_smpi_static_t { }; /** - * \brief Holds a reference to all static variables that were registered + * @brief Holds a reference to all static variables that were registered * via smpi_register_static(). This helps to free them when * SMPI shuts down. */ diff --git a/src/smpi/plugins/sampi_loadbalancer.cpp b/src/smpi/plugins/sampi_loadbalancer.cpp index 1a7850f4b9..c9b9a457e0 100644 --- a/src/smpi/plugins/sampi_loadbalancer.cpp +++ b/src/smpi/plugins/sampi_loadbalancer.cpp @@ -19,9 +19,9 @@ namespace plugin { } } -/** \ingroup plugin_loadbalancer - * \brief Initializes the load balancer plugin - * \details The load balancer plugin supports several AMPI load balancers that move ranks +/** @ingroup plugin_loadbalancer + * @brief Initializes the load balancer plugin + * @details The load balancer plugin supports several AMPI load balancers that move ranks * around, based on their host's load. */ void sg_load_balancer_plugin_init() diff --git a/src/surf/cpu_ti.cpp b/src/surf/cpu_ti.cpp index d1d7d749b7..99d32a6738 100644 --- a/src/surf/cpu_ti.cpp +++ b/src/surf/cpu_ti.cpp @@ -50,15 +50,15 @@ CpuTiTmgr::~CpuTiTmgr() } /** -* \brief Integrate trace -* -* Wrapper around surf_cpu_integrate_trace_simple() to get -* the cyclic effect. -* -* \param a Begin of interval -* \param b End of interval -* \return the integrate value. -1 if an error occurs. -*/ + * @brief Integrate trace + * + * Wrapper around surf_cpu_integrate_trace_simple() to get + * the cyclic effect. + * + * @param a Begin of interval + * @param b End of interval + * @return the integrate value. -1 if an error occurs. + */ double CpuTiTmgr::integrate(double a, double b) { if ((a < 0.0) || (a > b)) { @@ -94,19 +94,19 @@ double CpuTiTmgr::integrate(double a, double b) } /** - * \brief Auxiliary function to compute the integral between a and b. + * @brief Auxiliary function to compute the integral between a and b. * It simply computes the integrals at point a and b and returns the difference between them. - * \param a Initial point - * \param b Final point -*/ + * @param a Initial point + * @param b Final point + */ double CpuTiTrace::integrate_simple(double a, double b) { return integrate_simple_point(b) - integrate_simple_point(a); } /** - * \brief Auxiliary function to compute the integral at point a. - * \param a point + * @brief Auxiliary function to compute the integral at point a. + * @param a point */ double CpuTiTrace::integrate_simple_point(double a) { @@ -127,14 +127,14 @@ double CpuTiTrace::integrate_simple_point(double a) } /** -* \brief Computes the time needed to execute "amount" on cpu. -* -* Here, amount can span multiple trace periods -* -* \param a Initial time -* \param amount Amount to be executed -* \return End time -*/ + * @brief Computes the time needed to execute "amount" on cpu. + * + * Here, amount can span multiple trace periods + * + * @param a Initial time + * @param amount Amount to be executed + * @return End time + */ double CpuTiTmgr::solve(double a, double amount) { /* Fix very small negative numbers */ @@ -185,12 +185,12 @@ double CpuTiTmgr::solve(double a, double amount) } /** - * \brief Auxiliary function to solve integral. + * @brief Auxiliary function to solve integral. * It returns the date when the requested amount of flops is available - * \param a Initial point - * \param amount Amount of flops - * \return The date when amount is available. -*/ + * @param a Initial point + * @param amount Amount of flops + * @return The date when amount is available. + */ double CpuTiTrace::solve_simple(double a, double amount) { double integral_a = integrate_simple_point(a); @@ -203,12 +203,12 @@ double CpuTiTrace::solve_simple(double a, double amount) } /** -* \brief Auxiliary function to update the CPU speed scale. -* -* This function uses the trace structure to return the speed scale at the determined time a. -* \param a Time -* \return CPU speed scale -*/ + * @brief Auxiliary function to update the CPU speed scale. + * + * This function uses the trace structure to return the speed scale at the determined time a. + * @param a Time + * @return CPU speed scale + */ double CpuTiTmgr::get_power_scale(double a) { double reduced_a = a - floor(a / last_time_) * last_time_; @@ -218,11 +218,11 @@ double CpuTiTmgr::get_power_scale(double a) } /** - * \brief Creates a new integration trace from a tmgr_trace_t + * @brief Creates a new integration trace from a tmgr_trace_t * - * \param speed_trace CPU availability trace - * \param value Percentage of CPU speed available (useful to fixed tracing) - * \return Integration trace structure + * @param speed_trace CPU availability trace + * @param value Percentage of CPU speed available (useful to fixed tracing) + * @return Integration trace structure */ CpuTiTmgr::CpuTiTmgr(tmgr_trace_t speed_trace, double value) : speed_trace_(speed_trace) { @@ -258,14 +258,14 @@ CpuTiTmgr::CpuTiTmgr(tmgr_trace_t speed_trace, double value) : speed_trace_(spee } /** - * \brief Binary search in array. + * @brief Binary search in array. * It returns the first point of the interval in which "a" is. - * \param array Array - * \param a Value to search - * \param low Low bound to search in array - * \param high Upper bound to search in array - * \return Index of point -*/ + * @param array Array + * @param a Value to search + * @param low Low bound to search in array + * @param high Upper bound to search in array + * @return Index of point + */ int CpuTiTrace::binary_search(double* array, double a, int low, int high) { xbt_assert(low < high, "Wrong parameters: low (%d) should be smaller than high (%d)", low, high); diff --git a/src/surf/network_interface.cpp b/src/surf/network_interface.cpp index abf0801f3c..3c2dd98bfa 100644 --- a/src/surf/network_interface.cpp +++ b/src/surf/network_interface.cpp @@ -24,14 +24,14 @@ namespace simgrid { namespace kernel { namespace resource { -/** @brief Command-line option 'network/TCP-gamma' -- see \ref options_model_network_gamma */ +/** @brief Command-line option 'network/TCP-gamma' -- see @ref options_model_network_gamma */ simgrid::config::Flag NetworkModel::cfg_tcp_gamma( "network/TCP-gamma", {"network/TCP_gamma"}, "Size of the biggest TCP window (cat /proc/sys/net/ipv4/tcp_[rw]mem for recv/send window; " "Use the last given value, which is the max window size)", 4194304.0); -/** @brief Command-line option 'network/crosstraffic' -- see \ref options_model_network_crosstraffic */ +/** @brief Command-line option 'network/crosstraffic' -- see @ref options_model_network_crosstraffic */ simgrid::config::Flag NetworkModel::cfg_crosstraffic( "network/crosstraffic", "Activate the interferences between uploads and downloads for fluid max-min models (LV08, CM02)", "yes"); diff --git a/src/surf/network_interface.hpp b/src/surf/network_interface.hpp index 8267e775b0..915a925049 100644 --- a/src/surf/network_interface.hpp +++ b/src/surf/network_interface.hpp @@ -108,7 +108,7 @@ public: ************/ /** @ingroup SURF_network_interface * @brief SURF network link interface class - * @details A Link represents the link between two [hosts](\ref simgrid::surf::HostImpl) + * @details A Link represents the link between two [hosts](@ref simgrid::surf::HostImpl) */ class LinkImpl : public Resource, public simgrid::surf::PropertyHolder { protected: @@ -169,7 +169,7 @@ private: **********/ /** @ingroup SURF_network_interface * @brief SURF network action interface class - * @details A NetworkAction represents a communication between two [hosts](\ref simgrid::surf::HostImpl) + * @details A NetworkAction represents a communication between two [hosts](@ref simgrid::surf::HostImpl) */ class NetworkAction : public Action { public: @@ -202,8 +202,8 @@ public: } } } // namespace simgrid -/** \ingroup SURF_models - * \brief The network model +/** @ingroup SURF_models + * @brief The network model */ XBT_PUBLIC_DATA simgrid::kernel::resource::NetworkModel* surf_network_model; diff --git a/src/surf/sg_platf.cpp b/src/surf/sg_platf.cpp index f192754677..a3a9c52ac7 100644 --- a/src/surf/sg_platf.cpp +++ b/src/surf/sg_platf.cpp @@ -534,7 +534,7 @@ static void surf_config_models_setup() } /** - * \brief Add a Zone to the platform + * @brief Add a Zone to the platform * * Add a new autonomous system to the platform. Any elements (such as host, router or sub-Zone) added after this call * and before the corresponding call to sg_platf_new_Zone_seal() will be added to this Zone. @@ -620,7 +620,7 @@ simgrid::kernel::routing::NetZoneImpl* sg_platf_new_Zone_begin(simgrid::kernel:: } /** - * \brief Specify that the description of the current AS is finished + * @brief Specify that the description of the current AS is finished * * Once you've declared all the content of your AS, you have to seal * it with this call. Your AS is not usable until you call this function. diff --git a/src/surf/surf_interface.hpp b/src/surf/surf_interface.hpp index e1af3a481e..5e937a85f0 100644 --- a/src/surf/surf_interface.hpp +++ b/src/surf/surf_interface.hpp @@ -52,13 +52,13 @@ static inline int double_equals(double value1, double value2, double precision) return (fabs(value1 - value2) < precision); } -/** \ingroup SURF_simulation - * \brief List of hosts that have just restarted and whose autorestart process should be restarted. +/** @ingroup SURF_simulation + * @brief List of hosts that have just restarted and whose autorestart process should be restarted. */ XBT_PUBLIC_DATA std::vector host_that_restart; -/** \ingroup SURF_models - * \brief Initializes the CPU model with the model Cas01 +/** @ingroup SURF_models + * @brief Initializes the CPU model with the model Cas01 * * By default, this model uses the lazy optimization mechanism that relies on partial invalidation in LMM and a heap * for lazy action update. @@ -68,68 +68,68 @@ XBT_PUBLIC_DATA std::vector host_that_restart; */ XBT_PUBLIC void surf_cpu_model_init_Cas01(); -/** \ingroup SURF_models - * \brief Same as network model 'LagrangeVelho', only with different correction factors. +/** @ingroup SURF_models + * @brief Same as network model 'LagrangeVelho', only with different correction factors. * * This model is proposed by Pierre-Nicolas Clauss and Martin Quinson and Stéphane Génaud based on the model 'LV08' and * different correction factors depending on the communication size (< 1KiB, < 64KiB, >= 64KiB). * See comments in the code for more information. * - * \see surf_host_model_init_SMPI() + * @see surf_host_model_init_SMPI() */ XBT_PUBLIC void surf_network_model_init_SMPI(); -/** \ingroup SURF_models - * \brief Same as network model 'LagrangeVelho', only with different correction factors. +/** @ingroup SURF_models + * @brief Same as network model 'LagrangeVelho', only with different correction factors. * * This model impelments a variant of the contention model on Infinband networks based on * the works of Jérôme Vienne : http://mescal.imag.fr/membres/jean-marc.vincent/index.html/PhD/Vienne.pdf * - * \see surf_host_model_init_IB() + * @see surf_host_model_init_IB() */ XBT_PUBLIC void surf_network_model_init_IB(); -/** \ingroup SURF_models - * \brief Initializes the platform with the network model 'LegrandVelho' +/** @ingroup SURF_models + * @brief Initializes the platform with the network model 'LegrandVelho' * * This model is proposed by Arnaud Legrand and Pedro Velho based on the results obtained with the GTNets simulator for * onelink and dogbone sharing scenarios. See comments in the code for more information. * - * \see surf_host_model_init_LegrandVelho() + * @see surf_host_model_init_LegrandVelho() */ XBT_PUBLIC void surf_network_model_init_LegrandVelho(); -/** \ingroup SURF_models - * \brief Initializes the platform with the network model 'Constant' +/** @ingroup SURF_models + * @brief Initializes the platform with the network model 'Constant' * * In this model, the communication time between two network cards is constant, hence no need for a routing table. * This is particularly useful when simulating huge distributed algorithms where scalability is really an issue. This * function is called in conjunction with surf_host_model_init_compound. * - * \see surf_host_model_init_compound() + * @see surf_host_model_init_compound() */ XBT_PUBLIC void surf_network_model_init_Constant(); -/** \ingroup SURF_models - * \brief Initializes the platform with the network model CM02 +/** @ingroup SURF_models + * @brief Initializes the platform with the network model CM02 * * You sould call this function by yourself only if you plan using surf_host_model_init_compound. * See comments in the code for more information. */ XBT_PUBLIC void surf_network_model_init_CM02(); -/** \ingroup SURF_models - * \brief Initializes the platform with the network model NS3 +/** @ingroup SURF_models + * @brief Initializes the platform with the network model NS3 * * This function is called by surf_host_model_init_NS3 or by yourself only if you plan using * surf_host_model_init_compound * - * \see surf_host_model_init_NS3() + * @see surf_host_model_init_NS3() */ XBT_PUBLIC void surf_network_model_init_NS3(); -/** \ingroup SURF_models - * \brief Initializes the platform with the network model Reno +/** @ingroup SURF_models + * @brief Initializes the platform with the network model Reno * * The problem is related to max( sum( arctan(C * Df * xi) ) ). * @@ -141,8 +141,8 @@ XBT_PUBLIC void surf_network_model_init_NS3(); */ XBT_PUBLIC void surf_network_model_init_Reno(); -/** \ingroup SURF_models - * \brief Initializes the platform with the network model Reno2 +/** @ingroup SURF_models + * @brief Initializes the platform with the network model Reno2 * * The problem is related to max( sum( arctan(C * Df * xi) ) ). * @@ -154,8 +154,8 @@ XBT_PUBLIC void surf_network_model_init_Reno(); */ XBT_PUBLIC void surf_network_model_init_Reno2(); -/** \ingroup SURF_models - * \brief Initializes the platform with the network model Vegas +/** @ingroup SURF_models + * @brief Initializes the platform with the network model Vegas * * This problem is related to max( sum( a * Df * ln(xi) ) ) which is equivalent to the proportional fairness. * @@ -167,8 +167,8 @@ XBT_PUBLIC void surf_network_model_init_Reno2(); */ XBT_PUBLIC void surf_network_model_init_Vegas(); -/** \ingroup SURF_models - * \brief Initializes the platform with the current best network and cpu models at hand +/** @ingroup SURF_models + * @brief Initializes the platform with the current best network and cpu models at hand * * This platform model seperates the host model and the network model. * The host model will be initialized with the model compound, the network model with the model LV08 (with cross @@ -177,15 +177,15 @@ XBT_PUBLIC void surf_network_model_init_Vegas(); */ XBT_PUBLIC void surf_vm_model_init_HL13(); -/** \ingroup SURF_models - * \brief Initializes the platform with a compound host model +/** @ingroup SURF_models + * @brief Initializes the platform with a compound host model * * This function should be called after a cpu_model and a network_model have been set up. */ XBT_PUBLIC void surf_host_model_init_compound(); -/** \ingroup SURF_models - * \brief Initializes the platform with the current best network and cpu models at hand +/** @ingroup SURF_models + * @brief Initializes the platform with the current best network and cpu models at hand * * This platform model separates the host model and the network model. * The host model will be initialized with the model compound, the network model with the model LV08 (with cross @@ -194,23 +194,23 @@ XBT_PUBLIC void surf_host_model_init_compound(); */ XBT_PUBLIC void surf_host_model_init_current_default(); -/** \ingroup SURF_models - * \brief Initializes the platform with the model L07 +/** @ingroup SURF_models + * @brief Initializes the platform with the model L07 * * With this model, only parallel tasks can be used. Resource sharing is done by identifying bottlenecks and giving an * equal share of the model to each action. */ XBT_PUBLIC void surf_host_model_init_ptask_L07(); -/** \ingroup SURF_models - * \brief The storage model +/** @ingroup SURF_models + * @brief The storage model */ XBT_PUBLIC void surf_storage_model_init_default(); /* -------------------- * Model Descriptions * -------------------- */ -/** \brief Resource model description */ +/** @brief Resource model description */ struct surf_model_description { const char* name; const char* description; diff --git a/src/surf/trace_mgr.hpp b/src/surf/trace_mgr.hpp index 5d74fdf326..a818a1925f 100644 --- a/src/surf/trace_mgr.hpp +++ b/src/surf/trace_mgr.hpp @@ -31,12 +31,12 @@ typedef simgrid::kernel::resource::TraceEvent* tmgr_trace_event_t; extern XBT_PRIVATE simgrid::trace_mgr::future_evt_set future_evt_set; /** - * \brief Free a trace event structure + * @brief Free a trace event structure * * This function frees a trace_event if it can be freed, ie, if it has the free_me flag set to 1. * This flag indicates whether the structure is still used somewhere or not. * When the structure is freed, the argument is set to nullptr -*/ + */ XBT_PUBLIC void tmgr_trace_event_unref(tmgr_trace_event_t* trace_event); XBT_PUBLIC void tmgr_finalize(); diff --git a/src/xbt/dict.cpp b/src/xbt/dict.cpp index bac3293e2d..cac4d276e9 100644 --- a/src/xbt/dict.cpp +++ b/src/xbt/dict.cpp @@ -1,14 +1,10 @@ /* dict - a generic dictionary, variation over hash table */ -/* Copyright (c) 2004-2018. The SimGrid Team. - * All rights reserved. */ +/* Copyright (c) 2004-2018. The SimGrid Team. All rights reserved. */ /* This program is free software; you can redistribute it and/or modify it * under the terms of the license (GNU LGPL) which comes with this package. */ -#include -#include - #include "xbt/dict.h" #include "xbt/ex.h" #include @@ -18,13 +14,16 @@ #include "xbt/str.h" #include "dict_private.h" +#include +#include + XBT_LOG_NEW_DEFAULT_SUBCATEGORY(xbt_dict, xbt, "Dictionaries provide the same functionalities as hash tables"); /** - * \brief Constructor - * \param free_ctn function to call with (\a data as argument) when \a data is removed from the dictionary - * \return pointer to the destination - * \see xbt_dict_free() + * @brief Constructor + * @param free_ctn function to call with (@a data as argument) when @a data is removed from the dictionary + * @return pointer to the destination + * @see xbt_dict_free() * * Creates and initialize a new dictionary with a default hashtable size. * The dictionary is homogeneous: each element share the same free function. @@ -47,8 +46,8 @@ xbt_dict_t xbt_dict_new_homogeneous(void_f_pvoid_t free_ctn) } /** - * \brief Destructor - * \param dict the dictionary to be freed + * @brief Destructor + * @param dict the dictionary to be freed * * Frees a dictionary with all the data */ @@ -123,15 +122,15 @@ static void xbt_dict_rehash(xbt_dict_t dict) } /** - * \brief Add data to the dict (arbitrary key) - * \param dict the container - * \param key the key to set the new data - * \param key_len the size of the \a key - * \param data the data to add in the dict - * \param free_ctn unused parameter (kept for compatibility) + * @brief Add data to the dict (arbitrary key) + * @param dict the container + * @param key the key to set the new data + * @param key_len the size of the @a key + * @param data the data to add in the dict + * @param free_ctn unused parameter (kept for compatibility) * - * Set the \a data in the structure under the \a key, which can be any kind of data, as long as its length is provided - * in \a key_len. + * Set the @a data in the structure under the @a key, which can be any kind of data, as long as its length is provided + * in @a key_len. */ void xbt_dict_set_ext(xbt_dict_t dict, const char* key, int key_len, void* data, XBT_ATTRIB_UNUSED void_f_pvoid_t free_ctn) @@ -171,14 +170,14 @@ void xbt_dict_set_ext(xbt_dict_t dict, const char* key, int key_len, void* data, } /** - * \brief Add data to the dict (null-terminated key) + * @brief Add data to the dict (null-terminated key) * - * \param dict the dict - * \param key the key to set the new data - * \param data the data to add in the dict - * \param free_ctn unused parameter (kept for compatibility) + * @param dict the dict + * @param key the key to set the new data + * @param data the data to add in the dict + * @param free_ctn unused parameter (kept for compatibility) * - * set the \a data in the structure under the \a key, which is anull terminated string. + * set the @a data in the structure under the @a key, which is anull terminated string. */ void xbt_dict_set(xbt_dict_t dict, const char *key, void *data, void_f_pvoid_t free_ctn) { @@ -186,14 +185,14 @@ void xbt_dict_set(xbt_dict_t dict, const char *key, void *data, void_f_pvoid_t f } /** - * \brief Retrieve data from the dict (arbitrary key) + * @brief Retrieve data from the dict (arbitrary key) * - * \param dict the dealer of data - * \param key the key to find data - * \param key_len the size of the \a key - * \return the data that we are looking for + * @param dict the dealer of data + * @param key the key to find data + * @param key_len the size of the @a key + * @return the data that we are looking for * - * Search the given \a key. Throws not_found_error when not found. + * Search the given @a key. Throws not_found_error when not found. */ void *xbt_dict_get_ext(xbt_dict_t dict, const char *key, int key_len) { @@ -247,13 +246,13 @@ char *xbt_dict_get_key(xbt_dict_t dict, const void *data) } /** - * \brief Retrieve data from the dict (null-terminated key) + * @brief Retrieve data from the dict (null-terminated key) * - * \param dict the dealer of data - * \param key the key to find data - * \return the data that we are looking for + * @param dict the dealer of data + * @param key the key to find data + * @return the data that we are looking for * - * Search the given \a key. Throws not_found_error when not found. + * Search the given @a key. Throws not_found_error when not found. * Check xbt_dict_get_or_null() for a version returning nullptr without exception when not found. */ void *xbt_dict_get(xbt_dict_t dict, const char *key) @@ -262,13 +261,13 @@ void *xbt_dict_get(xbt_dict_t dict, const char *key) } /** - * \brief Retrieve element from the dict (null-terminated key) + * @brief Retrieve element from the dict (null-terminated key) * - * \param dict the dealer of data - * \param key the key to find data - * \return the s_xbt_dictelm_t that we are looking for + * @param dict the dealer of data + * @param key the key to find data + * @return the s_xbt_dictelm_t that we are looking for * - * Search the given \a key. Throws not_found_error when not found. + * Search the given @a key. Throws not_found_error when not found. * Check xbt_dict_get_or_null() for a version returning nullptr without exception when not found. */ xbt_dictelm_t xbt_dict_get_elm(xbt_dict_t dict, const char *key) @@ -282,7 +281,7 @@ xbt_dictelm_t xbt_dict_get_elm(xbt_dict_t dict, const char *key) } /** - * \brief like xbt_dict_get(), but returning nullptr when not found + * @brief like xbt_dict_get(), but returning nullptr when not found */ void *xbt_dict_get_or_null(xbt_dict_t dict, const char *key) { @@ -295,7 +294,7 @@ void *xbt_dict_get_or_null(xbt_dict_t dict, const char *key) } /** - * \brief like xbt_dict_get_elm(), but returning nullptr when not found + * @brief like xbt_dict_get_elm(), but returning nullptr when not found */ xbt_dictelm_t xbt_dict_get_elm_or_null(xbt_dict_t dict, const char *key) { @@ -308,13 +307,13 @@ xbt_dictelm_t xbt_dict_get_elm_or_null(xbt_dict_t dict, const char *key) } /** - * \brief Remove data from the dict (arbitrary key) + * @brief Remove data from the dict (arbitrary key) * - * \param dict the trash can - * \param key the key of the data to be removed - * \param key_len the size of the \a key + * @param dict the trash can + * @param key the key of the data to be removed + * @param key_len the size of the @a key * - * Remove the entry associated with the given \a key (throws not_found) + * Remove the entry associated with the given @a key (throws not_found) */ void xbt_dict_remove_ext(xbt_dict_t dict, const char *key, int key_len) { @@ -346,12 +345,12 @@ void xbt_dict_remove_ext(xbt_dict_t dict, const char *key, int key_len) } /** - * \brief Remove data from the dict (null-terminated key) + * @brief Remove data from the dict (null-terminated key) * - * \param dict the dict - * \param key the key of the data to be removed + * @param dict the dict + * @param key the key of the data to be removed * - * Remove the entry associated with the given \a key + * Remove the entry associated with the given @a key */ void xbt_dict_remove(xbt_dict_t dict, const char *key) { @@ -380,8 +379,8 @@ void xbt_dict_reset(xbt_dict_t dict) } /** - * \brief Return the number of elements in the dict. - * \param dict a dictionary + * @brief Return the number of elements in the dict. + * @param dict a dictionary */ int xbt_dict_length(xbt_dict_t dict) { @@ -389,7 +388,7 @@ int xbt_dict_length(xbt_dict_t dict) } /** - * \brief test if the dict is empty or not + * @brief test if the dict is empty or not */ int xbt_dict_is_empty(xbt_dict_t dict) { @@ -397,13 +396,13 @@ int xbt_dict_is_empty(xbt_dict_t dict) } /** - * \brief Outputs the content of the structure (debugging purpose) + * @brief Outputs the content of the structure (debugging purpose) * - * \param dict the exibitionist - * \param output a function to dump each data in the tree + * @param dict the exibitionist + * @param output a function to dump each data in the tree * * Outputs the content of the structure. (for debugging purpose). - * \a output is a function to output the data. If nullptr, data won't be displayed. + * @a output is a function to output the data. If nullptr, data won't be displayed. */ void xbt_dict_dump(xbt_dict_t dict, void_f_pvoid_t output) { diff --git a/src/xbt/dict_cursor.c b/src/xbt/dict_cursor.c index b528645f03..0b609f9867 100644 --- a/src/xbt/dict_cursor.c +++ b/src/xbt/dict_cursor.c @@ -84,7 +84,7 @@ inline void xbt_dict_cursor_first(const xbt_dict_t dict, xbt_dict_cursor_t * cur } } -/** \brief Move to the next element. */ +/** @brief Move to the next element. */ inline void xbt_dict_cursor_step(xbt_dict_cursor_t cursor) { xbt_dictelm_t current; diff --git a/src/xbt/dynar.cpp b/src/xbt/dynar.cpp index b2420dac6e..ff95c5507b 100644 --- a/src/xbt/dynar.cpp +++ b/src/xbt/dynar.cpp @@ -83,8 +83,8 @@ void xbt_dynar_dump(xbt_dynar_t dynar) /** @brief Constructor * - * \param elmsize size of each element in the dynar - * \param free_f function to call each time we want to get rid of an element (or nullptr if nothing to do). + * @param elmsize size of each element in the dynar + * @param free_f function to call each time we want to get rid of an element (or nullptr if nothing to do). * * Creates a new dynar. If a free_func is provided, the elements have to be pointer of pointer. That is to say that * dynars can contain either base types (int, char, double, etc) or pointer of pointers (struct **). @@ -124,9 +124,9 @@ void xbt_dynar_free_data(xbt_dynar_t dynar) /** @brief Destructor of the structure not touching to the content * - * \param dynar poor victim + * @param dynar poor victim * - * kilkil a dynar BUT NOT its content. Ie, the array is freed, but the content is not touched (the \a free_f function + * kilkil a dynar BUT NOT its content. Ie, the array is freed, but the content is not touched (the @a free_f function * is not used) */ void xbt_dynar_free_container(xbt_dynar_t* dynar) @@ -141,7 +141,7 @@ void xbt_dynar_free_container(xbt_dynar_t* dynar) /** @brief Frees the content and set the size to 0 * - * \param dynar who to squeeze + * @param dynar who to squeeze */ void xbt_dynar_reset(xbt_dynar_t const dynar) { @@ -156,8 +156,8 @@ void xbt_dynar_reset(xbt_dynar_t const dynar) /** @brief Merge dynar d2 into d1 * - * \param d1 dynar to keep - * \param d2 dynar to merge into d1. This dynar is free at end. + * @param d1 dynar to keep + * @param d2 dynar to merge into d1. This dynar is free at end. */ void xbt_dynar_merge(xbt_dynar_t* d1, xbt_dynar_t* d2) { @@ -177,15 +177,15 @@ void xbt_dynar_merge(xbt_dynar_t* d1, xbt_dynar_t* d2) } /** - * \brief Shrink the dynar by removing empty slots at the end of the internal array - * \param dynar a dynar - * \param empty_slots_wanted number of empty slots you want to keep at the end of the internal array for further + * @brief Shrink the dynar by removing empty slots at the end of the internal array + * @param dynar a dynar + * @param empty_slots_wanted number of empty slots you want to keep at the end of the internal array for further * insertions * - * Reduces the internal array size of the dynar to the number of elements plus \a empty_slots_wanted. + * Reduces the internal array size of the dynar to the number of elements plus @a empty_slots_wanted. * After removing elements from the dynar, you can call this function to make the dynar use less memory. - * Set \a empty_slots_wanted to zero to reduce the dynar internal array as much as possible. - * Note that if \a empty_slots_wanted is greater than the array size, the internal array is expanded instead of shrunk. + * Set @a empty_slots_wanted to zero to reduce the dynar internal array as much as possible. + * Note that if @a empty_slots_wanted is greater than the array size, the internal array is expanded instead of shrunk. */ void xbt_dynar_shrink(xbt_dynar_t dynar, int empty_slots_wanted) { @@ -194,7 +194,7 @@ void xbt_dynar_shrink(xbt_dynar_t dynar, int empty_slots_wanted) /** @brief Destructor * - * \param dynar poor victim + * @param dynar poor victim * * kilkil a dynar and its content */ @@ -206,7 +206,7 @@ void xbt_dynar_free(xbt_dynar_t* dynar) } } -/** \brief free a dynar passed as void* (handy to store dynar in dynars or dict) */ +/** @brief free a dynar passed as void* (handy to store dynar in dynars or dict) */ void xbt_dynar_free_voidp(void* d) { xbt_dynar_t dynar = (xbt_dynar_t)d; @@ -215,16 +215,16 @@ void xbt_dynar_free_voidp(void* d) /** @brief Count of dynar's elements * - * \param dynar the dynar we want to mesure + * @param dynar the dynar we want to mesure */ unsigned long xbt_dynar_length(const xbt_dynar_t dynar) { return (dynar ? (unsigned long) dynar->used : (unsigned long) 0); } - /**@brief check if a dynar is empty +/**@brief check if a dynar is empty * - *\param dynar the dynat we want to check + *@param dynar the dynat we want to check */ int xbt_dynar_is_empty(const xbt_dynar_t dynar) { @@ -233,9 +233,9 @@ int xbt_dynar_is_empty(const xbt_dynar_t dynar) /** @brief Retrieve a copy of the Nth element of a dynar. * - * \param dynar information dealer - * \param idx index of the slot we want to retrieve - * \param[out] dst where to put the result to. + * @param dynar information dealer + * @param idx index of the slot we want to retrieve + * @param[out] dst where to put the result to. */ void xbt_dynar_get_cpy(const xbt_dynar_t dynar, const unsigned long idx, void* const dst) { @@ -247,11 +247,11 @@ void xbt_dynar_get_cpy(const xbt_dynar_t dynar, const unsigned long idx, void* c /** @brief Retrieve a pointer to the Nth element of a dynar. * - * \param dynar information dealer - * \param idx index of the slot we want to retrieve - * \return the \a idx-th element of \a dynar. + * @param dynar information dealer + * @param idx index of the slot we want to retrieve + * @return the @a idx-th element of @a dynar. * - * \warning The returned value is the actual content of the dynar. + * @warning The returned value is the actual content of the dynar. * Make a copy before fooling with it. */ void* xbt_dynar_get_ptr(const xbt_dynar_t dynar, const unsigned long idx) @@ -280,9 +280,9 @@ void* xbt_dynar_set_at_ptr(const xbt_dynar_t dynar, const unsigned long idx) /** @brief Set the Nth element of a dynar (expanded if needed). Previous value at this position is NOT freed * - * \param dynar information dealer - * \param idx index of the slot we want to modify - * \param src What will be feeded to the dynar + * @param dynar information dealer + * @param idx index of the slot we want to modify + * @param src What will be feeded to the dynar * * If you want to free the previous content, use xbt_dynar_replace(). */ @@ -293,9 +293,9 @@ void xbt_dynar_set(xbt_dynar_t dynar, const int idx, const void* const src) /** @brief Set the Nth element of a dynar (expanded if needed). Previous value is freed * - * \param dynar - * \param idx - * \param object + * @param dynar + * @param idx + * @param object * * Set the Nth element of a dynar, expanding the dynar if needed, AND DO free the previous value at this position. If * you don't want to free the previous content, use xbt_dynar_set(). @@ -421,7 +421,7 @@ void xbt_dynar_remove_n_at(xbt_dynar_t const dynar, const unsigned int n, const * Beware that if your dynar contains pointed values (such as strings) instead of scalar, this function compares the * pointer value, not what's pointed. The only solution to search for a pointed value is then to write the foreach loop * yourself: - * \code + * @code * signed int position = -1; * xbt_dynar_foreach(dynar, iter, elem) { * if (not memcmp(elem, searched_element, sizeof(*elem))) { @@ -429,7 +429,7 @@ void xbt_dynar_remove_n_at(xbt_dynar_t const dynar, const unsigned int n, const * break; * } * } - * \endcode + * @endcode * * Raises not_found_error if not found. If you have less than 2 millions elements, you probably want to use * #xbt_dynar_search_or_negative() instead, so that you don't have to TRY/CATCH on element not found. @@ -594,8 +594,8 @@ void xbt_dynar_cursor_rm(xbt_dynar_t dynar, unsigned int* const cursor) * } * @endverbatim * - * \param dynar the dynar to sort - * \param compar_fn comparison function of type (int (compar_fn*) (const void*) (const void*)). + * @param dynar the dynar to sort + * @param compar_fn comparison function of type (int (compar_fn*) (const void*) (const void*)). */ void xbt_dynar_sort(xbt_dynar_t dynar, int_f_cpvoid_cpvoid_t compar_fn) { @@ -616,8 +616,8 @@ xbt_dynar_t xbt_dynar_sort_strings(xbt_dynar_t dynar) /** @brief Transform a dynar into a nullptr terminated array. * - * \param dynar the dynar to transform - * \return pointer to the first element of the array + * @param dynar the dynar to transform + * @return pointer to the first element of the array * * Note: The dynar won't be usable afterwards. */ @@ -633,10 +633,10 @@ void* xbt_dynar_to_array(xbt_dynar_t dynar) /** @brief Compare two dynars * - * \param d1 first dynar to compare - * \param d2 second dynar to compare - * \param compar function to use to compare elements - * \return 0 if d1 and d2 are equal and 1 if not equal + * @param d1 first dynar to compare + * @param d2 second dynar to compare + * @param compar function to use to compare elements + * @return 0 if d1 and d2 are equal and 1 if not equal * * d1 and d2 should be dynars of pointers. The compar function takes two elements and returns 0 when they are * considered equal, and a value different of zero when they are considered different. Finally, d2 is destroyed diff --git a/src/xbt/ex.cpp b/src/xbt/ex.cpp index ac0b6de577..76f083755e 100644 --- a/src/xbt/ex.cpp +++ b/src/xbt/ex.cpp @@ -43,7 +43,7 @@ void xbt_ex_display(xbt_ex_t * e) simgrid::xbt::log_exception(xbt_log_priority_critical, "UNCAUGHT EXCEPTION", *e); } -/** \brief returns a short name for the given exception category */ +/** @brief returns a short name for the given exception category */ const char *xbt_ex_catname(xbt_errcat_t cat) { switch (cat) { diff --git a/src/xbt/log.c b/src/xbt/log.c index fe6d5d8048..094ed9f158 100644 --- a/src/xbt/log.c +++ b/src/xbt/log.c @@ -33,7 +33,7 @@ int xbt_log_no_loc = 0; /* if set to true (with --log=no_loc), file localization will be omitted (for tesh tests) */ static xbt_os_mutex_t log_cat_init_mutex = NULL; -/** \addtogroup XBT_log +/** @addtogroup XBT_log * * For more information, please refer to @ref outcomes_logs Section. */ @@ -537,14 +537,14 @@ static xbt_log_category_t _xbt_log_cat_searchsub(xbt_log_category_t cat, char *n } /** - * \ingroup XBT_log - * \param control_string What to parse + * @ingroup XBT_log + * @param control_string What to parse * * Typically passed a command-line argument. The string has the syntax: * * ( [category] "." [keyword] ":" value (" ")... )... * - * where [category] is one the category names (see \ref XBT_log_cats for a complete list of the ones defined in the + * where [category] is one the category names (see @ref XBT_log_cats for a complete list of the ones defined in the * SimGrid library) and keyword is one of the following: * * - thres: category's threshold priority. Possible values: @@ -552,8 +552,8 @@ static xbt_log_category_t _xbt_log_cat_searchsub(xbt_log_category_t cat, char *n * - add or additivity: whether the logging actions must be passed to the parent category. * Possible values: 0, 1, no, yes, on, off. * Default value: yes. - * - fmt: the format to use. See \ref log_use_conf_fmt for more information. - * - app or appender: the appender to use. See \ref log_use_conf_app for more information. + * - fmt: the format to use. See @ref log_use_conf_fmt for more information. + * - app or appender: the appender to use. See @ref log_use_conf_app for more information. */ void xbt_log_control_set(const char *control_string) { diff --git a/src/xbt/log_private.h b/src/xbt/log_private.h index e5095be5b4..41bdf56226 100644 --- a/src/xbt/log_private.h +++ b/src/xbt/log_private.h @@ -20,9 +20,9 @@ struct xbt_log_layout_s { }; /** - * \ingroup XBT_log_implem - * \param cat the category (not only its name, but the variable) - * \param parent the parent cat + * @ingroup XBT_log_implem + * @param cat the category (not only its name, but the variable) + * @param parent the parent cat * * Programatically alter a category's parent (don't use). */ diff --git a/src/xbt/mallocator.c b/src/xbt/mallocator.c index 9b7bd8e8eb..8e2b397649 100644 --- a/src/xbt/mallocator.c +++ b/src/xbt/mallocator.c @@ -1,7 +1,6 @@ /* mallocator - recycle objects to avoid malloc() / free() */ -/* Copyright (c) 2006-2018. The SimGrid Team. - * All rights reserved. */ +/* Copyright (c) 2006-2018. The SimGrid Team. All rights reserved. */ /* This program is free software; you can redistribute it and/or modify it * under the terms of the license (GNU LGPL) which comes with this package. */ @@ -85,19 +84,19 @@ static inline int xbt_mallocator_is_active(void) { } /** - * \brief Constructor - * \param size size of the internal stack: number of objects the mallocator will be able to store - * \param new_f function to allocate a new object of your datatype, called in \a xbt_mallocator_get() when the + * @brief Constructor + * @param size size of the internal stack: number of objects the mallocator will be able to store + * @param new_f function to allocate a new object of your datatype, called in @a xbt_mallocator_get() when the * mallocator is empty - * \param free_f function to free an object of your datatype, called in \a xbt_mallocator_release() when the stack is + * @param free_f function to free an object of your datatype, called in @a xbt_mallocator_release() when the stack is * full, and when the mallocator is freed. - * \param reset_f function to reinitialise an object of your datatype, called when you extract an object from the + * @param reset_f function to reinitialise an object of your datatype, called when you extract an object from the * mallocator (can be NULL) * * Create and initialize a new mallocator for a given datatype. * - * \return pointer to the created mallocator - * \see xbt_mallocator_free() + * @return pointer to the created mallocator + * @see xbt_mallocator_free() */ xbt_mallocator_t xbt_mallocator_new(int size, pvoid_f_void_t new_f, void_f_pvoid_t free_f, void_f_pvoid_t reset_f) { @@ -117,12 +116,12 @@ xbt_mallocator_t xbt_mallocator_new(int size, pvoid_f_void_t new_f, void_f_pvoid return m; } -/** \brief Destructor - * \param m the mallocator you want to destroy +/** @brief Destructor + * @param m the mallocator you want to destroy * * Destroy the mallocator and all its data. The function free_f is called on each object in the mallocator. * - * \see xbt_mallocator_new() + * @see xbt_mallocator_new() */ void xbt_mallocator_free(xbt_mallocator_t m) { @@ -138,8 +137,8 @@ void xbt_mallocator_free(xbt_mallocator_t m) } /** - * \brief Extract an object from a mallocator - * \param m a mallocator + * @brief Extract an object from a mallocator + * @param m a mallocator * * Remove an object from the mallocator and return it. * This function is designed to be used instead of malloc(). @@ -149,7 +148,7 @@ void xbt_mallocator_free(xbt_mallocator_t m) * * In both cases, the function reset_f() (if defined) is called on the object. * - * \see xbt_mallocator_release() + * @see xbt_mallocator_release() */ void *xbt_mallocator_get(xbt_mallocator_t m) { @@ -186,16 +185,16 @@ void *xbt_mallocator_get(xbt_mallocator_t m) return object; } -/** \brief Push an object into a mallocator - * \param m a mallocator - * \param object an object you don't need anymore +/** @brief Push an object into a mallocator + * @param m a mallocator + * @param object an object you don't need anymore * * Push into the mallocator an object you don't need anymore. * This function is designed to be used instead of free(). * If the mallocator is not full, your object if stored into the mallocator and no free is done. * If the mallocator is full, the object is freed by calling the function free_f(). * - * \see xbt_mallocator_get() + * @see xbt_mallocator_get() */ void xbt_mallocator_release(xbt_mallocator_t m, void *object) { diff --git a/src/xbt/mmalloc/swag.c b/src/xbt/mmalloc/swag.c index 573a321263..1df21d0375 100644 --- a/src/xbt/mmalloc/swag.c +++ b/src/xbt/mmalloc/swag.c @@ -27,10 +27,10 @@ static inline void *xbt_swag_getFirst(const_xbt_swag_t swag) } /* - * \brief Offset computation - * \arg var a variable of type struct something - * \arg field a field of struct something - * \return the offset of \a field in struct something. + * @brief Offset computation + * @arg var a variable of type struct something + * @arg field a field of struct something + * @return the offset of @a field in struct something. * @hideinitializer * * It is very similar to offsetof except that is done at runtime and that you have to declare a variable. Why defining @@ -40,9 +40,9 @@ static inline void *xbt_swag_getFirst(const_xbt_swag_t swag) /* @} */ /* Creates a new swag. - * \param swag the swag to initialize - * \param offset where the hookup is located in the structure - * \see xbt_swag_offset + * @param swag the swag to initialize + * @param offset where the hookup is located in the structure + * @see xbt_swag_offset * * Usage : xbt_swag_init(swag,&obj.setA-&obj); */ @@ -55,11 +55,11 @@ static inline void xbt_swag_init(xbt_swag_t swag, size_t offset) } /* - * \param obj the objet to insert in the swag - * \param swag a swag + * @param obj the objet to insert in the swag + * @param swag a swag * - * insert (at the tail... you probably had a very good reason to do that, I hope you know what you're doing) \a obj in - * \a swag + * insert (at the tail... you probably had a very good reason to do that, I hope you know what you're doing) @a obj in + * @a swag */ static inline void xbt_swag_insert(void *obj, xbt_swag_t swag) { @@ -80,11 +80,11 @@ static inline void xbt_swag_insert(void *obj, xbt_swag_t swag) } /* - * \param obj the objet to remove from the swag - * \param swag a swag - * \return \a obj if it was in the \a swag and NULL otherwise + * @param obj the objet to remove from the swag + * @param swag a swag + * @return @a obj if it was in the @a swag and NULL otherwise * - * removes \a obj from \a swag + * removes @a obj from @a swag */ static inline void *xbt_swag_remove(void *obj, xbt_swag_t swag) { @@ -119,8 +119,8 @@ static inline void *xbt_swag_remove(void *obj, xbt_swag_t swag) } /* - * \param swag a swag - * \return the number of objects in \a swag + * @param swag a swag + * @return the number of objects in @a swag */ static inline int xbt_swag_size(const_xbt_swag_t swag) { diff --git a/src/xbt/xbt_os_time.c b/src/xbt/xbt_os_time.c index 8fd95b5e57..25864106f7 100644 --- a/src/xbt/xbt_os_time.c +++ b/src/xbt/xbt_os_time.c @@ -104,8 +104,8 @@ void xbt_os_sleep(double sec) /* TSC (tick-level) timers are said to be unreliable on SMP hosts and thus disabled in SDL source code */ -/* \defgroup XBT_sysdep All system dependency - * \brief This section describes many macros/functions that can serve as an OS abstraction. +/* @defgroup XBT_sysdep All system dependency + * @brief This section describes many macros/functions that can serve as an OS abstraction. */ struct s_xbt_os_timer { #if HAVE_POSIX_GETTIME diff --git a/src/xbt/xbt_replay.cpp b/src/xbt/xbt_replay.cpp index b889434cf9..af68627239 100644 --- a/src/xbt/xbt_replay.cpp +++ b/src/xbt/xbt_replay.cpp @@ -1,5 +1,4 @@ -/* Copyright (c) 2010-2018. The SimGrid Team. - * All rights reserved. */ +/* Copyright (c) 2010-2018. The SimGrid Team. All rights reserved. */ /* This program is free software; you can redistribute it and/or modify it * under the terms of the license (GNU LGPL) which comes with this package. */ @@ -115,8 +114,8 @@ static void handle_action(ReplayAction& action) } /** - * \ingroup XBT_replay - * \brief function used internally to actually run the replay + * @ingroup XBT_replay + * @brief function used internally to actually run the replay */ int replay_runner(int argc, char* argv[]) { @@ -154,16 +153,16 @@ int replay_runner(int argc, char* argv[]) } /** - * \ingroup XBT_replay - * \brief Registers a function to handle a kind of action + * @ingroup XBT_replay + * @brief Registers a function to handle a kind of action * * Registers a function to handle a kind of action - * This table is then used by \ref simgrid::xbt::replay_runner + * This table is then used by @ref simgrid::xbt::replay_runner * * The argument of the function is the line describing the action, fields separated by spaces. * - * \param action_name the reference name of the action. - * \param function prototype given by the type: void...(const char** action) + * @param action_name the reference name of the action. + * @param function prototype given by the type: void...(const char** action) */ void xbt_replay_action_register(const char* action_name, action_fun function) { @@ -171,8 +170,8 @@ void xbt_replay_action_register(const char* action_name, action_fun function) } /** - * \ingroup XBT_replay - * \brief Get the function that was previously registered to handle a kind of action + * @ingroup XBT_replay + * @brief Get the function that was previously registered to handle a kind of action * * This can be useful if you want to override and extend an existing action. */ diff --git a/tools/generate-dwarf-functions b/tools/generate-dwarf-functions index 8ecc0fa42c..301c2b5492 100755 --- a/tools/generate-dwarf-functions +++ b/tools/generate-dwarf-functions @@ -29,10 +29,10 @@ $(cat "$1" | grep DW_TAG_ | sed 's/.*\(DW_TAG_[^ ]*\) = \(0x[0-9a-f]*\).*/ {\ namespace simgrid { namespace dwarf { -/** \brief Get the name of a dwarf tag (DW_TAG_*) from its code +/** @brief Get the name of a dwarf tag (DW_TAG_*) from its code * - * \param tag tag code (see the DWARF specification) - * \return name of the tag + * @param tag tag code (see the DWARF specification) + * @return name of the tag */ XBT_PRIVATE const char *tagname(int tag) @@ -57,10 +57,10 @@ $(cat "$1" | grep DW_AT_ | sed 's/.*\(DW_AT_[^ ]*\) = \(0x[0-9a-f]*\).*/ {\2, namespace simgrid { namespace dwarf { -/** \brief Get the name of an attribute (DW_AT_*) from its code +/** @brief Get the name of an attribute (DW_AT_*) from its code * - * \param attr attribute code (see the DWARF specification) - * \return name of the attribute + * @param attr attribute code (see the DWARF specification) + * @return name of the attribute */ XBT_PRIVATE const char *attrname(int attr) -- 2.20.1