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-<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
**
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-<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)
# 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
-/*! \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
<a href="http://people.irisa.fr/Martin.Quinson/blog/SimGrid/">blog of
Martin Quinson</a>.
-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: <simgrid-user@lists.gforge.inria.fr>.
-\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 ;)
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 <tt>tools/MSG_visualization/colorize.pl </tt>
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.
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
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
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
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
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,
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();
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
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,
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
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.
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
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(...);
}
}
}
-\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
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.
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
<i>rewind</i> 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
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
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
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
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
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
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
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:
- - <b>You are using a broken build environment</b>\n
+ - <b>You are using a broken build environment</b>@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.
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
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
specify <tt>-lpthread</tt> on the linker command line. As usual, this should
come after <tt>-lsimgrid</tt> 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
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:
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)
==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
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
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 <tt>--suppressions=$HOME/.valgrind.supp</tt> option on the command line.
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
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
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
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
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.
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 <simgrid-devel@lists.gforge.inria.fr>
-
*/
-/*! \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 <a href="http://simgrid.gforge.inria.fr/documentation.html"> tutorial section</a> 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 <a href="http://simgrid.gforge.inria.fr/documentation.html"> tutorial section</a> that contains a dedicated tutorial.
-\endhtmlonly
+@endhtmlonly
Here are some examples on how to use MSG, the most used API.
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
<hr>
-\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
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
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
Its arguments are:
- <i>platform_file</i>: the name of a file containing an valid platform description.
- <i>deployment_file</i>: 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
*/
/*!
@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 <a href="http://www.cmake.org/">official CMake web site</a>.
-\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
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)
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,
- 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
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.
/*!
@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
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
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
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
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
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
@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
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...
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
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.
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:
/**
@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
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.
};
~~~~
-\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.
};
~~~~
-\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
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
<b>Note:</b> `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.
/*!
-\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.
- 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.
- 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/
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
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
- 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.
- 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
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
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
<a href="https://ci.inria.fr/simgrid/">available</a>.
-\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
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
./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.
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
)
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
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
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.
- <b>Write the tesh file</b>, 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
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 <project/directory>/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 <project/directory>/tools/tesh/ directory, that can be useful to understand the tesh syntax.
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 <options> <tesh-file>)
# option --setenv bindir set the directory containing the binary
# --setenv srcdir set the directory containing the source file
--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.
miss issues. And we use <a href="https://ci.appveyor.com/project/mquinson/simgrid">AppVeyor</a>
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
The result can be seen here: https://ci.inria.fr/simgrid/
We have 2 interesting projects on Jenkins:
-
\li <a href="https://ci.inria.fr/simgrid/job/SimGrid/">SimGrid</a>
- is the main project, running the tests that we spoke about.\n It is
+
@li <a href="https://ci.inria.fr/simgrid/job/SimGrid/">SimGrid</a>
+ is the main project, running the tests that we spoke about.@n It is
configured (on Jenkins) to run the script <tt>tools/jenkins/build.sh</tt>
-
\li <a href="https://ci.inria.fr/simgrid/job/SimGrid-DynamicAnalysis/">SimGrid-DynamicAnalysis</a>
+
@li <a href="https://ci.inria.fr/simgrid/job/SimGrid-DynamicAnalysis/">SimGrid-DynamicAnalysis</a>
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 <tt>tools/jenkins/DynamicAnalysis.sh</tt>
In each case, SimGrid gets built 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:
#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
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
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
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
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
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.
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
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
*/
@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
/** @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
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
/** @addtogroup SIMIX_API
- \section smx_detail Coming soon
+ @section smx_detail Coming soon
@{ */
/** @defgroup m_datatypes_management_details SIMIX datatypes management details */
/** @} */
-/** \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:
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.
/**
-\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
@{
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 */
* * PORTABILITY-INTERNALS * * (not included in documentation)
* ************************* */
- /** \addtogroup XBT_context Portable context implementation
- * \brief Contexts are a higher level system than <tt>setjump/longjmp</tt>
+ /** @addtogroup XBT_context Portable context implementation
+ * @brief Contexts are a higher level system than <tt>setjump/longjmp</tt>
* 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.
*/
-/*! \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
<a href="http://www.nsnam.org/"><b>ns-3</b></a> 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
./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
<a href="http://www.nsnam.org/">(official website)</a>.
-\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 <tt>include/simgrid/config.h</tt>
-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 <tt>CMakeFiles/CMakeOutput.log</tt> and
<tt>CMakeFiles/CMakeError.log</tt> 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
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
@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.
-/*! \page options Configure SimGrid
+/*! @page options Configure SimGrid
-\htmlonly
+@htmlonly
<div align="center">
-\endhtmlonly
-\htmlinclude graphical-toc.svg
-\htmlonly
+@endhtmlonly
+@htmlinclude graphical-toc.svg
+@htmlonly
</div>
<script>
document.getElementById("Config").style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1;stroke:#000000;stroke-width:0.35277778;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1";
</script>
-\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
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 \<config\> tag in the platform file. The
+Another solution is to use the @c @<config@> tag in the platform file. The
only restriction is that this tag must occure before the first
-platform element (be it \c \<AS\>, \c \<cluster\>, \c \<peer\> or whatever).
-The \c \<config\> tag takes an \c id attribute, but it is currently
+platform element (be it @c @<AS@>, @c @<cluster@>, @c @<peer@> or whatever).
+The @c @<config@> 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 \<prop\> 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 @<prop@> 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
<config>
<prop id="Item" value="Value"/>
</config>
-\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.
}
@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 <b>For collective operations of SMPI, please refer to Section \ref options_index_smpi_coll</b>
-- \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 <b>Tracing configuration options can be found in Section \ref tracing_tracing_options</b>.
-
-- \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 <b>For collective operations of SMPI, please refer to Section @ref options_index_smpi_coll</b>
+- @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 <b>Tracing configuration options can be found in Section @ref tracing_tracing_options</b>.
+
+- @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
described in
<a href="http://mescal.imag.fr/membres/arnaud.legrand/articles/simutools09.pdf">Accuracy Study and Improvement of Network Simulation in the SimGrid Framework</a>.
- - \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
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
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
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.
<a href="http://mescal.imag.fr/membres/jean-marc.vincent/index.html/PhD/Vienne.pdf">this PhD thesis</a>.
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
pair of interconnected hosts. An example of usable platform is
available in <tt>examples/platforms/crosstraffic.xml</tt>.
-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.
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:<filename>
-\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
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
liveness properties since it may break some cycles in the exploration
that are important to the property validity.
-\verbatim
+@verbatim
--cfg=model-check/reduction:<technique>
-\endverbatim
+@endverbatim
For now, this configuration variable can take 2 values:
* none: Do not apply any kind of reduction (mandatory for now for
* 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
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.
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
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
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
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:
</pre>
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).
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
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.
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
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.
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
- 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
<a href="http://hal.inria.fr/inria-00602216/">INRIA RR-7653</a>.
-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
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.
- 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 <i>-trace</i> parameter for the smpirun script runs the
simulation with --cfg=tracing:yes and --cfg=tracing/smpi:yes. Check the
smpirun's <i>-help</i> parameter for additional tracing options.
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,
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.
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 ?
---------------------------------- | ------------------------------- | ------------------------
--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
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
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
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
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
to choose between them.
- <b>no</b> (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.
- <b>dlopen</b> or <b>yes</b> (default when using smpirun): Link multiple times against the binary.
- <b>mmap</b> (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
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:
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
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.
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".
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
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
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
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.
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
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.
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
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
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
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
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.
*/
-/*! \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
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
tasks that are not classified according to a category are not
traced</em>. 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
<b>--cfg=</b> switch:
-\li <b>\c
+@li <b>@c
tracing
</b>:
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 <b>\c
+@li <b>@c
tracing/categorized
</b>:
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 <b>\c
+@li <b>@c
tracing/uncategorized
</b>:
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 <b>\c
+@li <b>@c
tracing/filename
</b>:
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:
<a href="http://github.com/schnorr/pajeng/">http://github.com/schnorr/pajeng/</a>
-\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 <b>\c
+@li <b>@c
tracing/smpi
</b>:
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 <b>\c
+@li <b>@c
tracing/smpi/group
</b>:
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 <b>\c
+@li <b>@c
tracing/smpi/computing
</b>:
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 <b>\c
+@li <b>@c
tracing/smpi/internals
</b>:
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 <b>\c
+@li <b>@c
tracing/smpi/display-sizes
</b>:
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 <b>\c
+@li <b>@c
tracing/smpi/sleeping
</b>:
TODO
-\verbatim
+@verbatim
TODO
-\endverbatim
+@endverbatim
-\li <b>\c
+@li <b>@c
tracing/smpi/format
</b>:
TODO
-\verbatim
+@verbatim
TODO
-\endverbatim
+@endverbatim
-\li <b>\c
+@li <b>@c
tracing/smpi/format/ti-one-file
</b>:
TODO
-\verbatim
+@verbatim
TODO
-\endverbatim
+@endverbatim
-\li <b>\c
+@li <b>@c
tracing/vm
</b>:
TODO
-\verbatim
+@verbatim
TODO
-\endverbatim
+@endverbatim
-\li <b>\c
+@li <b>@c
tracing/msg/process
</b>:
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 <b>\c
+@li <b>@c
tracing/buffer
</b>:
This option put some events in a time-ordered buffer using the
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 <b>\c
+@li <b>@c
tracing/onelink-only
</b>:
This option changes the way SimGrid register its platform on the trace
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 <b>\c
+@li <b>@c
tracing/disable-link
</b>:
TODO
-\verbatim
+@verbatim
TODO
-\endverbatim
+@endverbatim
-\li <b>\c
+@li <b>@c
tracing/disable-power
</b>:
TODO
-\verbatim
+@verbatim
TODO
-\endverbatim
+@endverbatim
-\li <b>\c
+@li <b>@c
tracing/disable-destroy
</b>:
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 <b>\c
+@li <b>@c
tracing/basic
</b>:
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 <b>\c
+@li <b>@c
tracing/comment
</b>:
Use this to add a comment line to the top of the trace file.
-\verbatim
+@verbatim
--cfg=tracing/comment:my_string
-\endverbatim
+@endverbatim
-\li <b>\c
+@li <b>@c
tracing/comment-file
</b>:
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 <b>\c
+@li <b>@c
tracing/precision
</b>:
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 <b>\c
+@li <b>@c
tracing/platform
</b>:
TODO
-\verbatim
+@verbatim
TODO
-\endverbatim
+@endverbatim
-\li <b>\c
+@li <b>@c
tracing/platform/topology
</b>:
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 <b>does not</b> use
the tracing API. For that, you can run a uncategorized trace
with the following parameters (it will work with <b>any</b> 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
<b>TRACE_category (...)</b> function (as explained above),
and then classify your tasks to a previously declared category
using the <b>MSG_task_set_category (...)</b>
(or <b>SD_task_set_category (...)</b> 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);
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
-/*! \page platform Describing the virtual platform
+/*! @page platform Describing the virtual platform
@tableofcontents
-\htmlonly
+@htmlonly
<div align="center">
-\endhtmlonly
-\htmlinclude graphical-toc.svg
-\htmlonly
+@endhtmlonly
+@htmlinclude graphical-toc.svg
+@htmlonly
</div>
<script>
document.getElementById("VirtualPlatform").style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1;stroke:#000000;stroke-width:0.35277778;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1";
</script>
-\endhtmlonly
+@endhtmlonly
As @ref starting_components "explained in the introduction," any
SimGrid study must entail the description of the platform on which you
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)
The current version is <b>4.1</b>. 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}
<?xml version='1.0'?>
<!DOCTYPE platform SYSTEM "http://simgrid.gforge.inria.fr/simgrid/simgrid.dtd">
<platform version="4.1">
</route>
</zone>
</platform>
-\endcode
+@endcode
As we said, the englobing @ref pf_overview "<platform>" tag is
used to specify the dtd version used for this file.
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.
#### Examples ####
-\code{.xml}
+@code{.xml}
<host id="host1" speed="1000000000"/>
<host id="host2" speed="1000000000">
<prop id="color" value="blue"/>
<prop id="rendershape" value="square"/>
</host>
-\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 ``\<host\>`` tag
+time, using the ``availability_file`` attribute to the ``@<host@>`` tag
and a separate text file whose syntax is exemplified below.
#### Adding a trace file ####
-\verbatim
+@verbatim
<platform version="4">
<host id="bob" speed="500Gf" availability_file="bob.trace" />
</platform>
-\endverbatim
+@endverbatim
#### Example of "bob.trace" file ####
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 ``\<host\>`` tag). (Clearly, the
+to the maximum performance specified in the ``@<host@>`` 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>
``<cluster />`` represents a machine-cluster. It is most commonly used
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</b>.
The default inner organization of the cluster is as follow:
-\verbatim
+@verbatim
__________
| |
| router |
| | | ........ | | |
| |
c-0.me c-99.me
-\endverbatim
+@endverbatim
Here, a set of <b>host</b>s is defined. Each of them has a <b>link</b>
to a central backbone (backbone is a link itself, as a link can
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.
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 ``\<host\>`` tag.
-core | no | int (default: 1) | Same as the ``core`` attribute of the ``\<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.
+speed | yes | int | Same as the ``speed`` attribute of the ``@<host@>`` tag.
+core | no | int (default: 1) | Same as the ``core`` attribute of the ``@<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 <b>link</b> section for syntax/details.
sharing_policy | no | string | Sharing policy for the links between nodes and backbone (if any). See <b>link</b> section for syntax/details.
bb_bw | no | int | Bandwidth for backbone (if any). See <b>link</b> section for syntax/details. If bb_bw and bb_lat (see below) attributes are omitted, no backbone is created (alternative cluster architecture <b>described before</b>).
bb_lat | no | int | Latency for backbone (if any). See <b>link</b> section for syntax/details. If bb_lat and bb_bw (see above) attributes are omitted, no backbone is created (alternative cluster architecture <b>described before</b>).
bb_sharing_policy | no | string | Sharing policy for the backbone (if any). See <b>link</b> 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 <a href="https://hal.inria.fr/hal-00919507/"> "Toward Better Simulation of MPI Applications on Ethernet/TCP Networks"</a>
-loopback_bw | no | int | Bandwidth for loopback (if any). See <b>link</b> 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 <b>link</b> 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 <b>link</b> 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), <a href="http://en.wikipedia.org/wiki/Torus_interconnect">TORUS </a>, 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), <a href="http://en.wikipedia.org/wiki/Torus_interconnect">TORUS </a>, 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
Consider the following two (and independent) uses of the ``cluster`` tag:
-\verbatim
+@verbatim
<cluster id="my_cluster_1" prefix="" suffix="" radical="0-262144"
speed="1e9" bw="125e6" lat="5E-5"/>
<cluster id="my_cluster_2" prefix="c-" suffix=".me" radical="0-99"
speed="1e9" bw="125e6" lat="5E-5"
bb_bw="2.25e9" bb_lat="5E-4"/>
-\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
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
<zone id="my_cluster1" routing="Cluster">
<cabinet id="cabinet1" prefix="host-" suffix=".cluster1"
speed="1Gf" bw="125MBps" lat="100us" radical="1-10"/>
<backbone id="backbone1" bandwidth="2.25GBps" latency="500us"/>
</zone>
-\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.
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 ####
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 <b>link</b> description for details.
+sharing_policy | no | SHARED@|SPLITDUPLEX (default: SPLITDUPLEX) | Sharing policy for links. See <b>link</b> description for details.
availability_file| no | string | Availability file for the peer. Same as host availability file. See <b>host</b> description for details.
state_file | no | string | State file for the peer. Same as host state file. See <b>host</b> description for details.
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. ``<link>``: 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
3. ``<backbone/>``: 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 ``<link>`` (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, <b>router</b> is used only to give some information
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
<router id="gw_dc1_horizdist"/>
-\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
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.
notation or by using common abbreviations. For instance, the following three tags
are equivalent:
-\verbatim
+@verbatim
<link id="LINK1" bandwidth="125000000" latency="5E-6"/>
<link id="LINK1" bandwidth="125000000" latency="5us"/>
<link id="LINK1" bandwidth="125000000" latency="0.000005"/>
-\endverbatim
+@endverbatim
Here, the second tag uses "us", meaning "microseconds". Other shortcuts are:
#### 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!
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 ``<link>`` 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.
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
<link id="SWITCH" bandwidth="125000000" latency="5E-5" sharing_policy="FATPIPE" />
-\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
<link id="LINK1" state_file="link1.fail" bandwidth="80000000" latency=".0001" bandwidth_file="link1.bw" latency_file="link1.lat" />
-\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
#### The ``<prop/>`` tag ####
Similar to the ``<host>`` tag, a link may also contain the ``<prop/>`` 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 <backbone/>
+@subsubsection pf_backbone <backbone/>
-\note
+@note
This tag is <b>only available</b> when the containing network zone uses the "Cluster" routing mode!
Using this tag, you can designate an already existing link to be a backbone.
--------------- | --------- | ------ | -----------
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
@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
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
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
/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
-#### \<storage_type\> ####
+@anchor pf_storage_entity_storage_type
+#### @<storage_type@> ####
Attribute name | Mandatory | Values | Description
--------------- | --------- | ------ | -----------
id | yes | string | Identifier of this storage_type; used when referring to it
model | no | string | In the future, this will allow 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:
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 <b><prop></b> tag. The <prop> tag allows you
to associate additional information to this <storage_type> and follows the
attribute/value schema; see the example below. You may want to use it to give information to
the tool you use for rendering your simulation, for example.
Here is a complete example for the ``storage_type`` tag:
-\verbatim
+@verbatim
<storage_type id="single_HDD" size="4000">
<model_prop id="Bwrite" value="30MBps" />
<model_prop id="Bread" value="100MBps" />
<prop id="Brand" value="Western Digital" />
</storage_type>
-\endverbatim
+@endverbatim
@subsubsection pf_tag_storage <storage>
Attributes | Mandatory | Values | Description
-------------- | --------- | ------ | -----------
id | yes | string | Identifier of this ``storage``; used when referring to it
-typeId | yes | string | Here you need to refer to an already existing \ref pf_storage_entity_storage_type "\<storage_type\>"; the storage entity defined by this tag will then inherit the properties defined there.
-attach | yes | string | Name of a host (see Section \ref pf_tag_host) to which this storage is <i>physically</i> attached to (e.g., a hard drive in a computer)
-content | no | string | When specified, overwrites the content attribute of \ref pf_storage_entity_storage_type "\<storage_type\>"
+typeId | yes | string | Here you need to refer to an already existing @ref pf_storage_entity_storage_type "@<storage_type@>"; the storage entity defined by this tag will then inherit the properties defined there.
+attach | yes | string | Name of a host (see Section @ref pf_tag_host) to which this storage is <i>physically</i> attached to (e.g., a hard drive in a computer)
+content | no | string | When specified, overwrites the content attribute of @ref pf_storage_entity_storage_type "@<storage_type@>"
Here are two examples:
-\verbatim
+@verbatim
<storage id="Disk1" typeId="single_HDD" attach="bob" />
<storage id="Disk2" typeId="single_SSD"
content="content/win_storage_content.txt" />
-\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 "\<storage_type\>" above) and attached
+of type "single_HDD" (shown as an example of @ref pf_storage_entity_storage_type "@<storage_type@>" above) and attached
to a host called "bob" (the definition of this host is omitted here).
The second storage is called "Disk2", is still of the same type as Disk1 but
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
<storage_type id="single_SSD" size="500GiB">
<model_prop id="Bwrite" value="60MBps" />
<model_prop id="Bread" value="200MBps" />
<mount storageId="Disk2" name="c:"/>
<mount storageId="Disk4" name="/home"/>
</host>
-\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.
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)
###### 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:
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,
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
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
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.
<b>Example:</b>
-\code
+@code
<zone id="zone0" routing="Full">
<host id="host1" speed="1000000000"/>
<host id="host2" speed="1000000000"/>
<link id="link1" bandwidth="125000000" latency="0.000100"/>
<route src="host1" dst="host2"><link_ctn id="link1"/></route>
</zone>
-\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
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
<zone id="zone0" routing="Floyd">
<cluster id="my_cluster_1" prefix="c-" suffix=""
</zoneroute>
</zone>
-\endverbatim
+@endverbatim
zoneroute given at the end gives a topological information: link1 is
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 ####
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
<zone id="zone_2" routing="Dijkstra">
<host id="zone_2_host1" speed="1000000000"/>
<host id="zone_2_host2" speed="1000000000"/>
<route src="central_router" dst="zone_2_host3"><link_ctn id="zone_2_link3"/></route>
<route src="central_router" dst="zone_2_gateway"><link_ctn id="zone_2_link4"/></route>
</zone>
-\endverbatim
+@endverbatim
-\anchor pf_routing_model_dijkstracache
+@anchor pf_routing_model_dijkstracache
### DijkstraCache ###
DijkstraCache example:
-\verbatim
+@verbatim
<zone id="zone_2" routing="DijkstraCache">
<host id="zone_2_host1" speed="1000000000"/>
...
(platform unchanged compared to upper example)
-\endverbatim
+@endverbatim
#### Example platform files ####
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
<zone id="zone0" routing="Full">
<host id="host1" speed="1000000000"/>
<host id="host2" speed="1000000000"/>
<link id="link1" bandwidth="125000000" latency="0.000100"/>
<route src="host1" dst="host2"><link_ctn id="link1"/></route>
</zone>
-\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.
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
<route src="Alice" dst="Bob">
<link_ctn id="link1"/>
<link_ctn id="link2"/>
<link_ctn id="link3"/>
</route>
-\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
<zoneroute src="zone1" dst="zone2"
gw_src="router1" gw_dst="router2">
<link_ctn id="link1"/>
</zoneroute>
-\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
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
<zone id="zone0" routing="Full">
<cluster id="my_cluster_1" prefix="c-" suffix=".me"
radical="0-149" speed="1000000000" bw="125000000" lat="5E-5"
<link_ctn id="backbone"/>
</zoneroute>
</zone>
-\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).
| --------------- | --------- | ---------------------- | ----------- |
| 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
<route src="Tremblay" dst="Bourassa">
<link_ctn id="4"/><link_ctn id="3"/><link_ctn id="2"/><link_ctn id="0"/><link_ctn id="1"/><link_ctn id="6"/><link_ctn id="7"/>
</route>
-\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
<route src="Tremblay" dst="Bourassa">
<link_ctn id="3"/>
</route>
-\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
| 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
<bypasszoneRoute src="my_cluster_1" dst="my_cluster_2"
gw_src="my_cluster_1_router"
gw_dst="my_cluster_2_router">
<link_ctn id="link_tmp"/>
</bypasszoneroute>
-\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
| --------------- | --------- | ---------------------- | ----------- |
| 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
<bypassRoute src="host_1" dst="host_2">
<link_ctn id="link_tmp"/>
</bypassRoute>
-\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
this route will be computed automatically.
As said before, there are mainly 2 tags for routing:
-\li <b>zoneroute</b>: to define routes between two <b>zone</b>
-\li <b>route</b>: to define routes between two <b>host/router</b>
+@li <b>zoneroute</b>: to define routes between two <b>zone</b>
+@li <b>route</b>: to define routes between two <b>host/router</b>
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
then have to define some <b>route</b> to gives some topological
information to SimGrid. Here is a file doing it all:
-\verbatim
+@verbatim
<zone id="zone_Big" routing="Dijkstra">
<zone id="zone_1" routing="Full">
<host id="zone_1_host1" speed="1000000000"/>
<link_ctn id="backbone"/>
</zoneroute>
</zone>
-\endverbatim
+@endverbatim
-\section pf_other Other tags
+@section pf_other Other tags
-The following tags can be used inside a \<platform\> tag even if they are not
+The following tags can be used inside a @<platform@> 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
* **Example**
-\verbatim
+@verbatim
<?xml version='1.0'?>
<!DOCTYPE platform SYSTEM "http://simgrid.gforge.inria.fr/simgrid.dtd">
<platform version="4">
<zone id="zone0" routing="Full">
...
-\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:
#### Example ####
-\code{.xml}
+@code{.xml}
<prop id="Operating System" value="Linux" />
-\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).
#### Example ####
-\verbatim
+@verbatim
<zone id="zone0" routing="Full">
<host id="bob" speed="1000000000"/>
</zone>
<trace id="myTrace" file="bob.trace" periodicity="1.0"/>
<trace_connect trace="myTrace" element="bob" kind="POWER"/>
-\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
<trace id="myTrace" periodicity="1.0">
0.0 1.0
11.0 0.5
20.0 0.8
</trace>
-\endverbatim
+@endverbatim
-#### \c trace_connect attributes ####
+#### @c trace_connect attributes ####
| Attribute name | Mandatory | Values | Description |
| --------------- | --------- | ---------------------- | ----------- |
-| kind | no | HOST_AVAIL\|POWER\|<br/>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@|<br/>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
./two_hosts.xml:17: <trace_connect trace="Tremblay_power" element="Tremblay" kind="SPEED"/>
@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
update the generated platforms with <tt>bin/simgrid_update_xml</tt> 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
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
<zone id="zone_4" routing="Full">
<zone id="exitzone_4" routing="Full">
<router id="router_4"/>
<link_ctn id="bb_4"/>
</zoneroute>
</zone>
-\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
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
-<b>coordinates</b> of the \<peer\> or \<host\> tag. There's nothing
+<b>coordinates</b> of the @<peer@> or @<host@> tag. There's nothing
complicated in using it, here is an example:
-\verbatim
+@verbatim
<?xml version='1.0'?>
<!DOCTYPE platform SYSTEM "http://simgrid.gforge.inria.fr/simgrid.dtd">
<platform version="4">
<host id="100429957" coordinates="17.5 6.7 18.8" speed="8.3Gf" />
</zone>
</platform>
-\endverbatim
+@endverbatim
Coordinates are then used to calculate latency (in microseconds)
between two hosts by calculating the distance between the two hosts
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
<?xml version='1.0'?>
<!DOCTYPE platform SYSTEM "http://simgrid.gforge.inria.fr/simgrid.dtd">
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 <b>peer</b> 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
disk space. Here is the list of available model and their
characteristics (lookup: time to resolve a route):
-\li <b>Full</b>: Full routing data (fast, large memory requirements,
+@li <b>Full</b>: Full routing data (fast, large memory requirements,
fully expressive)
-\li <b>Floyd</b>: Floyd routing data (slow initialization, fast
+@li <b>Floyd</b>: Floyd routing data (slow initialization, fast
lookup, lesser memory requirements, shortest path routing only).
Calculates all routes at once at the beginning.
-\li <b>Dijkstra</b>: Dijkstra routing data (fast initialization, slow
+@li <b>Dijkstra</b>: Dijkstra routing data (fast initialization, slow
lookup, small memory requirements, shortest path routing only).
Calculates a route when necessary.
-\li <b>DijkstraCache</b>: Dijkstra routing data (fast initialization,
+@li <b>DijkstraCache</b>: 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 <b>None</b>: No routing (usable with Constant network only).
+@li <b>None</b>: 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 <b>Vivaldi</b>: Vivaldi routing, so when you want to use coordinates
-\li <b>Cluster</b>: Cluster routing, specific to cluster tag, should
+@li <b>Vivaldi</b>: Vivaldi routing, so when you want to use coordinates
+@li <b>Cluster</b>: 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
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
<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
<route src="A" dst="B">
<link_ctn id="1"/>
</route>
<route src="A" dst="C">
<link_ctn id="3"/>
</route>
-\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
You are also free to declare platform where the routing is not
symmetrical. For example, add the following to the previous file:
-\verbatim
+@verbatim
<route src="C" dst="A">
<link_ctn id="2"/>
<link_ctn id="1"/>
</route>
-\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
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
/*! @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:
}
~~~
-\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
[`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:
- 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:
- `RemotePtr<T>` represents the address of an object of type `T` in some
remote `AddressSpace` (it could be an alias to `Remote<T*>`).
-\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.
uhood_tech once you understant the overall design presented on this
page.
-\htmlonly
+@htmlonly
<center>
-\endhtmlonly
-\htmlinclude simgrid_modules.map
-\htmlonly
+@endhtmlonly
+@htmlinclude simgrid_modules.map
+@htmlonly
<br><b>SimGrid Components (click to jump to API)</b>
</center>
-\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
your work.
- If you want to study a theoretical problem and compare several
- heuristics, you probably want to try <b>\ref MSG_API</b> (yet another
+ heuristics, you probably want to try <b>@ref MSG_API</b> (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 <b>\ref SMPI_API</b> (Simulated
+ you should have a look at the <b>@ref SMPI_API</b> (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
<a href=http://lists.gforge.inria.fr/mailman/listinfo/simgrid-devel>SimGrid
developers mailing list</a>, 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 <b>\ref SURF_API</b>. It is
+module called <b>@ref SURF_API</b>. 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.
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 <b>\ref XBT_API
+The base of the whole toolkit is constituted by the <b>@ref XBT_API
(eXtended Bundle of Tools)</b>.
-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
*/
/*! @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
> large) set of worker machines. What is the best way to organize the
> computations ?
-\htmlonly
+@htmlonly
<div align="center">
-\endhtmlonly
-\htmlinclude tuto-msg/overview.svg
-\htmlonly
+@endhtmlonly
+@htmlinclude tuto-msg/overview.svg
+@htmlonly
</div>
-\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:
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
-\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
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).
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:
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 \<simgrid_root_directory\>/bin/colorize.
+@c /opt/simgrid/bin/simgrid-colorizer. If you did not install it at all,
+you can find it in @<simgrid_root_directory@>/bin/colorize.
For a classical Gantt-Chart visualization, you can produce a [Paje][fn:5] trace:
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.<br>
+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.<br>
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.<br>
+ - @c worker: each workers will execute this function.<br>
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
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
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
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
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
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
./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
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
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
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
- 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
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");
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)
}
/**
- * \brief Node Function
+ * @brief Node Function
* Arguments:
* - my id
* - the id of a guy I know in the system (except for the first node)
return 1;
}
-/** \brief Main function. */
+/** @brief Main function. */
int main(int argc, char *argv[])
{
MSG_init(&argc, argv);
@subsection s4u_ex_actors_start Starting and stoping actors
- <b>Creating actors</b>.
- @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.
- <b>Kill actors</b>.
- @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.
- <b>Controling the actor life cycle from the XML</b>.
@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.
- <b>Daemonize actors</b>
- @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
- <b>Suspend and Resume actors</b>.
- @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.
- <b>Migrating Actors</b>.
- @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.
- <b>Waiting for the termination of an actor</b> (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.
- <b>Yielding to other actor</b>.
- @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.
also the tesh files in the example directories for details.
- <b>Communication replay</b>.
- @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).
- <b>I/O replay</b>.
- @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).
@subsection s4u_ex_activity_comm Communications on the network
- <b>Basic asynchronous communications</b>.
- @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
@ref simgrid::s4u::Comm::wait().
- <b>Waiting for all communications in a set</b>.
- @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.
- <b>Waiting for the first completed communication in a set</b>.
- @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.
@subsection s4u_ex_activity_exec Executions on the CPU
- <b>Basic execution</b>.
- @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
get more resources.
- <b>Asynchronous execution</b>.
- @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.
- <b>Monitoring asynchronous executions</b>.
- @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.
- <b>Remote execution</b>.
- @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.
- <b>Using Pstates on a host</b>
@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.
- <b>Parallel tasks</b>
- @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.
write actions on the storage resources.
- <b>Access to raw storage devices</b>.
- @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.
read and write. The file and disk sizes are also dealt with and can
result in short reads and short write, as in reality.
- - <b>File Management</b>. @ref examples/s4u/io-file-system/s4u-io-file-system.cpp \n
+ - <b>File Management</b>. @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, ...).
- <b>Remote I/O</b>.
- @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
- - <b>Mutex: </b> @ref examples/s4u/mutex/s4u-mutex.cpp \n
+ - <b>Mutex: </b> @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
- <b>Retrieving the list of hosts matching a given criteria</b>.
- @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.
- <b>User-defined properties</b>.
@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
@section s4u_ex_energy Simulating the energy consumption
- <b>Describing the energy profiles in the platform</b>
- @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.
- <b>Consumption due to the CPU</b>
- @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.
- <b>Modeling the shutdown and boot of hosts</b>
@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.
options to see the task executions:
- <b>Platform tracing</b>.
- @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
This section contains application examples that are somewhat larger
than the previous examples.
- - <b>Ping Pong</b>: @ref examples/s4u/app-pingpong/s4u-app-pingpong.cpp\n
+ - <b>Ping Pong</b>: @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).
- - <b>Token ring:</b> @ref examples/s4u/app-token-ring/s4u-app-token-ring.cpp \n
+ - <b>Token ring:</b> @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.
- - <b>Master Workers:</b> @ref examples/s4u/app-masterworker/s4u-app-masterworker.cpp \n
+ - <b>Master Workers:</b> @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
- <b>Bit Torrent</b>
- @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.
- <b>Chained send</b>
- @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)
- <b>Chord Protocol</b>
- @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.
*/
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<double*>(mailbox->get());
xbt_assert(task != nullptr, "mailbox->get() failed");
double comp_size = *task;
* 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)
{
}
/* 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)
/* 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)
{
}
/* 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)
{
/* 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)
{
/* 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)
{
/* 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)
{
/* 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)
{
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();
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);
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);
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);
/**
* @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 */
} // 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<simgrid::kernel::resource::Model*> all_existing_models;
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
*/
/* 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,
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.
~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.
*/
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;
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
/************************** 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
*
* 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);
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<Link> {
friend simgrid::kernel::resource::LinkImpl;
A task is some <em>computing amount</em> 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 <em>\ref e_SD_task_state_t "state"</em> indicating whether the task is scheduled, running, done, ...
+ Each task has a <em>@ref e_SD_task_state_t "state"</em> indicating whether the task is scheduled, running, done, ...
*/
typedef struct s_SD_task_t* SD_task_t;
*
* A task is some <em>working amount</em> 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 <em>\ref e_SD_task_state_t "state"</em> indicating whether the task is scheduled, running, done, ...
+ * Each task has a <em>@ref e_SD_task_state_t "state"</em> indicating whether the task is scheduled, running, done, ...
*
* @see SD_task_t, @see SD_task_dependency_api
* @{
some <em>private data</em> that can be only accessed by local
process.
- \see m_host_management
+ @see m_host_management
@{ */
typedef enum {
SIMIX_WAITING,
/* ******************************** Synchro ************************************ */
-/**
- * \ingroup simix_synchro_management
- */
+/** @ingroup simix_synchro_management */
typedef struct s_smx_sem_t* smx_sem_t;
/* ****************************** Process *********************************** */
* 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
*
* 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 <name>:<min nb>_to_<max nb>_<type>\endverbatim
+ * @verbatim <name>:<min nb>_to_<max nb>_<type>@endverbatim
*
- * For example, <tt>size:1_to_1_int</tt> describes a variable called \e size which must take exactly one value, and
+ * For example, <tt>size:1_to_1_int</tt> 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 <tt>outputfiles:0_to_10_string</tt> which describes a variable called \e outputfiles and
+ * Another example could be <tt>outputfiles:0_to_10_string</tt> 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
*/
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<int>") XBT_PUBLIC
void xbt_cfg_set_int(const char* name, int val);
XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::set_value<double>") XBT_PUBLIC
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<int>") 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();
* 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.
*
* @{
*/
*
* Here is a little example of use:
-\verbatim
+@verbatim
xbt_dict_t mydict = xbt_dict_new_homogeneous(free);
char buff[512];
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
* @{
*/
- /** \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 {
*
* Here is an example (assuming that the dictionary contains strings, i.e., that the <tt>data</tt> 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 !!
*
* @{ */
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;
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)) ; \
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);
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;
* @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.
*
*/
-/** \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
#include <stddef.h> /* NULL */
#include <xbt/misc.h>
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)*/
}
/**
- * \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.
*/
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.
*/
#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).
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).
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.
*/
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.
*/
};
/**
- * \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())
/* ********************** */
/**
- * \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
/** @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, ...) \
/** @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(...) \
* 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).
*
* @{
*/
-/** \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);
#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 */
XBT_PARMAP_DEFAULT /**< futex if available, posix otherwise */
} e_xbt_parmap_mode_t;
-/** \} */
+/** @} */
#endif
/** @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);
/**
* @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.
*
#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)
*
* @{
*/
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);
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);
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);
/** 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();
}
/**
- * \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)
{
/** @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)
{
}
/**
- * \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
}
/**
- * \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
}
/**
- * \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
*/
}
/**
- * \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
}
/**
- * \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
}
/**
- * \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
*/
};
/**
- * \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
};
/**
- * \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)
{
}
/**
- * \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)
{
/* ********************************************************************************* */
/**
- * \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
*/
}
/**
- * \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
*/
/* ********************************************************************************* */
/**
- * \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)
{
}
/**
- * \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)
{
#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.
/*** 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
*/
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();
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 <typename T> class Parmap {
public:
Parmap(unsigned num_workers, e_xbt_parmap_mode_t mode);
enum Flag { PARMAP_WORK, PARMAP_DESTROY };
/**
- * \brief Thread data transmission structure
+ * @brief Thread data transmission structure
*/
class ThreadData {
public:
};
/**
- * \brief Synchronization object (different specializations).
+ * @brief Synchronization object (different specializations).
*/
class Synchro {
public:
explicit Synchro(Parmap<T>& 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;
};
/**
- * \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 <typename T> Parmap<T>::Parmap(unsigned num_workers, e_xbt_parmap_mode_t mode)
{
}
/**
- * \brief Destroys a parmap
+ * @brief Destroys a parmap
*/
template <typename T> Parmap<T>::~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 <typename T> void Parmap<T>::apply(void (*fun)(T), const std::vector<T>& data)
{
}
/**
- * \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 <typename T> boost::optional<T> Parmap<T>::next()
{
}
/**
- * \brief Main work loop: applies fun to elements in turn.
+ * @brief Main work loop: applies fun to elements in turn.
*/
template <typename T> void Parmap<T>::work()
{
/**
* Get a synchronization object for given mode.
- * \param mode the synchronization mode
+ * @param mode the synchronization mode
*/
template <typename T> typename Parmap<T>::Synchro* Parmap<T>::new_synchro(e_xbt_parmap_mode_t mode)
{
}
/**
- * \brief Main function of a worker thread.
+ * @brief Main function of a worker thread.
*/
template <typename T> void* Parmap<T>::worker_main(void* arg)
{
}
}
-/** \} */
+/** @} */
}
}
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,
* 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)
{
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 ()
{
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)
{
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
* 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)
{
}
}
-/** \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)
{
}
/**
- * \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)
{
}
}
-/** \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 ()
{
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)
{
*/
/* 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)
{
}
/* 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 ()
{
}
/* 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)
{
}
/* 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)
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)
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)
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)
{
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 ()
{
}
/**
- * \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)
{
}
/**
- * \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)
{
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.
}
/**
- * \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.
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)
{
/** 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)
{
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) {
/*
* 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
*
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.
*/
/* 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)
{
}
/*
- * 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)
{
}
/* 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
*/
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.
// 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)
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.
}
}
-/** \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<simgrid::mc::VisitedState> VisitedStates::addVisitedState(
unsigned long state_number, simgrid::mc::State* graph_state, bool compare_snpashots)
{
}
/**
- * \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<VisitedPair> visited_pair, simgrid::mc::Pair* pair)
{
-/* 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. */
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.
*
* 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);
}
}
-/** \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)
}
}
-/** \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)
// ***** 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)
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)
}
}
-/** \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)
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)
{
// ***** 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)
}
-/** \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)
}
}
-/** \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,
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.
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
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<simgrid::mc::ObjectInformation> createObjectInformation(
std::vector<simgrid::xbt::VmMap> const& maps, const char *name)
{
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)
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)
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<simgrid::xbt::VmMap> const& maps, simgrid::mc::ObjectInformation* result)
/************************************* 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)
{
/********************************* 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) {
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");
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);
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)
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)
{
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.
*/
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.
*/
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.
*/
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.
*/
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)
{
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.
*/
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)
{
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.
* <a href="http://lists.gforge.inria.fr/pipermail/simgrid-user/2011-November/002649.html">this thread</a>
* 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)
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.
* 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)
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)
{
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.
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
*/
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)
{
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)
}
/**
- * \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) {
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)
{
}
/**
- * \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)
{
}
}
-/** \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)
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.
* 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)
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)
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.
*
* 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)
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)
return MSG_process_get_PID(static_cast<msg_task_t>(comm->src_buff)->simdata->sender);
}
-/** \ingroup msg_task_usage
- * \brief Sets the tracing category of a task.
+/** @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)
{
/******************************** 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)
{
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,
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)
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)
{
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)
{
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)
{
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.
*/
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.
*/
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.
*/
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.
*/
}
/********************************* 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)
{
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)
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)) {
}
}
-/** \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
*/
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
*/
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
*/
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
*/
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.
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)
{
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.
}
}
-/** \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
*
}
}
-/** \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.
*/
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.
*/
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)
{
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)
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().
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)
{
}
/**
- * \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 \<stdio.h\> 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)
*/
}
/**
- * \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)
{
}
/**
- * \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)
{
/* **************************** 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()
{
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}
<host id="HostA" power="100.0Mf" cores="4">
<prop id="watt_per_state" value="100.0:120.0:200.0" />
<prop id="watt_off" value="10" />
</host>
-\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:
<table>
-<tr><th>\#Cores loaded</th><th>Consumption</th><th>Explanation</th></tr>
+<tr><th>@#Cores loaded</th><th>Consumption</th><th>Explanation</th></tr>
<tr><td>0</td><td> 100 Watts</td><td>Idle value</td></tr>
<tr><td>1</td><td> 120 Watts</td><td>OneCore value</td></tr>
<tr><td>2</td><td> 147 Watts</td><td>linear extrapolation between OneCore and AllCores</td></tr>
### 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}
<host id="HostC" power="100.0Mf" cores="1">
<prop id="watt_per_state" value="95.0:200.0" /> <!-- we may have used '95:200:200' instead -->
<prop id="watt_off" value="10" />
</host>
-\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}
<host id="HostC" power="100.0Mf,50.0Mf,20.0Mf" cores="4">
<prop id="watt_per_state" value="95.0:120.0:200.0, 93.0:115.0:170.0, 90.0:110.0:150.0" />
<prop id="watt_off" value="10" />
</host>
-\endcode
+@endcode
This encodes the following values
<table>
/* **************************** 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()
{
{
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();
/* **************************** 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()
{
The energy consumption of a link depends directly on its current traffic load. Specify that consumption in your
platform file as follows:
- \verbatim
+ @verbatim
<link id="SWITCH1" bandwidth="125Mbps" latency="5us" sharing_policy="SHARED" >
<prop id="watt_range" value="100.0:200.0" />
<prop id="watt_off" value="10" />
</link>
- \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.
{
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()
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);
/* **************************** 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)
{
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)
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)
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)
{
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
*/
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.
*/
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.
*/
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.
*/
}
/**
- * \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)
{
}
/**
- * \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)
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)
{
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)
{
}
/**
- * \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.
*/
}
/**
- * \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.
}
/**
- * \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<const char*> Host::get_attached_storages() const
{
*
* 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()
{
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)
{
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.
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.
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);
}
/**
- * \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)
{
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)
{
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)
{
}
}
-/** \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)
{
} // 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)
{
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)
{
* (#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.
*/
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)
{
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()
{
}
/**
- * \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] =
}
/**
- * \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)
{
}
}
-/** \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.
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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()
{
}
/**
- * \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)
{
*
* 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)
{
*
* 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)
{
* 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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
/** @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)
/** @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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
* 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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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.
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
}
/**
- * \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)
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
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()
{
}
/**
- * \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) {
}
/**
- * \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)
{
}
/**
- * \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<std::string, std::string>* properties, smx_actor_t parent_process)
}
/**
- * \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
}
/**
- * \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) {
}
/**
- * \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)
{
}
/**
- * \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)
{
/** @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<std::string, std::string>* properties)
#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)
}
/**
- * \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)
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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*),
}
/**
- * \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,
}
/**
- * \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*),
}
}
/**
- * \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*),
}
/**
- * \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)
}
/**
- * \ingroup simix_comm_management
+ * @ingroup simix_comm_management
*/
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)
{
}
/**
- * \ingroup simix_comm_management
+ * @ingroup simix_comm_management
*/
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)
{
}
/**
- * \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)
{
}
/**
- * \ingroup simix_comm_management
+ * @ingroup simix_comm_management
*
*/
int simcall_comm_test(smx_activity_t comm)
}
/**
- * \ingroup simix_synchro_management
+ * @ingroup simix_synchro_management
*
*/
smx_mutex_t simcall_mutex_init()
}
/**
- * \ingroup simix_synchro_management
+ * @ingroup simix_synchro_management
*
*/
void simcall_mutex_lock(smx_mutex_t mutex)
}
/**
- * \ingroup simix_synchro_management
+ * @ingroup simix_synchro_management
*
*/
int simcall_mutex_trylock(smx_mutex_t mutex)
}
/**
- * \ingroup simix_synchro_management
+ * @ingroup simix_synchro_management
*
*/
void simcall_mutex_unlock(smx_mutex_t mutex)
}
/**
- * \ingroup simix_synchro_management
+ * @ingroup simix_synchro_management
*
*/
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)
}
/**
- * \ingroup simix_synchro_management
+ * @ingroup simix_synchro_management
*
*/
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)
}
/**
- * \ingroup simix_synchro_management
+ * @ingroup simix_synchro_management
*
*/
int simcall_sem_acquire_timeout(smx_sem_t sem, double timeout)
};
/**
- * \brief Represents a simcall to the kernel.
+ * @brief Represents a simcall to the kernel.
*/
struct s_smx_simcall {
e_smx_simcall_t call;
/**
* @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) {
}
/**
- * \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() {
}
/**
- * \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) {
}
/**
- * \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()
{
}
/**
- * \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)
{
}
/**
- * \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)
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
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)
/********************************* 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)
}
/**
- * \ingroup SIMIX_API
- * \brief Initialize SIMIX internal data.
+ * @ingroup SIMIX_API
+ * @brief Initialize SIMIX internal data.
*/
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
*/
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()
{
}
/**
- * \ingroup SIMIX_API
- * \brief Run the main simulation loop.
+ * @ingroup SIMIX_API
+ * @brief Run the main simulation loop.
*/
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)
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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
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<smx_activity_t>* deque, e_smx_comm_type_t type,
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
#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); \
}
/**
- * \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()
{
static std::map<std::string, Instance> 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)
{
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)
{
}
/**
- * \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()
{
}
/**
- * \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()
{
}
/**
- * \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)
{
}
/**
- * \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());
};
/**
- * \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.
*/
}
}
-/** \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()
}
/**
-* \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)) {
}
/**
- * \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)
{
}
/**
-* \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 */
}
/**
- * \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);
}
/**
-* \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_;
}
/**
- * \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)
{
}
/**
- * \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);
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<double> 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<bool> NetworkModel::cfg_crosstraffic(
"network/crosstraffic",
"Activate the interferences between uploads and downloads for fluid max-min models (LV08, CM02)", "yes");
************/
/** @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:
**********/
/** @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:
}
}
} // 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;
}
/**
- * \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.
}
/**
- * \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.
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<sg_host_t> 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.
*/
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) ) ).
*
*/
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) ) ).
*
*/
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.
*
*/
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
*/
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
*/
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;
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();
/* 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 <cstdio>
-#include <cstring>
-
#include "xbt/dict.h"
#include "xbt/ex.h"
#include <xbt/ex.hpp>
#include "xbt/str.h"
#include "dict_private.h"
+#include <cstdio>
+#include <cstring>
+
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.
}
/**
- * \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
*/
}
/**
- * \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)
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
}
/**
- * \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)
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
}
-/** \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;
/** @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 **).
/** @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)
/** @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)
{
/** @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)
{
}
/**
- * \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)
{
/** @brief Destructor
*
- * \param dynar poor victim
+ * @param dynar poor victim
*
* kilkil a dynar and its content
*/
}
}
-/** \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;
/** @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)
{
/** @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)
{
/** @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)
/** @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().
*/
/** @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().
* 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))) {
* 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.
* }
* @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)
{
/** @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.
*/
/** @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
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) {
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.
*/
}
/**
- * \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:
* - 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)
{
};
/**
- * \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).
*/
/* 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. */
}
/**
- * \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)
{
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)
{
}
/**
- * \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().
*
* 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)
{
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)
{
}
/*
- * \brief Offset computation
- * \arg var a variable of type <tt>struct</tt> something
- * \arg field a field of <tt>struct</tt> something
- * \return the offset of \a field in <tt>struct</tt> something.
+ * @brief Offset computation
+ * @arg var a variable of type <tt>struct</tt> something
+ * @arg field a field of <tt>struct</tt> something
+ * @return the offset of @a field in <tt>struct</tt> something.
* @hideinitializer
*
* It is very similar to offsetof except that is done at runtime and that you have to declare a variable. Why defining
/* @} */
/* 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);
*/
}
/*
- * \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)
{
}
/*
- * \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)
{
}
/*
- * \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)
{
/* 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
-/* 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. */
}
/**
- * \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[])
{
}
/**
- * \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)
{
}
/**
- * \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.
*/
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)
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)
