About 2441 useless spaces at end of lines removed, mainly in doc/.
* Simgrid is now built as a dll.
* Simgrid-java now works on Windows.
* Simgrid-Java is now included into Windows package.
-
+
MacOS:
* First pre-build package for MacOSX.
-
+
Build System:
* Fix compilation when using MSG_USE_DEPRECATED.
* Fix some compilation issues on Macs and Windows.
you can run your code both in the simulator and on a real platform. For this,
there are two implementations of the GRAS interface, one for simulation, and one
for real execution. So, you just have to relink your code to choose one of
-both worlds.
+both worlds.
\subsection faq_visualization Visualizing and analyzing the results
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
+filter (e.g. with bash):
+\verbatim
./msg_test small_platform.xml small_deployment.xml 2>&1 | ../../tools/MSG_visualization/colorize.pl
\endverbatim
\subsection faq_C Argh! Do I really have to code in C?
-Currently bindings on top of MSG are supported for Java, Ruby and Lua. You can find a few
+Currently bindings on top of MSG are supported for Java, Ruby and Lua. You can find a few
documentation about them on the doc page. Note that bindings are released separately from the main dist
and so have their own version numbers.
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
-examples.
+examples.
Of course they have often been needing more complex functions like
MSG_process_suspend(), MSG_process_resume() and
\subsubsection faq_MIA_asynchronous I want to do asynchronous communications in MSG
-In the past (version <= 3.4), there was no function to perform asynchronous communications.
-It could easily be implemented by creating new process when needed though. Since version 3.5,
+In the past (version <= 3.4), there was no function to perform asynchronous communications.
+It could easily be implemented by creating new process when needed though. Since version 3.5,
we have introduced the following functions:
- MSG_task_isend()
- MSG_task_irecv()
- MSG_comm_waitany()
- MSG_comm_destroy()
-We refer you to the description of these functions for more details on their usage as well
+We refer you to the description of these functions for more details on their usage as well
as to the example section on \ref MSG_ex_asynchronous_communications.
\subsubsection faq_MIA_thread_synchronization I need to synchronize my MSG processes
-You obviously cannot use pthread_mutexes of pthread_conds since we handle every
-scheduling related decision within SimGrid.
+You obviously cannot use pthread_mutexes of pthread_conds since we handle every
+scheduling related decision within SimGrid.
In the past (version <=3.3.4) you could do it by playing with
MSG_process_suspend() and MSG_process_resume() or with fake communications (using MSG_task_get(),
the same within MSG, as in next code snippet. It is very close from what you
would have to do out of the simulator, and thus gives you information that
you could also get in real settings to not hinder the realism of your
-simulation.
+simulation.
\verbatim
double get_host_load() {
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
\verbatim
int sender()
{
- m_task_t task = MSG_task_create("Task", task_comp_size, task_comm_size,
+ m_task_t task = MSG_task_create("Task", task_comp_size, task_comm_size,
calloc(1,sizeof(double)));
*((double*) task->data) = MSG_get_clock();
MSG_task_put(task, slaves[i % slaves_count], PORT_22);
}
}
\endverbatim
-
+
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.
switch manually to the pthread version, and provide us with a good
patch for the configure script so that it is done automatically ;)
- - <b>Hundred thousands of simulated processes</b> (hard-core tricks)\n
+ - <b>Hundred thousands of simulated processes</b> (hard-core tricks)\n
As explained above, SimGrid can use UNIX98 contexts to represent
and handle the simulated processes. Thanks to this, the main
limitation to the number of simulated processes becomes the
quite hairy, the default value is a bit overestimated so that
user doesn't get into trouble about this. You want to tune this
size to increase the number of processes. This is the
- <tt>STACK_SIZE</tt> define in
+ <tt>STACK_SIZE</tt> define in
<tt>src/xbt/xbt_context_sysv.c</tt>, which is 128kb by default.
Reduce this as much as you can, but be warned that if this value
is too low, you'll get a segfault. The token ring example, which
- is quite simple, runs with 40kb stacks.
+ is quite simple, runs with 40kb stacks.
- You may tweak the logs to reduce the stack size further. When
logging something, we try to build the string to display in a
char array on the stack. The size of this array is constant (and
sized buffer. In which case, we have to traverse one time the log
event arguments to compute the size we need for the buffer,
malloc it, and traverse the argument list again to do the actual
- job.\n
+ job.\n
The idea here is to move XBT_LOG_BUFF_SIZE to 1, forcing the logs
to use a dynamic array each time. This allows us to lower further
the stack size at the price of some performance loss...\n
\subsubsection faq_MIA_checkpointing I need a checkpointing thing
Actually, it depends on whether you want to checkpoint the simulation, or to
-simulate checkpoints.
+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
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
-don't have much at hand right now.
+don't have much at hand right now.
You should refer to the Platform Description Archive
(http://pda.gforge.inria.fr) project to see the other platform file we
http://cdash.inria.fr/CDash/index.php?project=Simgrid (click on
previous if there is no result for today: results are produced only by
11am, French time) and
-https://buildd.debian.org/status/logs.php?pkg=simgrid if you don't believe us.
+https://buildd.debian.org/status/logs.php?pkg=simgrid if you don't believe us.
If it's failing on your machine in a way not experienced by the
autobuilders above, please drop us a mail on the mailing list so that
This indicates that one of the library SimGrid depends on (libpthread
here) was missing on the linking command line. Dependencies of
libsimgrid are expressed directly in the dynamic library, so it's
-quite impossible that you see this message when doing dynamic linking.
+quite impossible that you see this message when doing dynamic linking.
If you compile your code statically (and if you use a pthread version
of SimGrid -- see \ref faq_more_processes), you must absolutely
\subsubsection faq_trouble_lib_msg_deprecated "gcc: undefined reference to MSG_*"
-Since version 3.7 all the m_channel_t mecanism is deprecated. So functions
+Since version 3.7 all the m_channel_t mecanism is deprecated. So functions
about this mecanism may get removed in future releases.
List of functions:
\subsubsection faq_flexml_limit "surf_parse_lex: Assertion `next limit' failed."
-This is because your platform file is too big for the parser.
+This is because your platform file is too big for the parser.
Actually, the message comes directly from FleXML, the technology on top of
which the parser is built. FleXML has the bad idea of fetching the whole
was done by William Dowling, who use it in his own work. The good point is
that it now use a dynamic buffer, and that the memory usage was greatly
improved. The downside is that William also changed some things internally,
-and it breaks the hack we devised to bypass the parser, as explained in
+and it breaks the hack we devised to bypass the parser, as explained in
\ref pf_flexml_bypassing. Indeed, this is not a classical usage of the
parser, and Will didn't imagine that we may have used (and even documented)
such a crude usage of FleXML. So, we now have to repair the bypassing
- <b>Transport endpoint is not connected</b>: several processes try to open
a server socket on the same port number of the same machine. This is
naturally bad and each process should pick its own port number for this.\n
- Maybe, you just have some processes remaining from a previous experiment
+ Maybe, you just have some processes remaining from a previous experiment
on your machine.\n
Killing them may help, but again if you kill -KILL them, you'll have to
wait for a while: they didn't close there sockets properly and the system
- <b>Socket closed by remote side</b>: if the remote process is not
supposed to close the socket at this point, it may be dead.
-
+
- <b>Connection reset by peer</b>: I found this on Internet about this
- error. I think it's what's happening here, too:\n
+ error. I think it's what's happening here, too:\n
<i>This basically means that a network error occurred while the client was
receiving data from the server. But what is really happening is that the
server actually accepts the connection, processes the request, and sends
\endverbatim
In more complex situations, this min is the solution of a complex
-max-min linear system. Have a look
+max-min linear system. Have a look
<a href="http://lists.gforge.inria.fr/pipermail/simgrid-devel/2006-April/thread.html">here</a>
and read the two threads "Bug in SURF?" and "Surf bug not
fixed?". You'll have a few other examples of such computations. You
also decide to open a formal bug report using the
<a href="https://gforge.inria.fr/tracker/?atid=165&group_id=12&func=browse">relevant
interface</a>. You need to login on the server to get the ability to submit
-bugs.
+bugs.
We will do our best to solve any problem repported, but you need to help us
finding the issue. Just telling "it segfault" isn't enough. Telling "It
environment as distributed in Debian.
After that, you can run all make targets from both directories, and test
-easily that what you change for one arch does not break the other one.
+easily that what you change for one arch does not break the other one.
It is possible that this VPATH build thing breaks from time to time in the
SVN since it's quite fragile, but it's granted to work in any released
-version. If you experience problems, drop us a mail.
+version. If you experience problems, drop us a mail.
Another possible source of issue is that at the moment, building the
examples request to use the gras_stub_generator tool, which is a compiled
wine for example, which is not really pleasant. We are working on this, but
in the meanwhile, simply don't build the examples in cross-compilation
(<tt>cd src</tt> before running make).
-
+
Program (cross-)compiled with mingw32 do request an extra DLL at run-time to be
usable. For example, if you want to test your build with wine, you should do
the following to put this library where wine looks for DLLs.
-\verbatim
+\verbatim
cp /usr/share/doc/mingw32-runtime/mingwm10.dll.gz ~/.wine/c/windows/system/
gunzip ~/.wine/c/windows/system/mingwm10.dll.gz
\endverbatim
The DLL is built in src/.libs, and installed in the <i>prefix</i>/bin directory
-when you run make install.
+when you run make install.
-If you want to use it in a native project on windows, you need to use
+If you want to use it in a native project on windows, you need to use
simgrid.dll and mingwm10.dll. For each DLL, you need to build .def file
under linux (listing the defined symbols), and convert it into a .lib file
under windows (specifying this in a way that windows compilers like). To
- Coding functions coresponding to each process
- loading the platforme/deployment XML file that describe the environment of simulation
- and … Running the Simulation.
-
+
\dontinclude lua/masterslave/master.lua
\subsection bindings_binding_lua_example_master_slave Master/Slave Example
\li Master Code
\until end_of_master
-we mainly use simgrid.Task.new(task_name,computation_size,communication_size) to create our MSG Task,
+we mainly use simgrid.Task.new(task_name,computation_size,communication_size) to create our MSG Task,
then simgrid.Task.send(task,alias) to send it.
-we use also simgrid.Task.name(task), to get the task's name.
+we use also simgrid.Task.name(task), to get the task's name.
\dontinclude lua/masterslave/slave.lua
\li Slave Code
so you can exchange any kind of data (tables, matrix, strings,…) between process via tasks.
\li Sender process
-\verbatim
+\verbatim
task = simgrid.Task.new("data_task",task_comp,task_comm);
task['matrix'] = my_matrix;
task['table'] = my_table;
\endverbatim
Note that in lua, both sender and receiver share the same lua task.
So that the receiver could joint data directly on the received task without sending it back.
- You can find a complet example (matrix multiplication case) in the file example/lua/mult_matrix.lua.
+ You can find a complet example (matrix multiplication case) in the file example/lua/mult_matrix.lua.
\subsection bindings_binding_lua_example_bypass Bypass XML
and describe your platform directly from the code, with lua bindings it's Possible !! how ?
We provide some additional (tricky?) functions in lua that allows you to set up your own platform without using the XML files
( this can be useful for large platforms, so a simple for loop will avoid you to deal with an annoying XML File ;) )
-
+
\li set Routing mode
\verbatim
...
\endverbatim
for each host you have to specify which route to choose to access to the rest of hosts connected in the grid.
-
+
\li Save platform
\verbatim
simgrid.register_platform();
simgrid.Host.setFunction("Fafard","Slave",1,{"2"});
simgrid.Host.setFunction("Ginette","Slave",1,{"3"});
\endverbatim
- you don't need to use a deployment XML file, thanks to simgrid.Host.setFunction(host_id,function,args_number,args_list)
+ you don't need to use a deployment XML file, thanks to simgrid.Host.setFunction(host_id,function,args_number,args_list)
you can associate functions for each host with arguments if needed .
\li
/** @defgroup GRAS_howto_design HOWTO design a GRAS application
- @ingroup GRAS_howto HOWTOs
+ @ingroup GRAS_howto HOWTOs
This page tries to give some hints on how to design a GRAS application. The
provided model and functionnalities are somehow different from the other
\section GRAS_howto_design_what What is a GRAS application
As explained in \ref GRAS_tut_intro, you should see a GRAS application as a
-distributed service. There is two main parts:
+distributed service. There is two main parts:
- a user API, composed of regular functions offering services to the users
- a set of nodes (or processes, or agents, name them as you want)
collaborating and exchanging messages to achieve the requested service on
Note that we are not speaking about the amount of processes in your
application, but rather on the type of processes. The amount of distinct
-roles.
+roles.
Depending on your application, there may be only one type (for example in a
peer-to-peer system), two types of processes (for example in a client/server
include in the message. The message type is a qualitative information
"someone asked you to run that function" while the payload is the
quantitative information (the arguments to the function).
-
+
A rule of thumb: <b>A given message type have only one semantic meaning, and
one syntaxic payload datatype</b>. If you don't do so, you have a problem.
-
+
- If the same message type may have two semantic value depending on some
fields of the payload, I'd say that you used MPI too much before. You
should use the full power of the GRAS messaging functions by using
several message types. It will simplify your code and yield better
performance.
-
+
- You shouldn't have a given message type with differing payload
datatypes. It is possible to do so (using gras_datadesc_ref_generic()),
but it's quite painful, and is rarely what you really want. Are you
sure you don't want to split these messages in two separate types?
-
+
\subsubsection GRAS_howto_design_design_protocol_cb Message callbacks
Also sketch what your processes should do when they get the given message.
application level-protocol, were these action remain simplistic. Also
identify the process-wide globals needed to write the callbacks (even if it
can be later).
-
+
\section GRAS_howto_design_implem The implementation phase
Most of the time, you will find tons of specific cases you didn't thought
about in the design phase, and going from a code sketch to an actual
-implementation is often quite difficult.
+implementation is often quite difficult.
You will probably need some process-wide globals to store some state of your
processes. See \ref GRAS_tut_tour_globals on need.
\subsection GRAS_howto_design_implem_init Implement the initialization code
You must write some initialization code for all the process kinds of your
-application.
+application.
You may want to turn your code into a clean GRAS library by using the adhoc
mecanism, but unfortunately, it's not documented yet. Worse, there is two
If you find you've found a discrepency between both implementation of GRAS,
please drop us a mail. That would be a bug.
-
+
\subsection GRAS_howto_design_test_dist Test it in a distributed setting
You are now ready for the big jump...
/** @defgroup GRAS_howto HOWTOs
@ingroup GRAS_tut
-
+
This page tries to explain how to use the GRAS framework. It does not focus
on specific functionalities (which are detailed in the initiatic tour), but
rather on global aspects. Here is the list of existing howtos for now:
- \ref GRAS_howto_design
- I plan to write a document on how to debug a GRAS application, one day.
-
+
*/
/** @defgroup GRAS_tut_intro What is GRAS
- @ingroup GRAS_tut
+ @ingroup GRAS_tut
\htmlinclude .gtut-introduction.doc.toc
\section GRAS_tut_intro_further Further readings
-After this page, you may find these one interesting:
+After this page, you may find these one interesting:
\ref GRAS_howto_design. If you're new to GRAS, you may want to read the
initiatic tour first, begining with \ref GRAS_tut_tour_install or
\ref GRAS_tut_tour_setup.
- \ref GRAS_tut_intro_what_grid
- \ref GRAS_tut_intro_what_target
- \ref GRAS_tut_intro_what_simple
-
+
We now detail each of these points.
\subsection GRAS_tut_intro_what_2ways GRAS allows you to run both in simulation mode and on real platforms
controled environment, which reveals precious to debug and study algorithms.
Everyone who tried to run even simple tests on more than 100 real machines
will consider a simulator as a nirvana.
-
+
The experiments can be reproduced in the exact same conditions (which is
somehow hard in real settings), allowing for example to reproduce a bug as
many times as you want while debugging. You can also test your algorithm
(like a network topology and/or size you do don't have access to). Under
some conditions, SimGrid simulations are also much faster than real
executions, allowing you to run more experiments in less time.
-
+
Once you assessed the quality of your algorithm in the simulator, you can
deploy it on real platforms using the second implementation of the library.
Usually, taking an algorithm out of a simulator implies an almost complete
anyhow. The communications use advanced data exchange and conversion
mecanism ensuring that you are likely to get performance at least comparable
to other communication solutions (FIXME: cite the paper once it gets
-accepted).
+accepted).
GRAS applications are portable on several operating systems (Linux, MacOS X,
Solaris, IRIX, AIX and soon Windows) and several processor architectures
efficiently even when deployed on differing material. You can for example
have a process deployed on ppc/MacOS X interacting transparently with
another one deployed on alpha/Linux.
-
+
The simulation mode of GRAS is called usually SG (for SimGrid) while the in
situ execution mode is called RL (for Real Life).
-
+
\subsection GRAS_tut_intro_what_dist GRAS was designed for distributed computing, not parallel computing
In GRAS, you build your algorithm as a set of independent processes
network-aware parallel matrix multiplication library assigning more work to
well interconnected nodes. I wouldn't advice to build a physical or
biological compututation program on top of GRAS, even if it would be
-possible in theory.
+possible in theory.
In other words, GRAS is not a grid middleware in the common understanding of
the world, but rather a tool to constitute the building bricks of such a
introduce this in the future. This is an explicit choice since I consider
multi-threading as too complicated for usual users. There is too much
non-determinism, too many race conditions, and too few language-level
-constructs to keep yourself from screwing up. This idea is well expressed
+constructs to keep yourself from screwing up. This idea is well expressed
by John Ousterhout in <i>Why Threads Are a Bad Idea (for most purposes)</i>,
published at USENIX'96. See section \ref GRAS_tut_intro_what_dist for
platform performance consideration.
considerably simplify the code written in GRAS. The main use of of
interruptions in a distributed application is to timeout communications when
they fail. GRAS communication calls allow to setup a timeout value, and
-handle it internally (see below).
+handle it internally (see below).
The only interruption mecanism used is constituted by exceptions, just like
in C++ or Java (but implemented directly in C). They are propagated from the
point where they are raised to a point where they will be trapped, if any,
or abort the execution when not trapped. You can still be certain that
nothing will happen between two lines of your code, but the second line may
-never be executed if the first one raises an exception ;)
+never be executed if the first one raises an exception ;)
This exception mecanism was introduced because without it, user code has to
be loaded by tons of non-functional code to check whether an operation was
and start the callbacks associated to them. GRAS thus supports both the
pure event-based programming model and the more classical message passing
model.\n
-
+
- <b>Internal timers</b>. There is two types of timers: delayed actions and
repetitive actions. The former happen only once when the delay expires
while the second happen regularly each time that a period expires.\n
B. Both are naturally composed of two threads: the one running user code, and
the listener in charge of listening incoming messages from the network. Both
processes also have a queue for the communication between the two threads, even
-if only the queue of process B is depicted in the graph.
+if only the queue of process B is depicted in the graph.
The experimental scenario is as follows: <ul>
/**
-@addtogroup GRAS_tut
+@addtogroup GRAS_tut
This section constitutes a tutorial to the GRAS programming environment.
-/**
+/**
@page GRAS_tut_tour_install Lesson 0: Installing GRAS
Since GRAS is technically part of the SimGrid project, you have to install
SimGrid to install GRAS. Doing so is explained in the relevant FAQ section
-(\ref install).
+(\ref install).
-Newcommers should install the stable release from the tarball, since the
+Newcommers should install the stable release from the tarball, since the
snapshots may suffer from (additionnal;) stability issues. Only go for the
git if you really need features not present in the stable releases yet (or
if you plan to help us improving the tool, what is always welcomed).
-/**
+/**
@page GRAS_tut_tour_setup Lesson 1: Setting up your own project
\section GRAS_tut_tour_setup_toc Table of Contents
- \ref GRAS_tut_tour_setup_make
- \ref GRAS_tut_tour_setup_start
-<hr>
+<hr>
Any GRAS project should be constituted of at least 3 files, and possibly
much more.
- <tt><project>.c</tt>: A source file providing the source code of your
processes.
-
+
- <tt><platform>.xml</tt>: A platform description file. It describes
the virtual platform you want to run your application onto following the
SurfXML formatting so that the simulator can parse it. This file is only
needed in SG, and you don't need any to run on real platforms (of
course). The simplest is to use one of the pre-existing one.
-
+
- <tt><project>.xml</tt>: A deployment file. It describes which of
your processes to start, on which machine and with which arguments.
-
+
- A makefile is often needed, too, even if it's not mandatory.
If we start a project called <tt>test</tt>, we have to write 3 files:
\endverbatim
Note that each of the processes's main function have the exact same
-prototype of the classical <tt>main()</tt> function in C.
+prototype of the classical <tt>main()</tt> function in C.
This is on purpose, each of them can assume this role when running in RL.
But you shouldn't write a main() function yourself since all processes will
function.
Then, each process must initialize the GRAS framework at the beginning (with
-\ref gras_init) and should finalize it at the end (with \ref gras_exit).
+\ref gras_init) and should finalize it at the end (with \ref gras_exit).
You should pass to \ref gras_init the <tt>argc</tt> and <tt>argv</tt> you
received in your "main" function so that the users of your application can
now in your path. Its source resides in the tools/gras/ directory of the
archive, if you wonder.
-Here is the calling syntax:
+Here is the calling syntax:
\verbatim gras_stub_generator <project_name> <deployment_file.xml>\endverbatim
It parses the deployment file (called <tt>test.xml</tt> in our example),
generated binaries, and that's it. To start the simulation, simply call:
\verbatim ./<project>_simulator platform.xml deployment.xml\endverbatim
-If you have an error message similar to
-\verbatim
+If you have an error message similar to
+\verbatim
./<project>_simulator: error while loading shared libraries: libsimgrid.so.2: cannot open shared object file: No such file or directory
\endverbatim
it simply means that the dynamic linker of you system fails to find
-/**
+/**
@page GRAS_tut_tour_simpleexchange Lesson 2: Exchanging simple messages
\section GRAS_tut_tour_simpleexchange_toc Table of Contents
- \ref GRAS_tut_tour_simpleexchange_socks
- \ref GRAS_tut_tour_simpleexchange_exchange
- \ref GRAS_tut_tour_simpleexchange_recaping
-
-<hr>
+
+<hr>
\section GRAS_tut_tour_simpleexchange_msgtype Declaring the messages to be exchanged
-/**
+/**
@page GRAS_tut_tour_args Lesson 3: Passing arguments to the processes (in SG)
\section GRAS_tut_tour_args_toc Table of Contents
- \ref GRAS_tut_tour_args_use
- \ref GRAS_tut_tour_args_sg
- \ref GRAS_tut_tour_args_recap
-
+
<hr>
The most problematic issue with the code of previous lesson is that it does
\skip gras_socket_client
\until gras_socket_client
-The rest of the program remains inchanged.
+The rest of the program remains inchanged.
\section GRAS_tut_tour_args_sg Passing command line arguments in deployment files
-/**
+/**
@page GRAS_tut_tour_callbacks Lesson 4: Attaching callbacks to messages
\section GRAS_tut_tour_callbacks_toc Table of Contents
- \ref GRAS_tut_tour_callbacks_attach
- \ref GRAS_tut_tour_callbacks_handle
- \ref GRAS_tut_tour_callback_recap
-
+
<hr>
Our program is well and good, but if we had to write a longer program,
function. Here is the actual code of our callback:
\dontinclude 04-callback.c
-\skip gras_msg_cb_ctx_t
+\skip gras_msg_cb_ctx_t
\until end_of_callback
\section GRAS_tut_tour_callbacks_attach Attaching callbacks
arrives. With delay=0, the process just polls for already arrived messages,
but do not wait at all if none arrived yet. If the delay is greater than 0,
the process will wait for at most that amount of seconds. If a message
-arrives in the meanwhile, it won't even wait that long.
+arrives in the meanwhile, it won't even wait that long.
Sometimes, you want to handle all messages arriving in a given period
without really knowing how much messages will come (this is often the case
\include 04-callback.output
Our little example turns slowly to a quite advanced GRAS program. It entails
-most of the mecanism most program will use.
+most of the mecanism most program will use.
There is one last thing you should know about callbacks: you can stack them,
ie attach several callbacks to the same message. GRAS will pass it to the
- \ref GRAS_tut_tour_globals_use
- \ref GRAS_tut_tour_callback_pitfall
- \ref GRAS_tut_tour_callback_recap
-
+
<hr>
\section GRAS_tut_tour_globals_intro Introduction
the several instances of your process, leading to bad problems.
Instead, you you have to put all globals in a structure, and let GRAS handle
-it with the gras_userdata_* functions (there is only 3 of them ;).
+it with the gras_userdata_* functions (there is only 3 of them ;).
\section GRAS_tut_tour_globals_use Putting globals into action
We will now modify the example to add a "kill" message, and let the server
loop on incoming messages until it gets such a message. We only need a
-boolean, so the structure is quite simple:
+boolean, so the structure is quite simple:
\dontinclude 05-globals.c
\skip struct
\until server_data
-
+
Then, we need to create this structure in the process main function. We
could use either gras_userdata_new() or gras_userdata_set(). The former is an
helper macro mallocing the space needed by the structure and passing it to
\verbatim int server(int argc, char *argv[]) {
server_data_t globals=gras_user_new(server_data_t);
/* other variable definition */
-
+
gras_init(&argc, argv);
-
+
/* rest of the code */
}\endverbatim
- \ref GRAS_tut_tour_logs_config
- \ref GRAS_tut_tour_logs_config_prio
- \ref GRAS_tut_tour_logs_config_layout
-
+
<hr>
\section GRAS_tut_tour_logs_intro Introduction
the user a fine control at run time of what gets displayed and what don't.
For that, <i>log event</i> are produced into <i>log channels</i> at a given
<i>log priority</i>. Then, you can select the minimal priority an event
-should have on a given channel to get displayed.
+should have on a given channel to get displayed.
Then, to keep things managable even when the number of channels increase,
the channels form a tree and properties get inherited from parent channel to
their respective subchannels too). Finally, channels are not just open or
closed, but filter messages below a given priority (as we said). The
priorities are defined by type #e_xbt_log_priority_t.
-
+
That is all you really need to know about the logs before diving into
practice. If you want more information on that topic, refer to the \ref
XBT_log section, which contains much more information than this page.
\section GRAS_tut_tour_logs_recap Recapping everything together
Once we changed any fprintf of our code to some of these macros, the program
-may read:
+may read:
\include 06-logs.c
And the output now looks better:
\include 06-logs.output.verbose
On the contrary, if we want to reduce the amount of logging, we may want to
-do pass <tt>--log=test.thres:error</tt>:
+do pass <tt>--log=test.thres:error</tt>:
\subsection GRAS_tut_tour_logs_config_layout Choosing how things get displayed
- \ref GRAS_tut_tour_timers_intro
- \ref GRAS_tut_tour_timers_use
- \ref GRAS_tut_tour_timers_recap
-
+
<hr>
\section GRAS_tut_tour_timers_intro Introduction
One solution is to have the members re-register periodically, so that the
coordinator can detect the processes which didn't do so since a while, and
-dismiss them.
+dismiss them.
To implement this in GRAS, we need some more functions: gras_timer_repeat()
allows to specify a periodic action and gras_timer_delay() allows to get an
- \ref GRAS_tut_tour_exceptions_intro
- \ref GRAS_tut_tour_exceptions_use
- \ref GRAS_tut_tour_exceptions_recap
-
+
<hr>
\section GRAS_tut_tour_exceptions_intro Introduction
exception in C but only in C++, Java and such. This is true, exceptions are
not part of the C language, but this is such a great tool that we
implemented an exception mecanism as part of the SimGrid library (with
-setjmp and longjmp, for the curious).
+setjmp and longjmp, for the curious).
Being "home-grown" make our exception mecanic both stronger and weaker at
the same time. First it is weaker because, well, we are more limitated
\verbatim THROWF(system_error, 0, "Cannot connect to %s:%d because of %s", hostname, port, reason);\endverbatim
Then, you simply add a #TRY/#CATCH block around your code:
-\verbatim TRY{
- /* your code */
+\verbatim TRY{
+ /* your code */
}
CATCH(e) {
/* error handling code */
So, as you can see, you don't want to include large sections of your program
in TRY blocks. If you do so, it's quite sure that one day, you'll do a break
or a return within this block. And believe me, finding such typos is a real
-pain.
+pain.
If you are suspecting this kind of error, I made a little script for you:
check <tt>tools/xbt_exception_checker</tt> from the CVS. Given a set of C
like a JVM would do (ok, it'a a bit cruder than the one of the JVM, but
anyway). For each function frame of the calling stack, it displays the
function name and its location in the source files (if it manage to retrieve
-it). Don't be jalous, you can display such stacks wherever you want with
+it). Don't be jalous, you can display such stacks wherever you want with
xbt_backtrace_display() ;)
Unfortunately, this feature is only offered under Linux for now since I have
- \ref GRAS_tut_tour_simpledata_use
- \ref GRAS_tut_tour_simpledata_example
- \ref GRAS_tut_tour_simpledata_recap
-
+
<hr>
\section GRAS_tut_tour_simpledata_intro Introduction
The platforms targeted by GRAS complicate the data transfers since the
machines may well be heterogeneous. You may want to exchange data between a
regular x86 machine (Intel and assimilated) and amd64 machine or even a ppc
-machine (Mac).
+machine (Mac).
The first problem comes from the fact that C datatypes are not always of the
same size depending on the processor. On 32 bits machines (such as x86 and
Simply, when you declare a message type with gras_msgtype_declare(), you
should provide a description of the payload data type as last argument. GRAS
will serialize the data, send it on the socket, convert it on need and
-deserialize it for you automatically.
+deserialize it for you automatically.
That means that any given message type can only convey a payload of a
predefined type. You cannot have a message type sometimes conveying an
a segfault. Try passing too few parameters to printf with regard to the
format string if you want an example. Moreover, since you can convey
structures, it is easy to overcome this limitation: if you want several
-arguments, simply pack them into a structure before doing so.
+arguments, simply pack them into a structure before doing so.
There is absolutely no limitation on the type of data you can exchange in
GRAS. If you can build a C representation of your data, you can exchange it
- int
- long int
- long long int
-
+
For all these types, there is three variant: signed, unsigned and the
version where it is not specified. For example, "signed char", "char" and
"unsigned char" are all GRAS predefined datatype. The use of the unqualified
over the network and are thus predefined)
- #xbt_peer_t (a datatype describing a peer. There is a plenty of situation
in which you want to exchange data of this type, so this is also predefined)
-
+
\section GRAS_tut_tour_simpledata_example Back to our example
We will now modify our example to add some data to the "hello" and the
"kill" messages. "hello" will convey a string being displayed in the logs
while "kill" will convey an double indicating the number of seconds to wait
-before dying.
+before dying.
The first thing is to modify the message declarations to specify that they
convey a payload. Of course, all nodes have to agree on message definitions,
the network, converted and deserialized, but really, you can consider that
it's the exact copy of your variable. So, to retrieve the content, you have
to cast the <tt>void*</tt> pointer to a pointer on your datatype, and then
-derefence it.
+derefence it.
So, it you want to retrieve a double, you have to cast the pointer using
<tt>(double*)</tt>, and then dereference the obtained pointer by adding a
- \ref GRAS_tut_tour_rpc_use_a2i_cb
- \ref GRAS_tut_tour_rpc_use_rest
- \ref GRAS_tut_tour_rpc_recap
-
+
<hr>
\section GRAS_tut_tour_rpc_intro Introduction
communication to avoid deadlocks and such issues). The second argument is
the callback context that the callback got as first argument. It denotes how
to reach the caller and such. The last argument is a pointer to a variable
-containing the result to pass to the caller.
+containing the result to pass to the caller.
Having the callee explicitly returning data to the caller allows to free
data that were allocated to do the job asked by the client, as in this
-example.
+example.
\skip server_convert_i2a_cb
\until end_of_convert_callback
\include 10-rpc.output
Now, you know how to send messages, attach callbacks and do RPCs. The next
-lesson will learn you the last missing part of the messaging library:
+lesson will learn you the last missing part of the messaging library:
\ref GRAS_tut_tour_explicitwait
*/
- \ref GRAS_tut_tour_explicitwait_code_smain
- \ref GRAS_tut_tour_explicitwait_code_cmain
- \ref GRAS_tut_tour_explicitwait_recap
-
+
<hr>
\section GRAS_tut_tour_explicitwait_intro Introduction
receiver side. You have to attach a callback to a message type, and then go
into an infinite loop. Sometimes, you want to block your execution until a
message of a given type arrives. This often occures when you want to deal
-with synchronization problems.
+with synchronization problems.
As an example, we will study a simple centralized algorithm for mutual
exclusion. In short, when the client wants to enter the critical section
(CS), it sends a specific message to the server, and waits for the server to
answer back with another message. While the client is "locked" waiting for
the message, nothing else should occure for it (no callback or timer should
-be served).
+be served).
The simplest interface to explicit message waiting allows you to specify the
message type you are willing to accept (using gras_msg_wait()). But you can
\subsection GRAS_tut_tour_explicitwait_algo GRAS modelization of the algorithm
This section naturally provides an example of how to use gras_msg_wait(),
-but it can also be seen as an example of the guidelines provided in
+but it can also be seen as an example of the guidelines provided in
\ref GRAS_howto_design.
So, here are the caracteristics of our example:
-There is two types of processes:
+There is two types of processes:
- several <i>clients</i> which want to enter a critical section
- a <i>server</i>, which grants clients to enter the CS when no other
process is already in it.
- When it gets a <i>release</i>, it checks whether there is some waiting
processes in the waiting queue. If yes, it dequeues the first one and
send a <i>grant</i> message to it. If no, it notes that the CS is free.
-
+
The server has two private data (for the callbacks to work):
- a boolean indicating whether there is a process in the CS already
- a waiting queue (#xbt_dynar_t is quite natural to code this).
-
+
The client interface is composed of two functions:
- lock(), which tries to get the grant from the server to enter the CS.
This is where explicit waiting comes into the game. This function sends a
\subsubsection GRAS_tut_tour_explicitwait_code_cb b) Defining private data and callbacks of the server
-Then, we define the callbacks that should be invoqued on the server side
+Then, we define the callbacks that should be invoqued on the server side
when some messages are received, as previously. For this, we also have to
declare a structure for the private data of the server.
The core of our distributed service is implemented (protocol, actions on
server side, and accessing function on client side). We should now
-initialize the server and let it wait for incoming messages.
+initialize the server and let it wait for incoming messages.
Defining when to stop the server can become tricky. The simplest solution is
to never let the server stop. It simply runs forever. But the simulator will
Which produces the expected output:
\include 11-explicitwait.output
-
+
*/
- \ref GRAS_tut_tour_staticstruct_intro
- \ref GRAS_tut_tour_staticstruct_use
- \ref GRAS_tut_tour_staticstruct_recap
-
+
<hr>
\section GRAS_tut_tour_staticstruct_intro Introduction
- \ref GRAS_tut_tour_pointers_use
- \ref GRAS_tut_tour_pointers_recap
- \ref GRAS_tut_tour_pointers_cste
-
+
<hr>
\section GRAS_tut_tour_pointers_intro Introduction to pointers in datadesc
\section GRAS_tut_tour_pointers_use Using pointers in datadesc
void declare_ddt() {
gras_datadesc_type_t ddt;
-
+
gras_datadesc_set_const("SIZE",SIZE); /* Set it before */
- gras_datadesc_by_symbol(array);
+ gras_datadesc_by_symbol(array);
}
\endverbatim
*/
- and the this example do use structures as payload,
- so we have to declare it to GRAS. Hopefully, this can be done easily by enclosing
- the structure declaration within a \ref GRAS_DEFINE_TYPE macro call. It will then copy this
- declaration into an hidden string variable, which can be automatically parsed at
+ and the this example do use structures as payload,
+ so we have to declare it to GRAS. Hopefully, this can be done easily by enclosing
+ the structure declaration within a \ref GRAS_DEFINE_TYPE macro call. It will then copy this
+ declaration into an hidden string variable, which can be automatically parsed at
run time. Of course, the declaration is also copied unmodified by this macro, so that it
- gets parsed by the compiler also.
+ gets parsed by the compiler also.
There is some semantic that GRAS cannot guess alone and you need to <i>annotate</i>
- your declaration to add some. For example, the ctn pointer can be a reference to an
- object or a whole array (in which case you also has to specify its size). This is done
+ your declaration to add some. For example, the ctn pointer can be a reference to an
+ object or a whole array (in which case you also has to specify its size). This is done
with the GRAS_ANNOTE call. It is removed from the text passed to the compiler, but it helps
- GRAS getting some information about the semantic of your data. Here, it says that \a ctn is an
- array, which size is the result of the operation \a rows * \a cols (with \a rows and \a cols
- being the other fields of the structure).
+ GRAS getting some information about the semantic of your data. Here, it says that \a ctn is an
+ array, which size is the result of the operation \a rows * \a cols (with \a rows and \a cols
+ being the other fields of the structure).
- Please note that this annotation mechanism is not as robust and cool as this example seems to
- imply. If you want to use it yourself, you'd better use the exact right syntax, which is
+ Please note that this annotation mechanism is not as robust and cool as this example seems to
+ imply. If you want to use it yourself, you'd better use the exact right syntax, which is
detailed in the \ref GRAS_dd section.
\skip GRAS_DEFINE_TYPE
#define MAX_LEAFSET COLS
GRAS_DEFINE_TYPE(gras_row_t,
-struct gras_row_t {
- int which_row;
+struct gras_row_t {
+ int which_row;
int row[COLS][MAX_ROUTESET];
};)
-
+
typedef struct gras_row_t gras_row_t;
-
-GRAS_DEFINE_TYPE(gras_welcome_msg_t,
+
+GRAS_DEFINE_TYPE(gras_welcome_msg_t,
struct gras_welcome_msg_t {
int id;
double time_sent;
-
+
int row_count;
gras_row_t *rows GRAS_ANNOTE(size,row_count);
-
+
int leaves[MAX_LEAFSET];
-};)
+};)
void declare_ddt(void) {
gras_datadesc_type_t ddt;
-
+
gras_datadesc_set_const("COLS",COLS);
gras_datadesc_set_const("MAX_ROUTESET",MAX_ROUTESET);
gras_datadesc_set_const("MAX_LEAFSET",MAX_LEAFSET);
-
+
gras_datadesc_by_symbol(gras_row_t); /* Parse it before */
ddt=gras_datadesc_ref("welcome_msg_t*",gras_datadesc_by_symbol(gras_welcome_msg_t));
- gras_msgtype_declare("welcome",ddt);
-}
+ gras_msgtype_declare("welcome",ddt);
+}
- \ref GRAS_tut_tour_dynar_intro
- \ref GRAS_tut_tour_dynar_use
- \ref GRAS_tut_tour_dynar_recap
-
+
<hr>
\section GRAS_tut_tour_dynar_intro Introduction
- \ref GRAS_tut_tour_manualdatadef_intro
- \ref GRAS_tut_tour_manualdatadef_use
- \ref GRAS_tut_tour_manualdatadef_recap
-
+
<hr>
\section GRAS_tut_tour_manualdatadef_intro Introduction
- \ref GRAS_tut_tour_exchangecb_intro
- \ref GRAS_tut_tour_exchangecb_use
- \ref GRAS_tut_tour_exchangecb_recap
-
+
<hr>
\section GRAS_tut_tour_exchangecb_intro Introduction
- \ref GRAS_tut_tour_message_recaping_rpc_aside2
- \ref GRAS_tut_tour_message_recaping_rpc_aside3
- \ref GRAS_tut_tour_message_recaping_sync
-
+
<hr>
This is the end of the first big part of this tutorial. At this point, you
\section GRAS_tut_tour_message_recaping_intro Message passing compared to procedure call
In GRAS, you pass message to get remote component to achieve some work for
-you. In some sense, this is very similar to the good old procedure
+you. In some sense, this is very similar to the good old procedure
abstraction: you call some procedure to get <i>it</i> doing some work for
you. Looking closer at this good old abstraction, we notice 4 call semantics:
- <tt>void procedure(void)</tt> this is a procedure accepting no argument
- and returning no result (<b>type 1</b>).
+ and returning no result (<b>type 1</b>).
- <tt>void procedure2(int i)</tt> this is a procedure accepting an
- argument, but returning no result (<b>type 2</b>).
+ argument, but returning no result (<b>type 2</b>).
- <tt>int function(void)</tt> this is a function accepting no argument, but
- returning a result (<b>type 3</b>).
+ returning a result (<b>type 3</b>).
- <tt>int function(int i)</tt> this is a function accepting an argument,
and returning a result (<b>type 4</b>).
so on every nodes, but only on "servers" or "workers" or such. First of all,
you need to declare the callback itself. This function that will be executed
on request incoming must follow a very specific prototype (the same
-regardless of the call semantic):
+regardless of the call semantic):
\verbatim
int callback_name(gras_msg_cb_ctx_t context, void *payload) \endverbatim
If your message is of semantic T3 or T4 (ie, it returns a value to the
caller), then you must use the function gras_msg_rpcreturn() to do so. It
-takes three arguments:
+takes three arguments:
- a timeout to use (so that the server don't get frozen if the client is
unresponsive)
- the message context (the variable ctx of type #gras_msg_cb_ctx_t you got
mallocated in your callback (including the data you returned to the caller:
GRAS made a copy of it during the call to gras_msg_rpcreturn()).
-The callback is expected to return 0 if ok, as detailed in
+The callback is expected to return 0 if ok, as detailed in
\ref GRAS_tut_tour_message_recaping_rpc_aside1.
\subsection GRAS_tut_tour_message_recaping_rpc4 4. Attaching callbacks to the messages
/** @defgroup GRAS_tut_tour Initiatic tour
- @ingroup GRAS_tut
+ @ingroup GRAS_tut
During this tour, you will learn all you need to write your own GRAS
applications, from the installation of the framework to the use of (almost)
all features available in GRAS.
- \htmlonly <!--
+ \htmlonly <!--
DOXYGEN_NAVBAR_CHILD "0: Installing"=GRAS_tut_tour_install.html
DOXYGEN_NAVBAR_CHILD "1: Setup a project"=GRAS_tut_tour_setup.html
DOXYGEN_NAVBAR_CHILD "2: Simple messaging"=GRAS_tut_tour_simpleexchange.html
- \ref GRAS_tut_tour_setup_glue
- \ref GRAS_tut_tour_setup_make
- \ref GRAS_tut_tour_setup_start
-
+
<b>Part 2: Message passing</b>
-
+
- \ref GRAS_tut_tour_simpleexchange
- \ref GRAS_tut_tour_simpleexchange_msgtype
- \ref GRAS_tut_tour_simpleexchange_socks
- \ref GRAS_tut_tour_simpleexchange_exchange
- \ref GRAS_tut_tour_simpleexchange_recaping
-
+
- \ref GRAS_tut_tour_args
- \ref GRAS_tut_tour_args_use
- \ref GRAS_tut_tour_args_sg
- \ref GRAS_tut_tour_args_recap
-
+
- \ref GRAS_tut_tour_callbacks
- \ref GRAS_tut_tour_callbacks_declare
- \ref GRAS_tut_tour_callbacks_attach
- \ref GRAS_tut_tour_callbacks_handle
- \ref GRAS_tut_tour_callback_recap
-
+
- \ref GRAS_tut_tour_globals
- \ref GRAS_tut_tour_globals_intro
- \ref GRAS_tut_tour_globals_use
- \ref GRAS_tut_tour_callback_pitfall
- \ref GRAS_tut_tour_callback_recap
-
+
- \ref GRAS_tut_tour_logs
- \ref GRAS_tut_tour_logs_intro
- \ref GRAS_tut_tour_logs_practice
- \ref GRAS_tut_tour_timers_intro
- \ref GRAS_tut_tour_timers_use
- \ref GRAS_tut_tour_timers_recap
-
+
- \ref GRAS_tut_tour_exceptions
- \ref GRAS_tut_tour_exceptions_intro
- \ref GRAS_tut_tour_exceptions_use
- \ref GRAS_tut_tour_exceptions_recap
-
+
- \ref GRAS_tut_tour_simpledata
- \ref GRAS_tut_tour_simpledata_intro
- \ref GRAS_tut_tour_simpledata_intro_conv
- \ref GRAS_tut_tour_simpledata_use
- \ref GRAS_tut_tour_simpledata_example
- \ref GRAS_tut_tour_simpledata_recap
-
+
- \ref GRAS_tut_tour_rpc
- \ref GRAS_tut_tour_rpc_intro
- \ref GRAS_tut_tour_rpc_use
- \ref GRAS_tut_tour_rpc_use_a2i_cb
- \ref GRAS_tut_tour_rpc_use_rest
- \ref GRAS_tut_tour_rpc_recap
-
+
- \ref GRAS_tut_tour_explicitwait
- \ref GRAS_tut_tour_explicitwait_intro
- \ref GRAS_tut_tour_explicitwait_use
- \ref GRAS_tut_tour_explicitwait_code_smain
- \ref GRAS_tut_tour_explicitwait_code_cmain
- \ref GRAS_tut_tour_explicitwait_recap
-
+
- \ref GRAS_tut_tour_message_recaping
- \ref GRAS_tut_tour_message_recaping_intro
- \ref GRAS_tut_tour_message_recaping_rpc
- \ref GRAS_tut_tour_message_recaping_rpc_aside2
- \ref GRAS_tut_tour_message_recaping_rpc_aside3
- \ref GRAS_tut_tour_message_recaping_sync
-
+
<b>Part 3: Data description</b>
- \ref GRAS_tut_tour_staticstruct
- \ref GRAS_tut_tour_staticstruct_intro
- \ref GRAS_tut_tour_staticstruct_use
- \ref GRAS_tut_tour_staticstruct_recap
-
+
- \ref GRAS_tut_tour_pointers
- \ref GRAS_tut_tour_pointers_intro
- \ref GRAS_tut_tour_pointers_use
- \ref GRAS_tut_tour_pointers_recap
- \ref GRAS_tut_tour_pointers_cste
-
+
- \ref GRAS_tut_tour_dynar
- \ref GRAS_tut_tour_dynar_intro
- \ref GRAS_tut_tour_dynar_use
- \ref GRAS_tut_tour_dynar_recap
-
+
- \ref GRAS_tut_tour_manualdatadef
- \ref GRAS_tut_tour_manualdatadef_intro
- \ref GRAS_tut_tour_manualdatadef_use
- \ref GRAS_tut_tour_manualdatadef_recap
-
+
- \ref GRAS_tut_tour_exchangecb
- \ref GRAS_tut_tour_exchangecb_intro
- \ref GRAS_tut_tour_exchangecb_use
- Splitting in several files (logs, datadesc)
- Debugging GRAS programs
- Doing proper GRAS modules
-
+
<hr>
<center>
\htmlonly
-<table width="100%">
- <tr>
- <td valign="middle" align="left">
- <img src="simgrid_logo_2011.png" alt="SimGrid - Scalable simulation of distributed systems, ranging from grids to peer-to-peer systems" />
- </td>
- <td valign="middle" align="left">
+<table width="100%">
+ <tr>
+ <td valign="middle" align="left">
+ <img src="simgrid_logo_2011.png" alt="SimGrid - Scalable simulation of distributed systems, ranging from grids to peer-to-peer systems" />
+ </td>
+ <td valign="middle" align="left">
\endhtmlonly
-\htmlinclude .index.doc.toc
+\htmlinclude .index.doc.toc
\htmlonly
- </td>
- </tr>
-</table>
+ </td>
+ </tr>
+</table>
\endhtmlonly
</center>
Grids.
\htmlonly <!-- ______BODY_END______ --!> \endhtmlonly
- - The official webpage is <a href="http://simgrid.gforge.inria.fr/">simgrid.gforge.inria.fr</a>.
- - The Frequently Asked Questions are <a href="http://simgrid.gforge.inria.fr/faq.html">here</a>.
- - The development webpage is <a href="https://gforge.inria.fr/projects/simgrid//">gforge.inria.fr/projects/simgrid</a>.
+ - The official webpage is <a href="http://simgrid.gforge.inria.fr/">simgrid.gforge.inria.fr</a>.
+ - The Frequently Asked Questions are <a href="http://simgrid.gforge.inria.fr/faq.html">here</a>.
+ - The development webpage is <a href="https://gforge.inria.fr/projects/simgrid//">gforge.inria.fr/projects/simgrid</a>.
- The user mailing list is <simgrid-user@lists.gforge.inria.fr>
- The SimGrid software package can be downloaded from <a href="http://simgrid.gforge.inria.fr/download.php">here</a>.
<br>
- If you want to study the behaviour of a MPI application using emulation
technics, 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 you want to develop a real distributed application, then you may find
<b>\ref GRAS_API</b> (Grid Reality And Simulation) useful. This is an API
- for the realization of distributed applications.
+ for the realization of distributed applications.
\n\n
Moreover, there is two implementations of this API: one on top of the
SURF (allowing to develop and test your application within the comfort of
If your favorite programming environment/model is not there (BSP,
components, OpenMP, etc.) is not represented in the SimGrid toolkit yet, you may
-consider adding it. You should contact us first on the
-<a href=http://lists.gforge.inria.fr/mailman/listinfo/simgrid-devel>SimGrid
+consider adding it. You should contact us first on the
+<a href=http://lists.gforge.inria.fr/mailman/listinfo/simgrid-devel>SimGrid
developers mailing list</a>, though.
\subsection overview_kernel Simulation kernel layer
\htmlonly <!-- ______BODY_BEGIN______ --!> \endhtmlonly
<br>
-The SimGrid software package can be downloaded from
+The SimGrid software package can be downloaded from
<a href="http://simgrid.gforge.inria.fr/download.php">here</a>.<br>
If you are interested in the history of SimGrid and in current and planned development,
you can find out more <a href="http://simgrid.gforge.inria.fr/history.html">here</a>.
-Any question, remark or suggestion are welcome on the
+Any question, remark or suggestion are welcome on the
<a href="http://lists.gforge.inria.fr/mailman/listinfo/simgrid-user">SimGrid users
mailing list</a>.
\subsubsection install_intro2 Why cmake?
-CMake permits to developers to compil projects on different plateforms. Then many tools are embedded like ctest for making test, a link to cdash for vizualise results but also test coverage and bug reports.
+CMake permits to developers to compil projects on different plateforms. Then many tools are embedded like ctest for making test, a link to cdash for vizualise results but also test coverage and bug reports.
\subsubsection install_intro3 What cmake need?
\li c and c++ compiler
\li ccmake for graphical used of CMake
\li cmake <a href="http://www.cmake.org/cmake/resources/software.html">(download page)</a>
-
-On MacOSX some users reported that it is still possible to build with clang, provided that you use the
+
+On MacOSX some users reported that it is still possible to build with clang, provided that you use the
following package versions clang3.1 and clang++3.1. If it fails on you, try to use gcc47 (port install gcc47).
For Windows :
\li MinGW <a href="http://sourceforge.net/projects/mingw/files/MinGW/">(download page)</a>
\li perl <a href="http://www.activestate.com/activeperl/downloads">(download page)</a>
\li git <a href="http://msysgit.googlecode.com/files/Git-1.7.4-preview20110204.exe">(download page)</a>
-
+
Note that if you want change the compiler, you can simply specify the environment variables CC and CXX.
\verbatim
- export CC=gcc-4.4
- export CXX=g++-4.4
- export CC=clang
- export CXX=clang++
-\endverbatim
+ export CC=gcc-4.4
+ export CXX=g++-4.4
+ export CC=clang
+ export CXX=clang++
+\endverbatim
\subsubsection install_cmakeoption1 Liste of options
enable_latency_bound_tracking ON/OFF or TRUE/FALSE or 1/0
enable_lib_static ON/OFF or TRUE/FALSE or 1/0
enable_supernovae ON/OFF or TRUE/FALSE or 1/0
- enable_msg_deprecated ON/OFF or TRUE/FALSE or 1/0
- enable_print_message ON/OFF or TRUE/FALSE or 1/0
+ enable_msg_deprecated ON/OFF or TRUE/FALSE or 1/0
+ enable_print_message ON/OFF or TRUE/FALSE or 1/0
gtnets_path <path_to_gtnets_directory>
ns3_path <path_to_ns3_directory>
CMAKE_INSTALL_PREFIX <path_to_install_directory>
pipol_user <pipol_username>
\endverbatim
-
+
\subsubsection install_cmakeoption2 Options explaination
\li enable_gtnets : set to true implie that user wants to use gtnets.
-
+
\li enable_ns3 : set to true implie that user wants to use ns3.
\li enable_lua : set to true implie that user wants to add lua langage into simgrid compilation.
\li enable_smpi : Set to true if you want to use smpi lib. Actually on simgrid v3.4.1 Mac doesn't support lib smpi.
- \li enable_maintainer_mode : set to true it remakes some files.
+ \li enable_maintainer_mode : set to true it remakes some files.
\li enable_tracing : To enable the generation of simulation traces for visualization.
\li enable_model-checking : Enable the model checking when set to true.
\li enable_debug : If enable_debug is set to 'off' Simgrid compil flag has '-DNDEBUG' option.
-
- \li enable_jedule : To enable jedule mode, which creates visualizations of task schedules with Simdag.
-
+
+ \li enable_jedule : To enable jedule mode, which creates visualizations of task schedules with Simdag.
+
\li enable_latency_bound_tracking : Set to on if you want to be warned when communications are limited by round trip time.
-
+
\li enable_lib_static : Enable generated Simgrid and smpi static libraries.
-
+
\li enable_supernovae : Set to true make one file for each lib and compile with those generated files.
-
- \li enable_msg_deprecated : Simgrid is compiled with msg deprecated functions.
-
+
+ \li enable_msg_deprecated : Simgrid is compiled with msg deprecated functions.
+
\li enable_print_message : When set to true configuration print more debug output.
-
+
\li gtnets_path : Path to gtnets install directory (ex /usr)
-
+
\li ns3_path : Path to ns3 install directory (ex /usr)
\li CMAKE_INSTALL_PREFIX : Path where are installed lib/ doc/ and include/ directories (ex /usr/local)
-
+
\li pipol_user : specify your pipol username if you want to use the pipol-remote command.
\subsubsection install_cmakeoption3 Initialisation
enable_memcheck off
enable_model-checking off
enable_jedule off
-enable_latency_bound_tracking off
+enable_latency_bound_tracking off
enable_lib_static off
CMAKE_INSTALL_PREFIX /usr/local
gtnets_path null
\subsubsection install_cmakeoption4 Option's cache and how to reset?
-When options have been set they are keep into a cache file named "CMakeCache.txt". So if you want
+When options have been set they are keep into a cache file named "CMakeCache.txt". So if you want
reset values you just delete this file located to the project directory.
\subsection install_cmakecompilation Cmake compilation
(g)make VERBOSE=1 build all targets and print build command lines
make check test all targets and summarize
make dist make the distrib
-make distcheck check the dist (make + make dist + make check)
+make distcheck check the dist (make + make dist + make check)
(g)make install install the project (doc/ bin/ lib/ include/)
(g)make uninstall uninstall the project (doc/ bin/ lib/ include/)
(g)make clean clean all targets
ctest -D Experimental
ctest -D Experimental(Start|Update|Configure|Build)
ctest -D Experimental(Test|Coverage|MemCheck|Submit)
-ctest -D Nightly
+ctest -D Nightly
ctest -D Nightly(Start|Update|Configure|Build)
ctest -D Nightly(Test|Coverage|MemCheck|Submit)
ctest -D NightlyMemoryCheck
\subsection install_cmakeinstall How to install with cmake?
-\subsubsection install_cmakeinstall1 From Git.
+\subsubsection install_cmakeinstall1 From Git.
\verbatim
git clone git://scm.gforge.inria.fr/simgrid/simgrid.git simgrid
cd simgrid
cmake -Denable_maintainer_mode=on -DCMAKE_INSTALL_PREFIX=/home/navarrop/Bureau/install_simgrid ./
-make
+make
make install
\endverbatim
\subsubsection install_cmakehowto1 Add an executable or examples.
-If you want make an executable you have to create a CMakeList.txt to the src directory.
+If you want make an executable you have to create a CMakeList.txt to the src directory.
You must specified where to create the executable, source list, dependencies and the name of the binary.
\verbatim
cmake_minimum_required(VERSION 2.6)
-set(EXECUTABLE_OUTPUT_PATH "./")
+set(EXECUTABLE_OUTPUT_PATH "./")
set(LIBRARY_OUTPUT_PATH "${CMAKE_HOME_DIRECTORY}/lib")
add_executable(get_sender get_sender.c) #add_executable(<name_of_target> <src list>)
target_link_libraries(get_sender simgrid m pthread) #target_link_libraries(<name_of_targe> <dependencies>)
\endverbatim
-Then you have to modified <project/directory>/buildtools/Cmake/MakeExeLib.cmake and add
+Then you have to modified <project/directory>/buildtools/Cmake/MakeExeLib.cmake and add
this line :
\verbatim
add_subdirectory(${CMAKE_HOME_DIRECTORY}/<path_where_is_CMakeList.txt>)
\li MinGW <a href="http://sourceforge.net/projects/mingw/files/MinGW/">(download page)</a>
\li perl <a href="http://www.activestate.com/activeperl/downloads">(download page)</a>
\li git <a href="http://msysgit.googlecode.com/files/Git-1.7.4-preview20110204.exe">(download page)</a>
-
+
Then download the package <a href="https://gforge.inria.fr/frs/?group_id=12">SimGrid Installer</a>,
execute it and follow instructions.
<a href="win_install_01.png" border=0><img src="win_install_01.png" border=0></a>
\endhtmlonly
-Step 1: Accept the license.
+Step 1: Accept the license.
\htmlonly
<a href="win_install_02.png" border=0><img src="win_install_02.png" border=0></a>
\endhtmlonly
Step 3: Choice where to install packets previously selected. Please don't use spaces in path.
-
+
\htmlonly
<a href="win_install_04.png" border=0><img src="win_install_04.png" border=0></a>
\endhtmlonly
\subsection install_Win_compile1 Compile a project "HelloWorld"
-In the SimGrid install directroy you should have an HelloWorld project to explain you how to start
+In the SimGrid install directroy you should have an HelloWorld project to explain you how to start
compiling a source file. There are:
\verbatim
- HelloWorld.c The example source file.
\li You should obtain a runnable example ("HelloWorld.exe").
For compiling your own code you can simply copy the HelloWorld project and rename source name. It will
-create a target with the same name of the source.
+create a target with the same name of the source.
\subsection install_Win_compile2 How to add and compile a new example
\li Put your source file into the helloWord directory.
\li Edit CMakeLists.txt by removing the Find Targets section and add those two lines into this section
-\verbatim
+\verbatim
################
# FIND TARGETS #
################
add_executable(TARGET_NAME SOURCES) #It creates a target called 'TARGET_NAME.exe' with the sources 'SOURCES'
target_link_libraries(TARGET_NAME simgrid pcre) #Links TARGET_NAME with simgrid and pcre
-\endverbatim
+\endverbatim
\li To initialize and build your project, you'll need to run
\verbatim
cmake -G"MinGW Makefiles" \<path_to_HelloWorld_project\>
\li Run "mingw32-make"
\li You should obtain "TARGET_NAME.exe".
-\subsection install_Win_ruby Setup a virtualbox to use SimGrid-Ruby on windows
+\subsection install_Win_ruby Setup a virtualbox to use SimGrid-Ruby on windows
Allan Espinosa made these set of Vagrant rules available so that you
can use the SimGrid Ruby bindings in a virtual machine using
our students when we teach the C language.
\verbatim
-all: masterslave
+all: masterslave
masterslave: masterslave.o sched.o
INSTALL_PATH = $$HOME
-Wmissing-noreturn -Wredundant-decls -Wnested-externs \
-Wpointer-arith -Wwrite-strings -finline-functions
REASONABLY_CAREFUL_DUDE = -Wall
-NO_PRAYER_FOR_THE_WICKED = -w -O2
+NO_PRAYER_FOR_THE_WICKED = -w -O2
WARNINGS = $(REASONABLY_CAREFUL_DUDE)
CFLAGS = -g $(WARNINGS)
INCLUDES = -I$(INSTALL_PATH)/include
DEFS = -L$(INSTALL_PATH)/lib/
-LDADD = -lm -lsimgrid
-LIBS =
+LDADD = -lm -lsimgrid
+LIBS =
%: %.o
- $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) $^ $(LIBS) $(LDADD) -o $@
+ $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) $^ $(LIBS) $(LDADD) -o $@
%.o: %.c
$(CC) $(INCLUDES) $(DEFS) $(CFLAGS) -c -o $@ $<
#####################################################################
/** \addtogroup AMOK_API
- *
- * @{ */
+ *
+ * @{ */
- /** \defgroup AMOK_bw Bandwidth */
- /** \defgroup AMOK_pm Peer Management */
+ /** \defgroup AMOK_bw Bandwidth */
+ /** \defgroup AMOK_pm Peer Management */
/** @} */
other processes, and retrive information about them.
- \ref GRAS_msg : communications are message oriented. You have to
describe all possible messages and their payload beforehand, and
- can then attach callbacks to the arrival of a given kind of message.
+ can then attach callbacks to the arrival of a given kind of message.
- \ref GRAS_timer : this is how to program repetitive and delayed
tasks, not unlike cron(8) and at(1). This cannot be used to timeout
a function (like setitimer(2) or signal(2) games could do).
This is how to let GRAS handle your globals properly.
- \ref GRAS_emul : Support to emulate code excution (ie, reporting
execution time into the simulator and having code sections specific
- to simulation or to real mode).
-
+ to simulation or to real mode).
+
\section GRAS_examples Examples
-
+
There is for now rather few examples of GRAS, but it's better than
nothing, isn't it?
-
+
- \ref GRAS_ex_ping
- \ref GRAS_ex_mmrpc
- \ref GRAS_ex_token
- \ref GRAS_ex_timer
-
+
The initiatic tour of the tutorial also contains several examples. The
most proeminent one is:
-
+
- \ref GRAS_tut_tour_explicitwait_use
\section GRAS_tut_presentation Tutorial
-
+
We even have a tutorial for the GRAS framework. It details in a
hopefully pedagogic order all the points of the API, along with example
of use for each of them. Unfortunately, it is not finished yet (the main
part missing is the one on how to describe data). Here is the table of
content:
-
+
- \ref GRAS_tut_intro
- \ref GRAS_tut_intro_what
- \ref GRAS_tut_intro_model
- \ref GRAS_tut_tour_message_recaping
\section GRAS_howto_presentation HOWTOsbis
-
+
The tutorial and the API documentation present the framework little
piece by little piece and provide a lot of information on each of them.
Quite orthogonally to this, the HOWTOs try to present transversal
allows you to run a repetitive task ("do this every N second until I tell
you to stop"), or to deffer a treatment ("do this in 3 sec").
- @{ */
- /** @defgroup GRAS_dd Data description */
- /** @defgroup GRAS_sock Sockets */
- /** @defgroup GRAS_msg Messages */
- /** @defgroup GRAS_timer Timers */
-
+ @{ */
+ /** @defgroup GRAS_dd Data description */
+ /** @defgroup GRAS_sock Sockets */
+ /** @defgroup GRAS_msg Messages */
+ /** @defgroup GRAS_timer Timers */
+
/** @} */
#####################################################################
/** @addtogroup GRAS_run
Virtualization facilities allow your code to run both on top of the simulator or in real setting.
- @{ */
-
- /** @defgroup GRAS_globals Globals */
- /** @defgroup GRAS_emul Emulation support */
- /** @defgroup GRAS_virtu Syscalls */
+ @{ */
+
+ /** @defgroup GRAS_globals Globals */
+ /** @defgroup GRAS_emul Emulation support */
+ /** @defgroup GRAS_virtu Syscalls */
/** @} */
The initiatic tour of the tutorial also contains several examples. The
most proeminent one is:
-
+
- \ref GRAS_tut_tour_explicitwait_use
There is some more examples in the distribution, under the directory
@ingroup GRAS_ex
This example implements the very classical ping-pong in GRAS. It
- involves a client (initiating the ping-pong) and a server (answering to
+ involves a client (initiating the ping-pong) and a server (answering to
client's requests).
It works the following way:
to the expeditor
- The client sends the ping message to the server, and waits for the
pong message as an answer.
-
+
This example resides in the <b>examples/gras/ping/ping.c</b> file. Yes, both
the code of the client and of the server is placed in the same file. See
the \ref GRAS_tut_tour_setup of the tutorial if wondering.
- \ref GRAS_ex_ping_sermain
- \ref GRAS_ex_ping_client
- \ref GRAS_ex_ping_climain
-
+
<hr>
\dontinclude gras/ping/ping_common.c
-
- \section GRAS_ex_ping_common 1) Common code to the client and the server
-
+
+ \section GRAS_ex_ping_common 1) Common code to the client and the server
+
\subsection GRAS_ex_ping_initial 1.a) Initial settings
-
+
Let's first load the module header and declare a logging category (see
\ref XBT_log for more info on logging).
-
+
\skip include
\until XBT_LOG
-
+
The module header <tt>ping.h</tt> reads:
-
+
\dontinclude gras/ping/ping.h
\skip include
\until argv
\until argv
\subsection GRAS_ex_ping_register 1.b) Register the messages
-
+
This function, called by both the client and the server is in charge of
declaring the existing messages to GRAS. Since the payload does not
- involve any newly created types but only int, this is quite easy.
- (to exchange more complicated types, see \ref GRAS_dd or
+ involve any newly created types but only int, this is quite easy.
+ (to exchange more complicated types, see \ref GRAS_dd or
\ref GRAS_ex_mmrpc for an example).
\dontinclude gras/ping/ping_common.c
[Back to \ref GRAS_ex_ping_toc]
\section GRAS_ex_ping_server 2) Server's code
-
+
\subsection GRAS_ex_ping_serdata 2.a) The server's globals
In order to ensure the communication between the "main" and the callback
\dontinclude gras/ping/ping_server.c
\skip typedef struct
\until }
-
+
\subsection GRAS_ex_ping_sercb 2.b) The callback to the ping message
Here is the callback run when the server receives any ping message (this
will be registered later by the server).
-
+
\skip server_cb_ping_handler
\until end_of_server_cb_ping_handler
\subsection GRAS_ex_ping_sermain 2.c) The "main" of the server
-
+
This is the "main" of the server. As explained in the tutorial, \ref
GRAS_tut_tour_setup, you must not write any main()
function yourself. Instead, you just have to write a regular function
like this one which will act as a main.
-
+
\skip server
\until end_of_server
[Back to \ref GRAS_ex_ping_toc]
-
+
\section GRAS_ex_ping_client 3) Client's code
-
+
\subsection GRAS_ex_ping_climain 3.a) Client's "main" function
-
+
This function is quite straightforward, and the inlined comments should
be enough to understand it.
only one having it. So, if there is an action you want all processes to
do alternativly, but you cannot afford to have two processes doing it at
the same time, let the process having the token doing it.
-
+
Actually, there is a lot of different token ring algorithms in the
litterature, so this example implements one of them: the simplest one.
The ring is static (no new node can join it, and you'll get trouble if
one node dies or leaves), and nothing is done for the case in which the
- token is lost.
+ token is lost.
- \ref GRAS_ex_stoken_deploy
- \ref GRAS_ex_stoken_global
Here is the deployment file:
\include examples/gras/mutual_exclusion/simple_token/simple_token.xml
-
+
The neighbour of each node is given at startup as command line argument.
Moreover, one of the nodes is instructed by a specific argument (the one
on Tremblay here) to create the token at the begining of the algorithm.
-
+
\section GRAS_ex_stoken_global 2) Global definition
-
+
The token is incarned by a specific message, which circulates from node
to node (the payload is an integer incremented at each hop). So, the most
important part of the code is the message callback, which forwards the
message to the next node. That is why we have to store all variable in a
- global, as explained in the \ref GRAS_globals section.
+ global, as explained in the \ref GRAS_globals section.
\dontinclude examples/gras/mutual_exclusion/simple_token/simple_token.c
\skip typedef
\until }
-
+
\section GRAS_ex_stoken_callback 3) The callback
-
+
Even if this is the core of this algorithm, this function is quite
straightforward.
-
+
\skip node_cb_stoken_handler
\until end_of_node_cb_stoken_handler
\section GRAS_ex_stoken_main 4) The main function
-
+
This function is splited in two parts: The first one performs all the
- needed initialisations (points 1-7) while the end (point 8. below) calls
+ needed initialisations (points 1-7) while the end (point 8. below) calls
gras_msg_handle() as long as the planned amount of ring loops are not
performed.
-
+
\skip node
\until end_of_node
/** @defgroup GRAS_ex_mmrpc A simple RPC for matrix multiplication
@ingroup GRAS_ex
- This example implements a remote matrix multiplication. It involves a client
- (creating the matrices and sending the multiplications requests) and a server
+ This example implements a remote matrix multiplication. It involves a client
+ (creating the matrices and sending the multiplications requests) and a server
(computing the multiplication on client's behalf).
- This example also constitutes a more advanced example of data description
- mechanisms, since the message payload type is a bit more complicated than in
+ This example also constitutes a more advanced example of data description
+ mechanisms, since the message payload type is a bit more complicated than in
other examples such as the ping one (\ref GRAS_ex_ping).
It works the following way (not very different from the ping example):
- Both the client and the server register all needed messages and datatypes
- The server registers a callback to the "request" message, which computes
what needs to be and returns the result to the expeditor.
- - The client creates two matrices, ask for their multiplication and check
+ - The client creates two matrices, ask for their multiplication and check
the server's answer.
-
+
This example resides in the <b>examples/gras/mmrpc/mmrpc.c</b> file. (See
the \ref GRAS_tut_tour_setup of the tutorial if wondering why both the server
and the client live in the same source file)
- \ref GRAS_ex_mmrpc_client
- \ref GRAS_ex_mmrpc_cliinc
- \ref GRAS_ex_mmrpc_climain
-
+
<hr>
-
+
\section GRAS_ex_mmrpc_common 1) Common code to the client and the server (mmrpc_common.c and mmrpc.h)
-
-
+
+
\subsection GRAS_ex_mmrpc_header 1.a) Module header (mmrpc.h)
This loads the gras header and declare the function's prototypes as well
xbt/matrix module.
\subsection GRAS_ex_mmrpc_logdef 1.c) Logging category definition (mmrpc_common.c)
-
+
Let's first load the module header and declare a logging category (see
\ref XBT_log for more info on logging). This logging category does live
in this file (ie the required symbols are defined here and declared as
- "extern" in any other file using them). That is why we use
- \ref XBT_LOG_NEW_DEFAULT_CATEGORY here and
+ "extern" in any other file using them). That is why we use
+ \ref XBT_LOG_NEW_DEFAULT_CATEGORY here and
\ref XBT_LOG_EXTERNAL_DEFAULT_CATEGORY in mmrpc_client.c and mmrpc_server.c.
-
+
\dontinclude gras/mmrpc/mmrpc_common.c
\skip include
\until XBT_LOG
\subsection GRAS_ex_mmrpc_msgregister 1.d) Register the messages (mmrpc_common.c)
-
+
This function, called by both the client and the server is in charge of
declaring the existing messages to GRAS.
- The datatype description builded that way can then be used to build an array datatype or
+ The datatype description builded that way can then be used to build an array datatype or
to declare messages.
-
+
\skip register_messages
\until }
[Back to \ref GRAS_ex_mmrpc_toc]
\section GRAS_ex_mmrpc_server 2) Server's code (mmrpc_server.c)
-
+
\subsection GRAS_ex_mmrpc_serinc 2.a) Server intial settings
-
+
All module symbols live in the mmrpc_common.c file. We thus have to
define \ref XBT_DEFINE_TYPE_EXTERN to the preprocessor so that the
- \ref XBT_DEFINE_TYPE symbols don't get included here. Likewise, we use
+ \ref XBT_DEFINE_TYPE symbols don't get included here. Likewise, we use
\ref XBT_LOG_EXTERNAL_DEFAULT_CATEGORY to get the log category in here.
-
+
\dontinclude gras/mmrpc/mmrpc_server.c
\skip define
\until XBT_LOG
\subsection GRAS_ex_mmrpc_sercb 2.b) The callback to the mmrpc message
Here is the callback run when the server receives any mmrpc message (this
- will be registered later by the server). Note the way we get the message
- payload. In the ping example, there was one additional level of pointer
+ will be registered later by the server). Note the way we get the message
+ payload. In the ping example, there was one additional level of pointer
indirection (see \ref GRAS_ex_ping_sercb). This is because the payload is
an array here (ie a pointer) whereas it is a scalar in the ping example.
-
+
\skip server_cb_request_handler
\until end_of_server_cb_request_handler
\subsection GRAS_ex_mmrpc_sermain 2.c) The "main" of the server
-
+
This is the "main" of the server. As explained in the tutorial, \ref
GRAS_tut_tour_setup, you must not write any main()
function yourself. Instead, you just have to write a regular function
like this one which will act as a main.
-
+
\skip server
\until end_of_server
-
+
[Back to \ref GRAS_ex_mmrpc_toc]
\section GRAS_ex_mmrpc_client 3) Client's code (mmrpc_client.c)
-
+
\subsection GRAS_ex_mmrpc_cliinc 2.a) Server intial settings
-
+
As for the server, some extra love is needed to make sure that automatic
datatype parsing and log categories do work even if we are using several
- files.
-
+ files.
+
\dontinclude gras/mmrpc/mmrpc_client.c
\skip define
\until XBT_LOG
\subsection GRAS_ex_mmrpc_climain 3.b) Client's "main" function
-
+
This function is quite straightforward, and the inlined comments should
be enough to understand it.
This example fools around with the GRAS timers (\ref GRAS_timer). It is
mainly a regression test, since it uses almost all timer features.
-
+
The main program registers a repetititive task and a delayed one, and
then loops until the <tt>still_to_do</tt> variables of its globals reach
0. The delayed task set it to 5, and the repetititive one decrease it
- \ref GRAS_ex_timer_main
\dontinclude timer.c
-
+
\section GRAS_ex_timer_decl 1. Declarations and headers
\skip include
\until my_globals
-
+
\section GRAS_ex_timer_delay 2. Source code of the delayed action
\skip repetitive_action
\until end_of_repetitive_action
-
+
\section GRAS_ex_timer_repeat 3. Source code of the repetitive action
\skip delayed_action
\until end_of_delayed_action
-
+
\section GRAS_ex_timer_main 4. Source code of main function
\skip client
\until end_of_client
This describes the native to MSG.
\section jMSG_who Who should use this (and who shouldn't)
-
+
You should use MSG if you want to study some heuristics for a
given problem you don't really want to implement. If you want to
use the C programming language, your are in the right
/**
@defgroup MSG_examples MSG Examples
@ingroup MSG_API
-
+
@htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Examples" --> @endhtmlonly
MSG comes with an extensive set of examples. It is sometimes difficult
*/
-/**
+/**
@defgroup msg_simulation Main MSG simulation Functions
@ingroup MSG_API
@brief Describes how to setup and control your simulation.
@htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Simulation Control" --> @endhtmlonly
*/
-/** @defgroup m_process_management Process Management Functions
+/** @defgroup m_process_management Process Management Functions
* @ingroup MSG_API
* @brief This section describes the process structure of MSG
* (#m_process_t) and the functions for managing it.
*/
-
+
/** @defgroup m_host_management Host Management Functions
* @ingroup MSG_API
* @brief This section describes the host structure of MSG
*/
-
+
/** @defgroup m_task_management Task Management Functions
* @ingroup MSG_API
* @brief This section describes the task structure of MSG
*
* \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Tasks" --> \endhtmlonly
*/
-
+
/** @defgroup msg_task_usage Task Actions
* @ingroup MSG_API
* @brief This section describes the functions that can be used
*
* With it, you can create virtual machines to put your processes
* into, and interact directly with the VMs to manage groups of
- * processes.
+ * processes.
*
* This interface is highly experimental at this point. Testing is
* welcomed, but do not expect too much of it right now. Even the
* @brief This section describes the file structure of MSG
* (#msg_file_t) and the functions for managing it. It
* is based on POSIX functions.
- */
+ */
-/**
+/**
@defgroup msg_trace_driven Trace-driven simulations
@ingroup MSG_API
@brief This section describes the functions allowing to build trace-driven simulations.
This is very handy when you want to test an algorithm or protocol that
does nothing unless it receives some events from outside. For example,
a P2P protocol reacts to requests from the user, but does nothing if
-there is no such event.
-
+there is no such event.
+
In such situations, SimGrid allows to write your protocol in your C
file, and the events to react to in a separate text file. Declare a
function handling each of the events that you want to accept in your
trace files, register them using #MSG_action_register in your main,
and then use #MSG_action_trace_run to launch the simulation. You can
either have one trace file containing all your events, or a file per
-simulated process.
-
+simulated process.
+
Check the examples in <b>examples/msg/actions/actions.c</b> for details.
-
- */
-
-
+ */
+
+
+
/**
@defgroup MSG_LUA Lua bindings
@ingroup MSG_API
@brief Lua bindings to MSG (\ref MSG_API)
-@htmlonly <!-- DOXYGEN_NAVBAR_LABEL="LUA bindings" --> @endhtmlonly
-
+@htmlonly <!-- DOXYGEN_NAVBAR_LABEL="LUA bindings" --> @endhtmlonly
+
This is the lua bindings of the \ref MSG_API interface.
\section lMSG_who Who should use this (and who shouldn't)
-
+
If you want to use MSG to study your algorithm, but you don't want to
use the C language (using \ref MSG_API), then you should use some
bindings such as this one. The advantage of the lua bindings is that
lua modules implemented directly in C as we are using, there is no
ready to use reference documentation for this module. Even more than
for the other modules, you will have to dig into the source code of
-the examples to learn how to use it.
+the examples to learn how to use it.
\section Lua_examples Examples of lua MSG
-
+
- \ref MSG_ex_master_slave_lua
- \ref MSG_ex_master_slave_lua_bypass
- Also, the lua version of the Chord example (in the source tree)
We don't remove them because the ability to run old scientific
code is something important to us. But these functionalities are
-not actively supported anymore.
+not actively supported anymore.
To access these functions, you should define the relevant option
at configuration time in ccmake.
*/
-/**
+/**
@defgroup MSG_ex_asynchronous_communications Asynchronous communications
@ingroup MSG_examples
- \ref MSG_ext_icomms_fct_Waitall
- \ref MSG_ext_icomms_fct_Waitany
-<hr>
+<hr>
\dontinclude msg/icomms/peer.c
\subsection MSG_ext_icomms_Sender Sender function
-The sender send to a receiver an asynchronous message with the function "MSG_task_isend()". Cause this function is non-blocking
+The sender send to a receiver an asynchronous message with the function "MSG_task_isend()". Cause this function is non-blocking
we have to make "MSG_comm_test()" to know if the communication is finished for finally destroy it with function "MSG_comm_destroy()".
-It also available to "make MSG_comm_wait()" which make both of them.
+It also available to "make MSG_comm_wait()" which make both of them.
C style arguments (argc/argv) are interpreted as:
- the number of tasks to distribute
This function is the core of the simulation and is divided only into 3 parts
thanks to MSG_create_environment() and MSG_launch_application().
- -# Simulation settings : MSG_create_environment() creates a realistic
+ -# Simulation settings : MSG_create_environment() creates a realistic
environment
- -# Application deployment : create the processes on the right locations with
+ -# Application deployment : create the processes on the right locations with
MSG_launch_application()
-# The simulation is run with #MSG_main()
-
+
Its arguments are:
- <i>platform_file</i>: the name of a file containing an valid surfxml platform description.
- <i>application_file</i>: the name of a file containing a valid surfxml application description
*/
-/**
+/**
@defgroup MSG_ex_master_slave Basic Master/Slaves
@ingroup MSG_examples
-
+
Simulation of a master-slave application using a realistic platform
-and an external description of the deployment.
+and an external description of the deployment.
\section MSG_ex_ms_TOC Table of contents:
-
+
- \ref MSG_ext_ms_code
- \ref MSG_ext_ms_preliminary
- \ref MSG_ext_ms_master
- \ref MSG_ext_ms_core
- \ref MSG_ext_ms_main
- \ref MSG_ext_ms_helping
- - \ref MSG_ext_ms_application
+ - \ref MSG_ext_ms_application
- \ref MSG_ext_ms_platform
-
-<hr>
+
+<hr>
\dontinclude msg/masterslave/masterslave_forwarder.c
\until }
\subsection MSG_ext_ms_master Master code
-
+
This function has to be assigned to a m_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 #MSG_function_register() and then automatically assigned to a
process through #MSG_launch_application().
-
+
C style arguments (argc/argv) are interpreted as:
- the number of tasks to distribute
- the computation size of each task
- a list of host that will accept those tasks.
Tasks are dumbly sent in a round-robin style.
-
+
\until end_of_master
-
+
\subsection MSG_ext_ms_slave Slave code
-
+
This function has to be assigned to a #m_process_t that has to behave
as a slave. Just like the master fuction (described in \ref
MSG_ext_ms_master), it should not be called directly.
This function keeps waiting for tasks and executes them as it receives them.
-
+
\until end_of_slave
\subsection MSG_ext_ms_forwarder Forwarder code
-
+
This function has to be assigned to a #m_process_t that has to behave
as a forwarder. Just like the master function (described in \ref
MSG_ext_ms_master), it should not be called directly.
This function is the core of the simulation and is divided only into 3 parts
thanks to MSG_create_environment() and MSG_launch_application().
- -# Simulation settings : MSG_create_environment() creates a realistic
+ -# Simulation settings : MSG_create_environment() creates a realistic
environment
- -# Application deployment : create the processes on the right locations with
+ -# Application deployment : create the processes on the right locations with
MSG_launch_application()
-# The simulation is run with #MSG_main()
-
+
Its arguments are:
- <i>platform_file</i>: the name of a file containing an valid surfxml platform description.
- <i>application_file</i>: the name of a file containing a valid surfxml application description
-
+
\until end_of_test_all
-
+
\subsection MSG_ext_ms_main Main() function
-
+
This initializes MSG, runs a simulation, and free all data-structures created by MSG.
-
+
\until end_of_main
\section MSG_ext_ms_helping Helping files
\subsection MSG_ext_ms_platform Example of platform file
\include msg/small_platform.xml
-
+
*/
/** \page MSG_ex_master_slave_lua Master/slave Lua application
-
+
Simulation of a master-slave application using lua bindings
- \ref MSG_ext_ms_code_lua
- \ref MSG_ext_ms_master_lua
- \ref MSG_ext_ms_core_lua
- \ref MSG_ext_ms_helping
- - \ref MSG_ext_ms_application
+ - \ref MSG_ext_ms_application
- \ref MSG_ext_ms_platform
-
-
+
+
\dontinclude lua/masterslave/master_slave.lua
-
+
\section MSG_ext_ms_code_lua Code of the application
-
+
\subsection MSG_ext_ms_master_lua Master code
-
+
as described ine the C native master/Slave exmaple , this function has to be assigned to a m_process_t that will behave as the master.
-
+
Lua style arguments (...) in for the master are interpreted as:
- the number of tasks to distribute
- the computation size of each task
- a list of host that will accept those tasks.
Tasks are dumbly sent in a round-robin style.
-
+
\until end_of_master
-
-
+
+
\subsection MSG_ext_ms_slave_lua Slave code
-
+
This function has to be assigned to a #m_process_t that has to behave as a slave.
This function keeps waiting for tasks and executes them as it receives them.
-
+
\until end_of_slave
\subsection MSG_ext_ms_core_lua Simulation core
in this section the core of the simulation which start by including the simgrid lib for bindings
: <i>require "simgrid" </i>
-
- -# Simulation settings : <i>simgrid.platform</i> creates a realistic
- environment
- -# Application deployment : create the processes on the right locations with
+
+ -# Simulation settings : <i>simgrid.platform</i> creates a realistic
+ environment
+ -# Application deployment : create the processes on the right locations with
<i>simgrid.application</i>
-# The simulation is run with <i>simgrid.run</i>
-
+
Its arguments are:
- <i>platform_file</i>: the name of a file containing an valid surfxml platform description.( first command line argument)
- <i>application_file</i>: the name of a file containing a valid surfxml application description ( second commande line argument )
-
+
\until simgrid.clean()
-
+
*/
/** \page MSG_ex_master_slave_lua_bypass Master/slave Bypass Lua application
-
+
Simulation of a master-slave application using lua bindings, Bypassing the XML parser
- \ref MSG_ext_ms_code_lua
- \ref MSG_ext_ms_master_lua
- \ref MSG_ext_ms_slave_lua
- \ref MSG_ext_ms_core_lua
-
-
+
+
\dontinclude lua/console/master_slave_bypass.lua
-
+
\section MSG_ext_ms_code_lua Code of the application
-
+
\subsection MSG_ext_ms_master_lua Master code
-
+
as described ine the C native master/Slave exmaple , this function has to be assigned to a m_process_t that will behave as the master.
-
+
Lua style arguments (...) in for the master are interpreted as:
- the number of tasks to distribute
- the computation size of each task
- a list of host that will accept those tasks.
Tasks are dumbly sent in a round-robin style.
-
+
\until end_of_master
-
-
+
+
\subsection MSG_ext_ms_slave_lua Slave code
-
+
This function has to be assigned to a #m_process_t that has to behave as a slave.
This function keeps waiting for tasks and executes them as it receives them.
-
+
\until end_of_slave
\subsection MSG_ext_ms_core_lua Simulation core
in this section the core of the simulation which start by including the simgrid lib for bindings, then create the resources we need to set up our environment bypassing the XML parser.
: <i>require "simgrid" </i>
-
+
-# Hosts : <i>simgrid.Host.new</i> instanciate a new host with an id, and power.
-# Links : <i>simgrid.Link.new</i> instanictae a new link that will require an id, bandwith and latency values.
-# Route : <i>simgrid.Route.new</i> define a route between two hosts specifying the links to use.
- <i>simgrid.register_application()</i>: saving the deployment settings before running the simualtion.
\until simgrid.clean()
-
+
*/
-/** @addtogroup SD_API
+/** @addtogroup SD_API
\section SD_func Offered functionnalities
- \ref SD_datatypes_management
*/
-/** @defgroup SD_datatypes_management SD Data Types
+/** @defgroup SD_datatypes_management SD Data Types
@ingroup SD_API
@brief This section describes the different datatypes provided by SD.
*/
-/** \addtogroup SURF_API
+/** \addtogroup SURF_API
\section SURF_doc Surf documentation
- \ref SURF_simulation
/** \defgroup SURF_simulation Simulation
\ingroup SURF_API
\brief Functions for creating the environment and launching the simulation
-
+
This section describes the functions for initialising SURF, performing
the simulation and exiting SURF.
*/
/** \defgroup SURF_actions SURF actions
\ingroup SURF_API
\brief This section describes the different datatypes and operations related to the actions in SURF.
-
+
\htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Actions" --> \endhtmlonly
*/
/** \defgroup SURF_resources SURF resources
\ingroup SURF_API
\brief This section describes the different datatypes and operations related to the resources in SURF.
-
+
\htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Resources" --> \endhtmlonly
*/
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_workstation_resource->common_public->states.done_action_set.
- Depending on these results, you can schedule other tasks and call surf_solve() again.
+ 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.
/** @addtogroup XBT_API
-
+
The XBT functionalities fall into several categories:
- Portability support
- \ref XBT_syscall
- \ref XBT_config
- \ref XBT_mallocator
- Data structures
- - \ref XBT_dynar
+ - \ref XBT_dynar
- \ref XBT_dict
- - \ref XBT_set
+ - \ref XBT_set
Data are associated to both an ID (0(1) search) and a name
- \ref XBT_fifo
- \ref XBT_queue
- \ref XBT_peer
- \ref XBT_misc
- \ref XBT_graph
-
+
@{ */
/** @defgroup XBT_grounding Grounding features */
/** @defgroup XBT_adt Usual data structures */
########################################################################
-/** @addtogroup XBT_grounding
-
+/** @addtogroup XBT_grounding
+
Grounding features are the basement of SimGrid. You'll find portable (and
secure) wrappers to the malloc-like functions, logging support, error
reporting features, etc.
-
+
@{ */
/** @defgroup XBT_syscall Malloc and friends */
########################################################################
/** @addtogroup XBT_adt
-
+
Here are the basic data containers that every C programmer rewrites one day.
You won't need to do so yourself, you lucky one, because we did it for you.
-
+
@{ */
/** @defgroup XBT_dynar Dynar: generic dynamic array */
/** @defgroup XBT_dict Dict: generic dictionnary */
/** @defgroup XBT_fifo Fifo: generic workqueue */
/** @defgroup XBT_swag Swag: O(1) set datatype */
/** @defgroup XBT_heap Heap: generic heap data structure */
-/** @} */
+/** @} */
########################################################################
/** @addtogroup XBT_misc
-
+
Here are several general purposes library components designed specially
for you, you lucky one.
-
+
@{ */
/** @defgroup XBT_graph General purpose graph library */
* ************************* */
/** \defgroup XBT_context Portable context implementation
- * \brief Contexts are a higher level system than <tt>setjump/longjmp</tt>
+ * \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
+ * 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, \ref GRAS_API and \ref SMPI_API).
*
* You should use those environments instead.
-/**
+/**
\defgroup SimGrid_API SimGrid modules */
/** \defgroup XBT_API XBT
/** \defgroup MSG_API MSG
\ingroup SimGrid_API
- \brief Simple programming environment
-
+ \brief Simple programming environment
+
MSG was the first distributed programming environment provided within
SimGrid. While almost realistic, it remains quite simple (simplistic?).
\section MSG_who Who should use this (and who shouldn't)
-
+
You should use this module if you want to study some heuristics for a
given problem you don't really want to implement.
If you want to use DAGs, have a look at the \ref SD_API programming
If you want to get a real (but experimental) implementation of your solution, have a look
at the \ref GRAS_API one. If you want to study an existing MPI program,
have a look at the \ref SMPI_API one. If none of those programming
- environments fits your needs, you may consider implementing your own
+ environments fits your needs, you may consider implementing your own
directly on top of \ref SURF_API (but you probably want to contact us
- before).
+ before).
*/
/** \defgroup GRAS_API GRAS
\ingroup SimGrid_API
\brief Realistic programming environment (Grid Reality And Simulation)
-
+
GRAS provides a complete API to implement distributed application on top
of heterogeneous plateforms. In addition to the SimGrid implementation
of this interface (allowing you to work on your application within the
also provided (allowing you to really use your application once you're
done with developing it). It may still contain rought corners as
GRAS is not the most used part of SimGrid, however.
-
+
GRAS thus constitute a complete grid application developement framework,
encompassing both developer helping tools (the simulator and associated
tools) and an efficient while portable execution runtime.
-
+
\section GRAS_who Who should use this (and who shouldn't)
-
+
You should use this programming environment if you want to develop real
- applications, ie if the final result of your work is a program which
+ applications, ie if the final result of your work is a program which
may eventually be distributed. Rember however that GRAS is
considered as experimental at this point. Help would be welcomed
to improve this sorry situation...
-
+
If you just want to study some heuristics for a given problem you don't
want to implement really (ie, if your result would be a theorem), have a
look at the \ref MSG_API one, or the \ref SD_API one if you need to use DAGs.
- If you want to study an existing MPI program, have a look at the
- \ref SMPI_API one.
+ If you want to study an existing MPI program, have a look at the
+ \ref SMPI_API one.
If none of those programming environments fits your needs, you may
consider implementing your own directly on top of \ref SURF_API (but you
probably want to contact us before).
\ingroup SimGrid_API
\brief Distributed toolkit built over \ref GRAS_API (Advanced Metacomputing Overlay Kit)
- AMOK provides several tools useful to most applications built on top of GRAS,
- but yet not belonging to GRAS itself. It is planned that those modules will be
+ AMOK provides several tools useful to most applications built on top of GRAS,
+ but yet not belonging to GRAS itself. It is planned that those modules will be
changed to real plugins one day, allowing users to load only the needed parts at
- run time. For now, they live in another library against which you should link your
+ run time. For now, they live in another library against which you should link your
programs explicitly.
*/
/** \defgroup SMPI_API SMPI
\ingroup SimGrid_API
\brief Programming environment for the simulation of MPI applications
-
+
This programming environment permits to study existing MPI application
by emulating them on top of the SimGrid simulator. In other words, it
will constitute an emulation solution for parallel codes. You don't
even have to modify your code for that, although that may help, as
detailed below.
-
+
\section SMPI_who Who should use SMPI (and who shouldn't)
-
+
You should use this programming environment of the SimGrid suite if
you want to study existing MPI applications. If you want to create a
distributed application, you may be interested in the \ref GRAS_API
one if you need to use DAGs. If none of those programming environments
fits your needs, you may consider implementing your own directly on
top of \ref SURF_API (but you probably want to contact us before).
-
+
\section SMPI_what What can run within SMPI?
You can run unmodified MPI applications (both C and Fortran) within
want to use all the hosts defined in the hostfile, <tt>-map</tt> to
display on which host each rank gets mapped of <tt>-trace</tt> to
activate the tracing during the simulation. You can get the full list
-by running
-\verbatim
+by running
+\verbatim
smpirun -help
\endverbatim
/** \defgroup SD_API SimDag
\ingroup SimGrid_API
\brief Programming environment for DAG applications
-
+
SimDag provides some functionnalities to simulate parallel task scheduling
with DAGs models (Direct Acyclic Graphs).
The old versions of SimGrid were based on DAGs. But the DAG part (named SG)
was removed in SimGrid 3 because the new kernel (\ref SURF_API) was implemented. \ref SURF_API
was much faster and more flexible than SG and did not use DAGs.
SimDag is a new implementation of DAGs handling and it is built on top of \ref SURF_API.
-
+
\section SD_who Who should use this (and who shouldn't)
-
+
You should use this programming environment of the SimGrid suite if you want
to study algorithms and heuristics with DAGs of parallel tasks.
If you don't need to use DAGs for your simulation, have a look at the
\ref MSG_API programming environment.
If you want to implement a real distributed application, have a look at the
\ref GRAS_API programming environment.
- If you want to study an existing MPI program, have a look at the
- \ref SMPI_API one.
+ If you want to study an existing MPI program, have a look at the
+ \ref SMPI_API one.
If none of those programming environments fits your needs, you may
consider implementing your own directly on top of \ref SURF_API (but you
probably want to contact us before).
*/
-/**
+/**
@defgroup SURF_API SURF
@ingroup SimGrid_API
@brief Internal kernel of all the simulators used in SimGrid, and associated models.
-
+
SURF provides the core functionnalities to simulate a virtual
platform. It is very low-level and is not intended to be used by end
users, but rather to serve as a basis for higher-level simulators. Its
the feasibility of your idea.
Please note that as it is not really intended for public use, this
-module is only partially documented.
+module is only partially documented.
*/
int main(int argc, char *argv[]) {
MSG_global_init(&argc, argv);
-
+
xbt_cfg_set_parse(_surf_cfg_set,"Item:Value");
-
+
// Rest of your code
}
\endcode
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
-should provide information about all models for all existing resources.
+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 workstation/model: specify the used workstation model
information. Note that the CM02 model is described in the research report
<a href="ftp://ftp.ens-lyon.fr/pub/LIP/Rapports/RR/RR2002/RR2002-40.ps.gz">A
Network Model for Simulation of Grid Application</a> while LV08 is
-described in
+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
two extra models, described below, and some \ref options_pls "specific
additional configuration flags".
- \b GTNets: Network pseudo-model using the GTNets simulator instead
- of an analytic model
+ of an analytic model
- \b NS3: Network pseudo-model using the NS3 tcp model instead of an
- analytic model
+ analytic model
Concerning the CPU, we have only one model for now:
- \b Cas01: Simplistic CPU model (time=size/power)
-
+
The workstation concept is the aggregation of a CPU with a network
card. Three models exists, but actually, only 2 of them are
interesting. The "compound" one is simply due to the way our internal
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 workstation model. Currently, CPU:Cas01 and
+ - \b default: Default workstation model. Currently, CPU:Cas01 and
network:LV08 (with cross traffic enabled)
- \b compound: Workstation model that is automatically chosen if
you change the network and CPU models
- \b ptask_L07: Workstation model somehow similar to Cas01+CM02 but
allowing parallel tasks
-
+
\subsection options_model_optim Optimization level of the platform models
The network and CPU models that are based on lmm_solve (that
heap in action remaining).
- \b TI: Trace integration. Highly optimized mode when using
availability traces (only available for the Cas01 CPU model for
- now).
+ now).
- \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
should be lazily updated or not. It should have no impact on the
- computed timings, but should speed up the computation.
-
+ computed timings, but should speed up the computation.
+
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
cat /proc/sys/net/ipv4/tcp_wmem # gives the receiver window
\endverbatim
-\subsubsection options_model_network_coefs Corrective simulation factors
+\subsubsection options_model_network_coefs Corrective simulation factors
These factors allow to betterly take the slow start into account.
The corresponding values were computed through data fitting one the
timings of packet-level simulators. You should not change these values
-unless you are really certain of what you are doing. See
+unless you are really certain of what you are doing. See
<a href="http://mescal.imag.fr/membres/arnaud.legrand/articles/simutools09.pdf">Accuracy Study and Improvement of Network Simulation in the SimGrid Framework</a>
for more informations about these coeficients.
available in <tt>examples/msg/gtnets/crosstraffic-p.xml</tt>.
This is activated through the \b network/crosstraffic item, that
-can be set to 0 (disable this feature) or 1 (enable it).
+can be set to 0 (disable this feature) or 1 (enable it).
Note that with the default workstation model this option is activated by default.
in NS3. The only valid values (enforced on the SimGrid side) are
'NewReno' or 'Reno' or 'Tahoe'.
-When using GTNeTS, two items exist:
+When using GTNeTS, two items exist:
- \b gtnets/jitter, that is a double value to oscillate
the link latency, uniformly in random interval
[-latency*gtnets_jitter,latency*gtnets_jitter). It defaults to 0.
\section options_modelchecking Configuring the Model-Checking
To enable the experimental SimGrid model-checking support the program should
-be executed with the command line argument
+be executed with the command line argument
\verbatim
---cfg=model-check:1
+--cfg=model-check:1
\endverbatim
Properties are expressed as assertions using the function
\verbatim
auto-detection fails for you). They are sorted here from the slowest
to the most effient:
- \b thread: very slow factory using full featured threads (either
- ptheads or windows native threads)
+ ptheads or windows native threads)
- \b ucontext: fast factory using System V contexts (or a portability
layer of our own on top of Windows fibers)
- \b raw: amazingly fast factory using a context switching mecanism
- of our own, directly implemented in assembly (only available for x86
+ of our own, directly implemented in assembly (only available for x86
and amd64 platforms for now)
The only reason to change this setting is when the debuging tools get
\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. It is described in
+SimGrid v3.7 and higher. 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
primitives.
- \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
+ efficient synchronisation schema, but it loads all the cores of your
machine for no good reason. You probably prefer the other less
eager schemas.
impacts badly the simulation performance. It specify a threshold (in
second) under which the execution chunks are not reported to the
simulation kernel (default value: 1e-6). Please note that in some
-circonstances, this optimization can hinder the simulation accuracy.
+circonstances, this optimization can hinder the simulation accuracy.
\subsection options_smpi_timing Reporting simulation time
By default, when Ctrl-C is pressed, the status of all existing
simulated processes is displayed. This is very useful to debug your
-code, but it can reveal troublesome in some cases (such as when the
+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).
- \c network/bandwidth_factor: \ref options_model_network_coefs
- \c network/coordinates: \ref options_model_network_coord
-- \c network/crosstraffic: \ref options_model_network_crosstraffic
+- \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
\htmlinclude .platform.doc.toc
-In order to run any simulation, SimGrid needs 3 things: something to run
-(so, your code), a description of the platform on which you want to run your
+In order to run any simulation, SimGrid needs 3 things: something to run
+(so, your code), a description of the platform on which you want to run your
application, and finally it needs something to know where to deploy what.
For the latest 2 entries, you have basically 2 ways to give it as an input :
-\li You can program it, either using the Lua console (\ref MSG_Lua_funct) or if you're using MSG some
-of its platform and deployments functions(\ref msg_simulation). If you want to use it, please refer
+\li You can program it, either using the Lua console (\ref MSG_Lua_funct) or if you're using MSG some
+of its platform and deployments functions(\ref msg_simulation). If you want to use it, please refer
to its doc. (you can also check the section \ref pf_flexml_bypassing but this is strongly deprecated, as there is a new way to do it properly, but not yet documented).
-\li You can use two XML files: a platform description file and a deployment
+\li You can use two XML files: a platform description file and a deployment
description one.
-As the second one (deployment description) just consists of saying which
-process runs where and which arguments it should take as input, the easier way to
+As the second one (deployment description) just consists of saying which
+process runs where and which arguments it should take as input, the easier way to
understand how to write it is just to take a look at the examples. Here is an example of it:
\verbatim
\section pf_overview Some words about XML and DTD
-We choose to use XML because of some of its possibilities: if you're
-using an accurate XML editor, or simply using any XML plug-in for eclipse, it
+We choose to use XML because of some of its possibilities: if you're
+using an accurate XML editor, or simply using any XML plug-in for eclipse, it
will allow you to have cool stuff like auto-completion, validation and checking,
so all syntaxic errors may be avoided this way.
-the XML checking is done based on the dtd which is nowaday online at
+the XML checking is done based on the dtd which is nowaday online at
<a href="http://simgrid.gforge.inria.fr/simgrid.dtd">http://simgrid.gforge.inria.fr/simgrid.dtd</a>
while you might be tempted to read it, it will not help you that much.
If you read it, you should notice two or three important things :
\li The platform tags contains a version attributes. At the time of writing this doc
the current version is 3.
-\li The DTD contains definitions for the 2 files used by SimGrid (platform
+\li The DTD contains definitions for the 2 files used by SimGrid (platform
description and deployment).
\li There is a bunch of possibilities ! Let's see what's in it
Nowadays, the Internet is composed of a bunch of independently managed networks. Within each of those networks, there are entry and exit points (most of the time, you can both enter and exit through the same point) that allows to go out of the current network and reach other networks. At the upper level, these networks are known as <b>Autonomous System (AS)</b>, while at the lower level they are named sub-networks, or LAN. Indeed they are autonomous: routing is defined within the limits of his network by the administrator, and so, those networks can continue to operate without the existence of other networks. There are some rules to get out of networks by the entry points (or gateways). Those gateways allow you to go from a network to another one. Inside of each autonomous system, there is a bunch of equipments (cables, routers, switches, computers) that belong to the autonomous system owner.
-SimGrid platform description file relies exactly on the same concepts as real life platform. Every resource (computers, network equipments, and so on) belongs to an AS. Within this AS, you can define the routing you want between its elements (that's done with the routing model attribute and eventually with some \<route\> tag). You define AS by using ... well ... the \<AS\> tag. An AS can also contain some AS : AS allows you to define the hierarchy of your platform.
+SimGrid platform description file relies exactly on the same concepts as real life platform. Every resource (computers, network equipments, and so on) belongs to an AS. Within this AS, you can define the routing you want between its elements (that's done with the routing model attribute and eventually with some \<route\> tag). You define AS by using ... well ... the \<AS\> tag. An AS can also contain some AS : AS allows you to define the hierarchy of your platform.
Within each AS, you basically have the following type of resources:
\li <b>host</b>: an host, with cores in it, and so on
AS (or Autonomous System) is an organizational unit that contains resources and defines routing between them, and eventually some other AS. So it allows you to define a hierarchy into your platform. <b>*ANY*</b> resource <b>*MUST*</b> belong to an AS. There are a few attributes.
-<b>AS</b> attributes :
-\li <b>name (mandatory)</b>: the identifier of AS to be used when referring to it.
+<b>AS</b> attributes :
+\li <b>name (mandatory)</b>: the identifier of AS to be used when referring to it.
\li <b>routing (mandatory)</b>: the routing model used into it. By model we mean the internal way the simulator will manage routing. That also have a big impact on how many information you'll have to provide to help the simulator to route between the AS elements. <b>routing</b> possible values are <b>Full, Floyd, Dijkstra, DijkstraCache, none, RuleBased, Vivaldi, Cluster</b>. For more explanation about what to choose, take a look at the section devoted to it below.
Elements into an AS are basically resources (computers, network equipments) and some routing informations if necessary (see below for more explanation).
A <b>host</b> represents a computer, where you will be able to execute code and from which you can send and receive information. A host can contain more than 1 core. Here are the attributes of a host :
-<b>host</b> attributes :
+<b>host</b> attributes :
\li <b>id (mandatory)</b>: the identifier of the host to be used when referring to it.
\li <b>power (mandatory)</b>:the peak number FLOPS the CPU can manage. Expressed in flop/s.
\li <b>core</b>: The number of core of this host. If setted, the power gives the power of one core. The specified computing power will be available to up to 6 sequential
note that although sound, this model were never scientifically
assessed. Please keep this fact in mind when using it.
-\li <b>availability</b>: specify if the percentage of power available.
+\li <b>availability</b>: specify if the percentage of power available.
\li <b>availability_file</b>: Allow you to use a file as input. This file will contain availability traces for this computer. The syntax of this file is defined below. Possible values : absolute or relative path, syntax similar to the one in use on your system.
\li <b>state</b>: the computer state, as in : is that computer ON or OFF. Possible values : "ON" or "OFF".
\li <b>state_file</b>: Same mechanism as availability_file, similar syntax for value.
\li <b>coordinates</b>: you'll have to give it if you choose the vivaldi, coordinate-based routing model for the AS the host belongs to. More details about it in the P2P coordinate based section.
-An host can contain some <b>mount</b> that defines mounting points between some storage resource and the <b>host</b>. Please refer to the storage doc for more information.
+An host can contain some <b>mount</b> that defines mounting points between some storage resource and the <b>host</b>. Please refer to the storage doc for more information.
An host can also contain the <b>prop</b> tag. the prop tag allows you to define additional informations on this host following the attribute/value schema. You may want to use it to give information to the tool you use for rendering your simulation, for example.
<host id="host2" power="1000000000">
<prop id="color" value="blue"/>
<prop id="rendershape" value="square"/>
- </host>
+ </host>
\endverbatim
attribute and a separate text file whose syntax is exemplified below.
-<b>IMPORTANT NOTE:</b> the numeric separator in both trace and availability depends on your system locale. Examples below holds for LC_NUMERIC=C.
+<b>IMPORTANT NOTE:</b> the numeric separator in both trace and availability depends on your system locale. Examples below holds for LC_NUMERIC=C.
<b>Adding a trace file</b>
\verbatim
<platform version="1">
- <host id="bob" power="500000000"
+ <host id="bob" power="500000000"
availability_file="bob.trace" />
</platform>
\endverbatim
time 21.0 (20.0 plus the periodicity 1.0), we loop back to the
beginning and the host will deliver again 500~Mflop/s.
-<b>Changing initial state</b>
+<b>Changing initial state</b>
It is also possible to specify whether the host
is up or down by setting the <b>state</b> attribute to either <b>ON</b>
<b>Expliciting the default value "ON"</b>
\verbatim
<platform version="1">
- <host id="bob"
- power="500000000"
+ <host id="bob"
+ power="500000000"
state="ON" />
</platform>
\endverbatim
<b>Host switched off</b>
\verbatim
<platform version="1">
- <host id="bob"
- power="500000000"
+ <host id="bob"
+ power="500000000"
state="OFF" />
</platform>
\endverbatim
at which the host is turned on or off. An example of the content
of such a file is presented below.
<b>Adding a state file</b>
- \verbatim
+ \verbatim
<platform version="1">
- <host id="bob" power="500000000"
+ <host id="bob" power="500000000"
state_file="bob.fail" />
</platform>
\endverbatim
\subsubsection pf_cluster cluster
-A <b>cluster</b> represents a cluster. It is most of the time used when you want to have a bunch of machine defined quickly. It must be noted that cluster is meta-tag : <b>from the inner SimGrid point of view, a cluster is an AS where some optimized routing is defined</b> . The default inner organisation of the cluster is as follow :
+A <b>cluster</b> represents a cluster. It is most of the time used when you want to have a bunch of machine defined quickly. It must be noted that cluster is meta-tag : <b>from the inner SimGrid point of view, a cluster is an AS where some optimized routing is defined</b> . The default inner organisation of the cluster is as follow :
\verbatim
_________
| |
| router |
____________|__________|_____________ backbone
- | | | | | |
+ | | | | | |
l0| l1| l2| l97| l96 | | l99
| | | ........ | | |
| |
- c-0.me c-99.me
+ c-0.me c-99.me
\endverbatim
-You have a set of <b>host</b> defined. Each of them has a <b>link</b> to a central backbone (backbone is a <b>link</b> itsef, as a link can be used to represent a switch, see the switch or <b>link</b> section below for more details about it). A <b>router</b> gives a way to the <b>cluster</b> to be connected to the outside world. Internally, cluster is then an AS containing all hosts : the router is the default gateway for the cluster.
+You have a set of <b>host</b> defined. Each of them has a <b>link</b> to a central backbone (backbone is a <b>link</b> itsef, as a link can be used to represent a switch, see the switch or <b>link</b> section below for more details about it). A <b>router</b> gives a way to the <b>cluster</b> to be connected to the outside world. Internally, cluster is then an AS containing all hosts : the router is the default gateway for the cluster.
-There is an alternative organization, which is as follow :
+There is an alternative organization, which is as follow :
\verbatim
_________
| |
|__________|
/ | \
/ | \
- l0 / l1| \l2
+ l0 / l1| \l2
/ | \
/ | \
- host0 host1 host2
+ host0 host1 host2
\endverbatim
The principle is the same, except we don't have the backbone. The way to obtain it is simple : you just have to let bb_* attributes unsetted.
-<b>cluster</b> attributes :
+<b>cluster</b> attributes :
\li <b>id (mandatory)</b>: the identifier of the cluster to be used when referring to it.
\li <b>prefix (mandatory)</b>: each node of the cluster has to have a name. This is its prefix.
\li <b>suffix (mandatory)</b>: node suffix name.
\endverbatim
\subsubsection pf_peer peer
-A <b>peer</b> represents a peer, as in Peer-to-Peer (P2P). Basically, as cluster, <b>A PEER IS INTERNALLY INTERPRETED AS AN \<AS\></b>. It's just a kind of shortcut that does the following :
-\li It creates an host
+A <b>peer</b> represents a peer, as in Peer-to-Peer (P2P). Basically, as cluster, <b>A PEER IS INTERNALLY INTERPRETED AS AN \<AS\></b>. It's just a kind of shortcut that does the following :
+\li It creates an host
\li Two links : one for download and one for upload. This is convenient to use and simulate stuff under the last mile model (as ADSL peers).
\li It creates a gateway that serve as entry point for this peer zone. This router has coordinates.
-
-<b>peer</b> attributes :
+
+<b>peer</b> attributes :
\li <b>id (mandatory)</b>: the identifier of the peer to be used when referring to it.
\li <b>power CDATA (mandatory)</b>: as in host
\li <b>bw_in CDATA (mandatory)</b>: bandwidth in.
\subsection pf_ne Network equipments: links and routers
-You have basically two entities available to represent network entities :
+You have basically two entities available to represent network entities :
\li <b>link</b>: represents something that has a limited bandwidth, a latency, and that can be shared according to TCP way to share this bandwidth. <b>LINKS ARE NOT EDGES BUT HYPEREDGES</b>: it means that you can have more than 2 equipments connected to it.
\li <b>router</b>: represents something that one message can be routed to, but does not accept any code, nor have any influence on the performances (no bandwidth, no latency, not anything).<b>ROUTERS ARE ENTITIES (ALMOST) IGNORED BY THE SIMULATOR WHEN THE SIMULATION HAS BEGUN</b>. If you want to represent something like a switch, you must use <b>link</b> (see section below). Routers are used in order to run some routing algorithm and determine routes (see routing section for details).
let's see deeper what those entities hide.
\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 :
-
-<b>router</b> attributes :
+As said before, <b>router</b> is used only to give some information for routing algorithms. So, it does not have any attributes except :
+
+<b>router</b> attributes :
\li <b>id (mandatory)</b>: the identifier of the router to be used when referring to it.
\li <b>coordinates</b>: you'll have to give it if you choose the vivaldi, coordinate-based routing model for the AS the host belongs to. More details about it in the P2P coordinates based section.
<b>Expressing sharing policy</b>
By default a network link is SHARED, that is if more than one flow go through
-a link, each gets a share of the available bandwidth similar to the share TCP connections offers.
+a link, each gets a share of the available bandwidth similar to the share TCP connections offers.
Conversely if a link is defined as a FATPIPE, each flow going through this link will get all the available bandwidth, whatever the number of flows. The FATPIPE
-behavior allows to describe big backbones that won't affect performances (except latency). Finally a link can be considered as FULLDUPLEX, that means that in the simulator, 2 links (one named UP and the other DOWN) will be created for each link, so as the 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 <b>link_ctn</b> description.
+behavior allows to describe big backbones that won't affect performances (except latency). Finally a link can be considered as FULLDUPLEX, that means that in the simulator, 2 links (one named UP and the other DOWN) will be created for each link, so as the 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 <b>link_ctn</b> description.
\verbatim
<link id="SWITCH" bandwidth="125000000" latency="5E-5" sharing_policy="FATPIPE" />
<b>Example of "link1.bw" file</b>
\verbatim
-
+
1 PERIODICITY 12.0
2 4.0 40000000
3 8.0 60000000
interval, 1ms on [1, 2[, 10ms on [2, 3[, 1ms on [3,5[ (i.e., until the end of period). It then loops back, starting
at 100µs for one second.
-<b>link</b> attributes :
+<b>link</b> attributes :
\li <b>id (mandatory)</b>: the identifier of the link to be used when referring to it.
\li <b>bandwidth (mandatory)</b>: bandwidth for the link.
\li <b>lat </b>: latency for the link. Default is 0.0.
msg_file_management ; functions access are organized as a POSIX-like interface.
\subsubsection pf_sto_conc Storage Main concepts
-Basically there is 3 different entities to know :
+Basically there is 3 different entities to know :
\li the <b>storage_type</b>: here you define some kind of storage that you will instantiate many type on your platform. Think of it like a definition of throughput of a specific disk.
\li the <b>storage</b>: instance of a <b>storage_type</b>. Defines a new storage of <b>storage_type</b>
\li the <b>mount</b>: says that the storage is located into this specific resource.
\subsubsection pf_sto_sttp storage_type
-<b>storage_type</b> attributes :
+<b>storage_type</b> attributes :
\li <b>id (mandatory)</b>: the identifier of the storage_type to be used when referring to it.
\li <b>model (mandatory)</b>: Unused for now by the simulator (but mandatory, ok)
\li <b>content</b>: default value 0. The file containing the disk content. (may be moved soon or later to <b>storage</b> tag.
The tag must contains some predefined prop, as may do some other resources tags. This should moved to attributes soon or later.
-<b>storage_type</b> mandatory <b>prop</b> :
+<b>storage_type</b> mandatory <b>prop</b> :
\li <b>Bwrite</b>: value in B/s. Write throughput
\li <b>Bread</b>: value in B/s. Read throughput
\li <b>Bconnexion</b>: value in B/s. Connection throughput (i.e. the throughput of the storage connector).
\subsubsection pf_sto_st storage
-<b>storage_type</b> attributes :
+<b>storage_type</b> attributes :
\li <b>id (mandatory)</b>: the identifier of the storage to be used when referring to it.
\li <b>typeId (mandatory)</b>: the identifier of the storage_type that this storage belongs to.
\subsubsection pf_sto_mo mount
-<b>mount</b> attributes :
+<b>mount</b> attributes :
\li <b>id (mandatory)</b>: the id of the <b>storage</b> that must be mounted on that computer.
\li <b>name (mandatory)</b>: the name that will be the logical reference to this disk (the mount point).
\subsubsection pf_sto_mst mstorage
<b>Note : unused for now</b>
-<b>mstorage</b> attributes :
+<b>mstorage</b> attributes :
\li <b>typeId (mandatory)</b>: the id of the <b>storage</b> that must be mounted on that computer.
\li <b>name (mandatory)</b>: the name that will be the logical reference to this disk (the mount point).
\section pf_routing Routing
-In order to run fast, it has been chosen to use static routing within SimGrid. By static, it means that it is calculated once (or almost), and will not change during execution. We chose to do that because it is rare to have a real deficience of a resource ; most of the time, a communication fails because the links are too overloaded, and so your connection stops before the time out, or because the computer at the other end is not answering.
+In order to run fast, it has been chosen to use static routing within SimGrid. By static, it means that it is calculated once (or almost), and will not change during execution. We chose to do that because it is rare to have a real deficience of a resource ; most of the time, a communication fails because the links are too overloaded, and so your connection stops before the time out, or because the computer at the other end is not answering.
+
+We also chose to use shortests paths algorithms in order to emulate routing. Doing so is consistent with the reality: RIP, OSPF, BGP are all calculating shortest paths. They have some convergence time, but at the end, so when the platform is stable (and this should be the moment you want to simulate something using SimGrid) your packets will follow the shortest paths.
-We also chose to use shortests paths algorithms in order to emulate routing. Doing so is consistent with the reality: RIP, OSPF, BGP are all calculating shortest paths. They have some convergence time, but at the end, so when the platform is stable (and this should be the moment you want to simulate something using SimGrid) your packets will follow the shortest paths.
-
\subsection pf_rm Routing models
Within each AS, you have to define a routing model to use. You have basically 3 main kind of routing models :
\subsubsection pf_raf The router affair
-Expressing routers becomes mandatory when using shortest-path based models or when using ns-3 or the bindings to the GTNetS packet-level simulator instead of the native analytical network model implemented in SimGrid.
+Expressing routers becomes mandatory when using shortest-path based models or when using ns-3 or the bindings to the GTNetS packet-level simulator instead of the native analytical network model implemented in SimGrid.
-For graph-based shortest path algorithms, routers are mandatory, because both algorithms need a graph, and so we need to have source and destination for each edge.
+For graph-based shortest path algorithms, routers are mandatory, because both algorithms need a graph, and so we need to have source and destination for each edge.
Routers are naturally an important concept in GTNetS or ns-3 since the way they run the packet routing algorithms is actually simulated. Instead, the
SimGrid’s analytical models aggregate the routing time with the transfer time.
Rebuilding a graph representation only from the route information turns to be a very difficult task, because
of the missing information about how routes intersect. That is why we introduced a \<router\> tag, which is
simply used to express these intersection points. The only attribute accepted by this tag an id.
-It is important to understand that the \<router\> tag is only used to provide topological information.
+It is important to understand that the \<router\> tag is only used to provide topological information.
To express those topological information, some <b>route</b> have to be defined saying which link is between which routers. Description or the route syntax is given below, as well as example for the different models.
-\subsubsection pf_rm_sh Shortest-path based models
+\subsubsection pf_rm_sh Shortest-path based models
Here is the complete list of such models, that computes routes using classic shortest-paths algorithms. How to choose the best suited algorithm is discussed later in the section devoted to it.
\li <b>Floyd</b>: Floyd routing data. Pre-calculates all routes once.
\li <b>Dijkstra</b>: Dijkstra routing data ,calculating routes when necessary.
\li <b>DijkstraCache</b>: Dijkstra routing data. Handle some cache for already calculated routes.
-All those shortest-path models are instanciated the same way. Here are some example of it:
+All those shortest-path models are instanciated the same way. Here are some example of it:
-Floyd example :
+Floyd example :
\verbatim
<AS id="AS0" routing="Floyd">
-
+
<cluster id="my_cluster_1" prefix="c-" suffix=""
radical="0-1" power="1000000000" bw="125000000" lat="5E-5"
router_id="router1"/>
</AS>
<link id="link1" bandwidth="100000" latency="0.01"/>
-
+
<ASroute src="my_cluster_1" dst="AS1"
gw_src="router1"
gw_dst="host1">
<link_ctn id="link1"/>
</ASroute>
-
+
</AS>
\endverbatim
ASroute given at the end gives a topological information : link1 is between router1 and host1.
-Dijsktra example :
+Dijsktra example :
\verbatim
- <AS id="AS_2" routing="Dijsktra">
- <host id="AS_2_host1" power="1000000000"/>
- <host id="AS_2_host2" power="1000000000"/>
- <host id="AS_2_host3" power="1000000000"/>
- <link id="AS_2_link1" bandwidth="1250000000" latency="5E-4"/>
- <link id="AS_2_link2" bandwidth="1250000000" latency="5E-4"/>
- <link id="AS_2_link3" bandwidth="1250000000" latency="5E-4"/>
- <link id="AS_2_link4" bandwidth="1250000000" latency="5E-4"/>
+ <AS id="AS_2" routing="Dijsktra">
+ <host id="AS_2_host1" power="1000000000"/>
+ <host id="AS_2_host2" power="1000000000"/>
+ <host id="AS_2_host3" power="1000000000"/>
+ <link id="AS_2_link1" bandwidth="1250000000" latency="5E-4"/>
+ <link id="AS_2_link2" bandwidth="1250000000" latency="5E-4"/>
+ <link id="AS_2_link3" bandwidth="1250000000" latency="5E-4"/>
+ <link id="AS_2_link4" bandwidth="1250000000" latency="5E-4"/>
<router id="central_router"/>
<router id="AS_2_gateway"/>
- <!-- routes providing topological information -->
- <route src="central_router" dst="AS_2_host1"><link_ctn id="AS_2_link1"/></route>
- <route src="central_router" dst="AS_2_host2"><link_ctn id="AS_2_link2"/></route>
- <route src="central_router" dst="AS_2_host3"><link_ctn id="AS_2_link3"/></route>
- <route src="central_router" dst="AS_2_gateway"><link_ctn id="AS_2_link4"/></route>
+ <!-- routes providing topological information -->
+ <route src="central_router" dst="AS_2_host1"><link_ctn id="AS_2_link1"/></route>
+ <route src="central_router" dst="AS_2_host2"><link_ctn id="AS_2_link2"/></route>
+ <route src="central_router" dst="AS_2_host3"><link_ctn id="AS_2_link3"/></route>
+ <route src="central_router" dst="AS_2_gateway"><link_ctn id="AS_2_link4"/></route>
</AS>
\endverbatim
-DijsktraCache example :
+DijsktraCache example :
\verbatim
-<AS id="AS_2" routing="DijsktraCache">
- <host id="AS_2_host1" power="1000000000"/>
+<AS id="AS_2" routing="DijsktraCache">
+ <host id="AS_2_host1" power="1000000000"/>
...
(platform unchanged compared to upper example)
\endverbatim
-\subsubsection pf_rm_me Manually-entered route models
+\subsubsection pf_rm_me Manually-entered route models
\li <b>Full</b>: You have to enter all necessary routes manually
\li <b>RuleBased</b>: Rule-Based routing data; same as Full except you can use regexp to express route. As SimGrid has to evaluate the regexp, it's slower than Full, but requires less memory. Regexp syntax is similar as <a href="http://www.pcre.org">pcre</a> ones, as this is the lib SimGrid use to do so.
-Full example :
+Full example :
\verbatim
<AS id="AS0" routing="Full">
<host id="host1" power="1000000000"/>
</AS>
\endverbatim
-RuleBased example :
+RuleBased example :
\verbatim
<AS id="AS_orsay" routing="RuleBased" >
<cluster id="AS_gdx" prefix="gdx-" suffix=".orsay.grid5000.fr"
The example upper contains $1src and $1dst. It's simply a reference to string matching regexp enclosed by "()" within respectively <b>src</b> and <b>dst</b> attributes. If they were more than 1 "()", then you could referer to it as $2src, $3src and so on.
-\subsubsection pf_rm_sf Simple/fast models
+\subsubsection pf_rm_sf Simple/fast models
\li <b>none</b>: No routing (Unless you know what you are doing, avoid using this mode in combination with a non Constant network model).
None Example :
\subsection ps_dec Defining routes
-The principle of route definition is the same for the 4 available tags for doing it. Those for tags are:
+The principle of route definition is the same for the 4 available tags for doing it. Those for tags are:
\li <b>route</b>: to define route between host/router
\li <b>ASroute</b>: to define route between AS
\li <b>bypassRoute</b>: to bypass normal routes as calculated by the network model between host/router
\li <b>bypassASroute</b>: same as bypassRoute, but for AS
-Basically all those tags will contain an (ordered) list of references to link that compose the route you want to define.
+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:
+Consider the example below:
\verbatim
<route src="Alice" dst="Bob">
The route here fom host Alice to Bob will be first link1, then link2, and finally link3. What about the reverse route ? <b>route</b> and <b>ASroute</b> have an optional attribute <b>symmetrical</b>, that can be either YES or NO. YES means that the reverse route is the same route in the inverse order, and is setted to 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 ASroute, things are just sligthly more complicated, as you have to give the id of the gateway which is inside the AS you're talking about you want to access ... So it looks like this :
+For an ASroute, things are just sligthly more complicated, as you have to give the id of the gateway which is inside the AS you're talking about you want to access ... So it looks like this :
\verbatim
</ASroute>
\endverbatim
-gw == gateway, so when any message are trying to go from AS1 to AS2, it means that it must pass through router1 to get out of the AS, then pass through link1, and get into AS2 by being received by router2. router1 must belong to AS1 and router2 must belong to AS2.
+gw == gateway, so when any message are trying to go from AS1 to AS2, it means that it must pass through router1 to get out of the AS, then pass through link1, and get into AS2 by being received by router2. router1 must belong to AS1 and router2 must belong to AS2.
\subsubsection pf_linkctn link_ctn
a <b>link_ctn</b> is the tag that is used in order to reference a <b>link</b> in a route. Its id is the link id it refers to.
-<b>link_ctn</b> attributes :
+<b>link_ctn</b> attributes :
\li <b>id (mandatory)</b>: Id of the link this tag refers to
\li <b>direction</b>: if the link referenced by <b>id</b> has been declared as FULLDUPLEX, this is used to indicate in which direction the route you're defining is going through this link. Possible values "UP" or "DOWN".
ASroute tag purpose is to let people write manually their routes between AS. It's usefull when you're in Full or Rule-based model.
-<b>ASroute</b> attributes :
+<b>ASroute</b> attributes :
\li <b>src (mandatory)</b>: the source AS id.
\li <b>dst (mandatory)</b>: the destination AS id.
-\li <b>gw_src (mandatory)</b>: the gateway to be used within the AS. Can be any <b>host</b> or \b router defined into the \b src AS or into one of the AS it includes.
+\li <b>gw_src (mandatory)</b>: the gateway to be used within the AS. Can be any <b>host</b> or \b router defined into the \b src AS or into one of the AS it includes.
\li <b>gw_dst (mandatory)</b>: the gateway to be used within the AS. Can be any <b>host</b> or \b router defined into the \b dst AS or into one of the AS it includes.
\li <b>symmetrical</b>: if the route is symmetric, the reverse route will be the opposite of the one defined. Can be either YES or NO, default is YES.
<cluster id="my_cluster_1" prefix="c-" suffix=".me"
radical="0-149" power="1000000000" bw="125000000" lat="5E-5"
bb_bw="2250000000" bb_lat="5E-4"/>
-
+
<cluster id="my_cluster_2" prefix="c-" suffix=".me"
radical="150-299" power="1000000000" bw="125000000" lat="5E-5"
- bb_bw="2250000000" bb_lat="5E-4"/>
-
- <link id="backbone" bandwidth="1250000000" latency="5E-4"/>
-
- <ASroute src="my_cluster_1" dst="my_cluster_2"
- gw_src="c-my_cluster_1_router.me"
+ bb_bw="2250000000" bb_lat="5E-4"/>
+
+ <link id="backbone" bandwidth="1250000000" latency="5E-4"/>
+
+ <ASroute src="my_cluster_1" dst="my_cluster_2"
+ gw_src="c-my_cluster_1_router.me"
gw_dst="c-my_cluster_2_router.me">
<link_ctn id="backbone"/>
- </ASroute>
- <ASroute src="my_cluster_2" dst="my_cluster_1"
- gw_src="c-my_cluster_2_router.me"
+ </ASroute>
+ <ASroute src="my_cluster_2" dst="my_cluster_1"
+ gw_src="c-my_cluster_2_router.me"
gw_dst="c-my_cluster_1_router.me">
<link_ctn id="backbone"/>
- </ASroute>
+ </ASroute>
</AS>
\endverbatim
The principle is the same as ASroute : <b>route</b> contains list of links that are in the path between src and dst, except that it is for routes between a src that can be either <b>host</b> or \b router and a dst that can be either <b>host</b> or \b router. Usefull for Full and RuleBased, as well as for the shortest-paths based models, where you have to give topological informations.
-<b>route</b> attributes :
+<b>route</b> attributes :
\li <b>src (mandatory)</b>: the source id.
\li <b>dst (mandatory)</b>: the destination id.
\li <b>symmetrical</b>: if the route is symmetric, the reverse route will be the opposite of the one defined. Can be either YES or NO, default is YES.
<b>Note : bypassASroute and bypassRoute are under rewriting to perform better ; so you may not use it yet</b>
As said before, once you choose a model, it (if so) calculates routes for you. But maybe you want to define some of your routes, which will be specific. You may also want to bypass some routes defined in lower level AS at an upper stage : <b>bypassASroute</b> is the tag you're looking for. It allows to bypass routes defined between already defined between AS (if you want to bypass route for a specific host, you should just use byPassRoute). The principle is the same as ASroute : <b>bypassASroute</b> contains list of links that are in the path between src and dst.
-<b>bypassASroute</b> attributes :
+<b>bypassASroute</b> attributes :
\li <b>src (mandatory)</b>: the source AS id.
\li <b>dst (mandatory)</b>: the destination AS id.
-\li <b>gw_src (mandatory)</b>: the gateway to be used within the AS. Can be any <b>host</b> or \b router defined into the \b src AS or into one of the AS it includes.
+\li <b>gw_src (mandatory)</b>: the gateway to be used within the AS. Can be any <b>host</b> or \b router defined into the \b src AS or into one of the AS it includes.
\li <b>gw_dst (mandatory)</b>: the gateway to be used within the AS. Can be any <b>host</b> or \b router defined into the \b dst AS or into one of the AS it includes.
\li <b>symmetrical</b>: if the route is symmetric, the reverse route will be the opposite of the one defined. Can be either YES or NO, default is YES.
<b>bypassASroute Example</b>
\verbatim
<bypassASRoute src="my_cluster_1" dst="my_cluster_2"
- gw_src="my_cluster_1_router"
+ gw_src="my_cluster_1_router"
gw_dst="my_cluster_2_router">
- <link_ctn id="link_tmp"/>
+ <link_ctn id="link_tmp"/>
</bypassASroute>
\endverbatim
<b>Note : bypassASRoute and bypassRoute are under rewriting to perform better ; so you may not use it yet</b>
As said before, once you choose a model, it (if so) calculates routes for you. But maybe you want to define some of your routes, which will be specific. You may also want to bypass some routes defined in lower level AS at an upper stage : <b>bypassRoute</b> is the tag you're looking for. It allows to bypass routes defined between <b>host/router</b>. The principle is the same as route : <b>bypassRoute</b> contains list of links references of links that are in the path between src and dst.
-<b>bypassRoute</b> attributes :
+<b>bypassRoute</b> attributes :
\li <b>src (mandatory)</b>: the source AS id.
\li <b>dst (mandatory)</b>: the destination AS id.
\li <b>symmetrical</b>: if the route is symmetric, the reverse route will be the opposite of the one defined. Can be either YES or NO, default is YES.
<b>bypassRoute Example</b>
\verbatim
<bypassRoute src="host_1" dst="host_2">
- <link_ctn id="link_tmp"/>
+ <link_ctn id="link_tmp"/>
</bypassRoute>
\endverbatim
\subsection pb_baroex Basic Routing Example
-Let's say you have an AS named AS_Big that contains two other AS, AS_1 and AS_2. If you want to make an host (h1) from AS_1 with another one (h2) from AS_2 then you'll have to proceed as follow:
+Let's say you have an AS named AS_Big that contains two other AS, AS_1 and AS_2. If you want to make an host (h1) from AS_1 with another one (h2) from AS_2 then you'll have to proceed as follow:
\li First, you have to ensure that a route is defined from h1 to the AS_1's exit gateway and from h2 to AS_2's exit gateway.
\li Then, you'll have to define a route between AS_1 to AS_2. As those AS are both resources belonging to AS_Big, then it has to be done at AS_big level. To define such a route, you have to give the source AS (AS_1), the destination AS (AS_2), and their respective gateway (as the route is effectively defined between those two entry/exit points). Elements of this route can only be elements belonging to AS_Big, so links and routers in this route should be defined inside AS_Big. If you choose some shortest-path model, this route will be computed automatically.
\verbatim
<AS id="AS_Big" routing="Dijsktra">
- <AS id="AS_1" routing="Full">
- <host id="AS_1_host1" power="1000000000"/>
- <link id="AS_1_link" bandwidth="1250000000" latency="5E-4"/>
+ <AS id="AS_1" routing="Full">
+ <host id="AS_1_host1" power="1000000000"/>
+ <link id="AS_1_link" bandwidth="1250000000" latency="5E-4"/>
<router id="AS_1_gateway"/>
<route src="AS_1_host1" dst="AS_1_gateway">
<link_ctn id="AS_1_link"/>
- </route>
+ </route>
</AS>
- <AS id="AS_2" routing="Floyd">
- <host id="AS_2_host1" power="1000000000"/>
- <host id="AS_2_host2" power="1000000000"/>
- <host id="AS_2_host3" power="1000000000"/>
- <link id="AS_2_link1" bandwidth="1250000000" latency="5E-4"/>
- <link id="AS_2_link2" bandwidth="1250000000" latency="5E-4"/>
- <link id="AS_2_link3" bandwidth="1250000000" latency="5E-4"/>
- <link id="AS_2_link4" bandwidth="1250000000" latency="5E-4"/>
+ <AS id="AS_2" routing="Floyd">
+ <host id="AS_2_host1" power="1000000000"/>
+ <host id="AS_2_host2" power="1000000000"/>
+ <host id="AS_2_host3" power="1000000000"/>
+ <link id="AS_2_link1" bandwidth="1250000000" latency="5E-4"/>
+ <link id="AS_2_link2" bandwidth="1250000000" latency="5E-4"/>
+ <link id="AS_2_link3" bandwidth="1250000000" latency="5E-4"/>
+ <link id="AS_2_link4" bandwidth="1250000000" latency="5E-4"/>
<router id="central_router"/>
<router id="AS_2_gateway"/>
- <!-- routes providing topological information -->
- <route src="central_router" dst="AS_2_host1"><link_ctn id="AS_2_link1"/></route>
- <route src="central_router" dst="AS_2_host2"><link_ctn id="AS_2_link2"/></route>
- <route src="central_router" dst="AS_2_host3"><link_ctn id="AS_2_link3"/></route>
- <route src="central_router" dst="AS_2_gateway"><link_ctn id="AS_2_link4"/></route>
+ <!-- routes providing topological information -->
+ <route src="central_router" dst="AS_2_host1"><link_ctn id="AS_2_link1"/></route>
+ <route src="central_router" dst="AS_2_host2"><link_ctn id="AS_2_link2"/></route>
+ <route src="central_router" dst="AS_2_host3"><link_ctn id="AS_2_link3"/></route>
+ <route src="central_router" dst="AS_2_gateway"><link_ctn id="AS_2_link4"/></route>
</AS>
- <link id="backbone" bandwidth="1250000000" latency="5E-4"/>
+ <link id="backbone" bandwidth="1250000000" latency="5E-4"/>
- <ASroute src="AS_1" dst="AS_2"
- gw_src="AS_1_gateway"
+ <ASroute src="AS_1" dst="AS_2"
+ gw_src="AS_1_gateway"
gw_dst="AS_2_gateway">
<link_ctn id="backbone"/>
- </ASroute>
+ </ASroute>
</AS>
\endverbatim
There are 3 tags, that you can use inside a \<platform\> tag that are not describing the platform:
\li random: it allows you to define random generators you want to use for your simulation.
-\li config: it allows you to pass some configuration stuff like, for example, the network model and so on. It follows the
+\li config: it allows you to pass some configuration stuff like, for example, the network model and so on. It follows the
\li include: simply allows you to include another file into the current one.
\subsection pf_conf config
-<b>config</b> attributes :
+<b>config</b> attributes :
\li <b>id (mandatory)</b>: the identifier of the config to be used when referring to it.
\verbatim
<?xml version='1.0'?>
<!DOCTYPE platform SYSTEM "http://simgrid.gforge.inria.fr/simgrid.dtd">
-<platform version="3">
+<platform version="3">
<config id="General">
<prop id="maxmin/precision" value="0.000010"></prop>
<prop id="cpu/optim" value="TI"></prop>
<prop id="path" value="~/"></prop>
<prop id="smpi/bw_factor" value="65472:0.940694;15424:0.697866;9376:0.58729"></prop>
</config>
-
+
<AS id="AS0" routing="Full">
...
\endverbatim
\subsection pf_incl include
<b>include</b> tag allows to import into a file platform parts located in another file. This is done with the intention to help people combine their different AS and provide new platforms. Those files should contains XML part that contains either <b>include,cluster,peer,AS,trace,trace_connect</b> tags.
-<b>include</b> attributes :
+<b>include</b> attributes :
\li <b>file (mandatory)</b>: filename of the file to include. Possible values : absolute or relative path, syntax similar to the one in use on your system.
-<b>Note</b> : due to some obscure technical reasons, you have to open and close tag in order to let it work.
+<b>Note</b> : due to some obscure technical reasons, you have to open and close tag in order to let it work.
<b>include Example</b>
\verbatim
<?xml version='1.0'?>
\verbatim
<AS id="AS0" routing="Full">
- <host id="bob" power="1000000000"/>
+ <host id="bob" power="1000000000"/>
</AS>
<trace id="myTrace" file="bob.trace" periodicity="1.0"/>
<trace_connect trace="myTrace" element="bob" kind="POWER"/>
\endverbatim
-All constraints you have is that <b>trace_connect</b> is after <b>trace</b> and <b>host</b> definitions.
+All constraints you have is that <b>trace_connect</b> is after <b>trace</b> and <b>host</b> definitions.
-<b>trace</b> attributes :
+<b>trace</b> attributes :
\li <b>id (mandatory)</b>: the identifier of the trace to be used when referring to it.
\li <b>file</b>: filename of the file to include. Possible values : absolute or relative path, syntax similar to the one in use on your system. If ommited, the system expects that you provide the trace values inside the trace tags (see below).
\li <b>trace periodicity (mandatory)</b>: trace periodicity, same definition as in hosts (see upper for details).
-Here is an example of trace when no file name is provided:
+Here is an example of trace when no file name is provided:
\verbatim
<trace id="myTrace" periodicity="1.0">
</trace>
\endverbatim
-<b>trace_connect</b> attributes :
+<b>trace_connect</b> attributes :
\li <b>kind</b>: the type of trace, possible values <b>HOST_AVAIL|POWER|LINK_AVAIL|BANDWIDTH|LATENCY,</b> default: <b>HOST_AVAIL</b>
\li <b>trace (mandatory)</b>: the identifier of the trace referenced.
\li <b>element (mandatory)</b>: the identifier of the entity referenced.
Now you should know at least the syntax dans be able to create a platform. However, after having ourselves wrote some platforms, there are some best practices you should pay attention to in order to produce good platform and some choices you can make in order to have faster simulations. Here's some hints and tips, then.
-\subsection pf_as_h AS Hierarchy
+\subsection pf_as_h AS Hierarchy
The AS design allows SimGrid to go fast, because computing route is done only for the set of resources defined in this AS. If you're using only a big AS containing all resource with no AS into it and you're using Full model, then ... you'll loose all interest into it. On the other hand, designing a binary tree of AS with, at the lower level, only one host, then you'll also loose all the good AS hierarchy can give you. Remind you should always be "reasonable" in your platform definition when choosing the hierarchy. A good choice if you try to describe a real life platform is to follow the AS described in reality, since this kind og trade-off works well for real life platforms.
\subsection pf_exit_as Exit AS: why and how
-Users that have looked at some of our platforms may have notice a non-intuitive schema ... Something like that :
+Users that have looked at some of our platforms may have notice a non-intuitive schema ... Something like that :
\verbatim
</AS>
\endverbatim
-In the AS_4, you have an exitAS_4 defined, containing only one router, and routes defined to that AS from all other AS (as cluster is only a shortcut for an AS, see cluster description for details). If there was an upper AS, it would define routes to and from AS_4 with the gateway router_4. It's just because, as we did not allowed (for performances issues) to have routes from an AS to a single host/router, you have to enclose your gateway, when you have AS included in your AS, within an AS to define routes to it.
+In the AS_4, you have an exitAS_4 defined, containing only one router, and routes defined to that AS from all other AS (as cluster is only a shortcut for an AS, see cluster description for details). If there was an upper AS, it would define routes to and from AS_4 with the gateway router_4. It's just because, as we did not allowed (for performances issues) to have routes from an AS to a single host/router, you have to enclose your gateway, when you have AS included in your AS, within an AS to define routes to it.
\subsection pf_P2P_tags P2P or how to use coordinates
<?xml version='1.0'?>
<!DOCTYPE platform SYSTEM "http://simgrid.gforge.inria.fr/simgrid.dtd">
<platform version="3">
-
+
<config id="General">
<prop id="network/coordinates" value="yes"></prop>
-</config>
+</config>
<AS id="AS0" routing="Vivaldi">
<host id="100030591" coordinates="25.5 9.4 1.4" power="1500000000.0" />
<host id="100036570" coordinates="-12.7 -9.9 2.1" power="730000000.0" />
declare (such as <route src="A" dst="C"><link_ctn
id="3"/></route>), without trying to build new routes by aggregating
the provided ones.
-
+
You are also free to declare platform where the routing is not
symmetric. For example, add the following to the previous file:
surfxml_add_callback(STag_surfxml_route_cb_list, &parse_route_set_endpoints);
surfxml_add_callback(ETag_surfxml_link_c_ctn_cb_list, &parse_route_elem);
surfxml_add_callback(ETag_surfxml_route_cb_list, &parse_route_set_route);
-
+
/* Parse the file */
surf_parse_open(file);
xbt_assert(!surf_parse(), "Parse error in %s", file);
surf_parse_close();
\endverbatim
-
+
So, to bypass the FleXML parser, you need to write your own version of the
surf_parse function, which should do the following:
- Fill the A_<tag>_<attribute> variables with the wanted values
instead of the default flow-based simulation. You may want to use such
an approach if you have doubts about the validity of the default model
or if you want to perform some validation experiments. At the moment,
-we support the GTNetS simulator and since version 3.6.2, ns-3.
+we support the GTNetS simulator and since version 3.6.2, ns-3.
\section pls_simgrid_configuration_gtnets Using GTNetS
<i>
-To enable GTNetS model inside SimGrid it is needed to patch the GTNetS simulator source code
+To enable GTNetS model inside SimGrid it is needed to patch the GTNetS simulator source code
and build/install it from scratch
</i>
\verbatim
unzip gtnets-current.zip
-tar zxvf gtnets-current-patch.tgz
+tar zxvf gtnets-current-patch.tgz
cd gtnets-current
cat ../00*.patch | patch -p1
\endverbatim
- <b>Compile GTNetS</b>
- Due to portability issues it is possible that GTNetS does not compile in your architecture. The patches furnished in SimGrid SVN repository are intended for use in Linux architecture only. Unfortunately, we do not have the time, the money, neither the manpower to guarantee GTNetS portability. We advice you to use one of GTNetS communication channel to get more help in compiling GTNetS.
+ Due to portability issues it is possible that GTNetS does not compile in your architecture. The patches furnished in SimGrid SVN repository are intended for use in Linux architecture only. Unfortunately, we do not have the time, the money, neither the manpower to guarantee GTNetS portability. We advice you to use one of GTNetS communication channel to get more help in compiling GTNetS.
\verbatim
- <b>Enable GTNetS support in SimGrid</b>
-
+
In order to enable gtnets with simgrid you have to give where is gtnets. (path to \<gtnets_path\>/lib and \<gtnets_path\>/include)
\verbatim
\endverbatim
- <b>Once you have followed all the instructions for compiling and
- installing successfully you can activate this feature at
+ installing successfully you can activate this feature at
runntime with the following options:</b>
\verbatim
gtnets/gtnets gtnets/onelink-p.xml gtnets/onelink-d.xml --cfg=network_model:GTNets
\endverbatim
-
- A long version of this <a href="http://gforge.inria.fr/docman/view.php/12/6283/GTNetS HowTo.html">HowTo</a> it is available
+
+ A long version of this <a href="http://gforge.inria.fr/docman/view.php/12/6283/GTNetS HowTo.html">HowTo</a> it is available
More about GTNetS simulator at <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/index.html">GTNetS Website</a>
- <b>DISCLAIMER</b>
- The patches provided by us worked successfully with GTNetS found
- <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/software/gtnets-current.zip">here</a>,
+ The patches provided by us worked successfully with GTNetS found
+ <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/software/gtnets-current.zip">here</a>,
dated from 12th June 2008. Due to the discontinuing development of
GTNetS it is impossible to precise a version number. We STRONGLY recommend you
to download and install the GTNetS version found in SimGrid repository as explained above.
\section pls_simgrid_configuration_ns3 Using NS3
It is possible to use discrete-event network simulator <a href="http://www.nsnam.org/">(ns-3)</a> for Internet systems
-instead of the default one.
+instead of the default one.
-A ns-3 platform is created according to the platform file you provide in SimGrid format. However from this configuration, we had to set up some extra parameters :
+A ns-3 platform is created according to the platform file you provide in SimGrid format. However from this configuration, we had to set up some extra parameters :
<ul>
<li>
</li>
<li>
-Third, we also choose to restrict the way your platform is built : end hosts cannot have more than one interface card (so, only one <link> in your SimGrid platform should link
-an end host to the platform ; if not, your end host will be considered as a router.
+Third, we also choose to restrict the way your platform is built : end hosts cannot have more than one interface card (so, only one <link> in your SimGrid platform should link
+an end host to the platform ; if not, your end host will be considered as a router.
</li>
</ul>
\endverbatim
After install ns-3 you should have directories into your "ns-3_install_directory":
- \li include/ns3/
- \li lib/
+ \li include/ns3/
+ \li lib/
\li bin/ (with 3.12)
-
+
You also need to add to the LD_LIBRARY_PATH : "ns-3_install_directory/lib".
- <b>Enable ns-3 support on SimGrid</b>
Compiler: c : /usr/bin/gcc
version: 4.6.1
- CFlags : -O3 -finline-functions -funroll-loops -fno-strict-aliasing -L/usr/lib/x86_64-linux-gnu -I/usr/include
+ CFlags : -O3 -finline-functions -funroll-loops -fno-strict-aliasing -L/usr/lib/x86_64-linux-gnu -I/usr/include
-L/home/navarrop/Install/ns3-3.10/lib -I/home/navarrop/Install/ns3-3.10/include -g3 -D_NS3_3_10
- CPPFlags: -I/home/navarrop/Install/ns3-3.10/include -L/home/navarrop/Install/ns3-3.10/lib
+ CPPFlags: -I/home/navarrop/Install/ns3-3.10/include -L/home/navarrop/Install/ns3-3.10/lib
Compile Gtnets : 0
Compile NS-3 : 1 ---------------------> Be sure this option is "1" otherwise ns-3 is not activated
- Gtnets path :
+ Gtnets path :
NS-3 path : /home/navarrop/Install/ns3-3.10
- Compile Lua :
+ Compile Lua :
Compile Smpi : OFF
Compile Static : OFF
Compile pcre : AUTO
Tracing mode : OFF
Jedule mode : OFF
Latency bound : OFF
- Graphviz mode :
+ Graphviz mode :
Simgrid dependencies: -lm -lpcre -lpthread -lns3 -lrt
Gras dependencies : -lm -lpthread -lrt
- Smpi dependencies :
+ Smpi dependencies :
INSTALL_PREFIX: /usr/local
-- Configuring done
options accepted by the tracing system of SimGrid as of today, 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.
--cfg=tracing:1
\endverbatim
-\li <b>\c
+\li <b>\c
tracing/categorized
</b>:
It activates the categorized resource utilization tracing. It should
--cfg=tracing/categorized:1
\endverbatim
-\li <b>\c
+\li <b>\c
tracing/uncategorized
</b>:
It activates the uncategorized resource utilization tracing. Use it if
--cfg=tracing/uncategorized:1
\endverbatim
-\li <b>\c
+\li <b>\c
tracing/filename
</b>:
A file with this name will be created to register the simulation. The file
--cfg=tracing/onelink_only:1
\endverbatim
-\li <b>\c
+\li <b>\c
tracing/smpi
</b>:
This option only has effect if this simulator is SMPI-based. Traces the MPI
--cfg=tracing/smpi:1
\endverbatim
-\li <b>\c
+\li <b>\c
tracing/smpi/group
</b>:
This option only has effect if this simulator is SMPI-based. The processes
--cfg=tracing/smpi/group:1
\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
--cfg=tracing/disable_destroy:1
\endverbatim
-\li <b>\c
+\li <b>\c
triva/categorized
</b>:
This option generates a graph configuration file for Triva considering
--cfg=triva/categorized:graph_categorized.plist
\endverbatim
-\li <b>\c
+\li <b>\c
triva/uncategorized
</b>:
This option generates a graph configuration file for Triva considering
special configurations tunned to SimGrid needs. This part of the documentation
explains how to configure and use Triva to analyse a SimGrid trace file.
-- <b>Installing Triva</b>: the tool is available in the Inria's Forge,
+- <b>Installing Triva</b>: the tool is available in the Inria's Forge,
at <a href="http://triva.gforge.inria.fr">http://triva.gforge.inria.fr</a>.
Use the following command to get the sources, and then check the file
<i>INSTALL</i>. This file contains instructions to install
--gc_apply Apply the configuration
--gc_hide Hide the GraphConfiguration window
\endverbatim
-Triva expects that the user choose one of the available options
+Triva expects that the user choose one of the available options
(currently <em>--graph</em> or <em>--treemap</em> for a visualization analysis)
and the trace file from the simulation.
the end (that depends on the time simulated by SimGrid). The middle of the
window, in the square named <i>Time Slice Configuration</i>, contains the
aspects related to the time-slice, including its <i>start</i> and its
-<i>size</i>. The gray rectangle in the bottom of this part indicates the
-<i>current time-slice</i> that is considered for the drawings. If the checkbox
+<i>size</i>. The gray rectangle in the bottom of this part indicates the
+<i>current time-slice</i> that is considered for the drawings. If the checkbox
<i>Update Drawings on Sliders Change</i> is not selected, the button
<i>Apply</i> must be clicked in order to inform triva that the
new time-slice must be considered. The bottom part of the window, in the space
For <em>LINK</em> we have:
-\verbatim
+\verbatim
LINK = {
type = rhombus;
size = bandwidth;
a look at the following presentation first to get the basic concepts.
Afterward, you probably want to proceed to the \ref MSG_API. Of
course, if you're curious or if you know what you want, you may prefer
-to go to \ref SMPI_API, or even \ref GRAS_API.
+to go to \ref SMPI_API, or even \ref GRAS_API.
The scientific bases of the SimGrid project are presented in a 3 ou 4
hours-long tutorial. It can be found at the following locations.
\includepdf[nup=2x4,pages=1-]{../webcruft/simgrid-101.pdf}
\endlatexonly
-\htmlonly
+\htmlonly
<script language="javascript">
var base="simgrid-101",max=30,cur=1;
function pad(){ return cur < 10 ? '00' + cur : cur < 100 ? '0' + cur : '' + cur; }
</script>
<div id='blah' style='text-align:center;'>
- <div id='practical-simgrid' >
+ <div id='practical-simgrid' >
<img src='simgrid-101_001.png' id="display" onclick='slidemove(1)'/>
<br/>
<form>
<span id="nums">1/30</span>  
<input type='button' value='Next »' onclick="slidemove(1)"/>
- <br/>
+ <br/>
<a href='simgrid-101.pdf'>Download PDF version</a>
- </form>
+ </form>
</div>
</div>
-\endhtmlonly
+\endhtmlonly
*/
\ No newline at end of file
