SimGrid 3.7.1
Scalable simulation of distributed systems
|
Any GRAS project should be constituted of at least 3 files, and possibly much more.
<project>.c
: A source file providing the source code of your processes.<platform>.xml
: 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.<project>.xml
: A deployment file. It describes which of your processes to start, on which machine and with which arguments.If we start a project called test
, we have to write 3 files: test.c
, platform.xml
and test.xml
Let's look at the C source file first. It should contain one main function for each type of processes in your overlay. Let's assume that you want to code a simple client/server communication. For this, the source file should read as:
#include <gras.h> int client(int argc, char *argv[]) { ... } int server(int argc, char *argv[]) { ... }
Note that each of the processes's main function have the exact same prototype of the classical main()
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 run as threads within the same regular process in simulation mode. That is why the real main
function of GRAS programs are generated automatically. This will be detailled in time (section Glueing things together), but for now just note the similarity between the "main" functions you have to write for each processes and a "real main" function.
Then, each process must initialize the GRAS framework at the beginning (with gras_init) and should finalize it at the end (with gras_exit).
You should pass to gras_init the argc
and argv
you received in your "main" function so that the users of your application can pass some configuration flags to the framework.
It is not enough to have one of the processes initializing the framework since in RL, each of them will run on a different host. If you use some AMOK modules, you have to initialize them in each process too.
The source file then reads:
/* Copyright (c) 2006, 2010. The SimGrid Team. * All rights reserved. */ /* This program is free software; you can redistribute it and/or modify it * under the terms of the license (GNU LGPL) which comes with this package. */ #include <gras.h> int client(int argc, char *argv[]) { gras_init(&argc, argv); /* Your own code for the client process */ gras_exit(); return 0; } int server(int argc, char *argv[]) { gras_init(&argc, argv); /* Your own code for the server process */ gras_exit(); return 0; }
That's it. You have a working GRAS application with two processes. They don't do anything useful, but that's a beginning. Let's see how to bring them to life.
The platform file is used by the simulator to know about the existing hosts and their interactions. Its exact syntax is at the same time very simple and a bit beyond the topic of this document. Here is a very simple example describin two hosts named Jacquelin and Boivin and how they are interconnected.
<?xml version='1.0'?> <!DOCTYPE platform SYSTEM "http://simgrid.gforge.inria.fr/simgrid.dtd"> <platform version="3"> <AS id="AS0" routing="Full"> <host id="Jacquelin" power="137333000"/> <host id="Boivin" power="98095000"/> <link id="1" bandwidth="3430125" latency="0.000536941"/> <route src="Jacquelin" dst="Boivin"><link_ctn id="1"/></route> <route src="Boivin" dst="Jacquelin"><link_ctn id="1"/></route> </AS> </platform>
At this point, you should not try to write your own platform file, but use one of the existing ones. There is a few of them in the examples/msg directory of the project. The only information we need from those files are the names of the existing hosts. It will be mandatory to write the deployment file.
This file explains which of your processes should be started on the different hosts. It is mainly used in simulation. In real life, you will have to start your processes manually (see below). We we dream of a system able to apply a deployment file in real life and TakTuk may be the right tool for this, but this is still to be done.
Here is an example of such file, describing that a server
process must be started onto the Jacquelin
host and a client
process must be started on the Boivin
host.
<?xml version='1.0'?> <!DOCTYPE platform SYSTEM "http://simgrid.gforge.inria.fr/simgrid.dtd"> <platform version="3"> <process host="Jacquelin" function="server" /> <process host="Boivin" function="client" /> </platform>
Actually, you should write such a file also if you only plan to use GRAS in RL since this file is also used to glue your code to GRAS, as explained in the next section.
As explained above, you shouldn't write any real main
function since its content depends on whether you run in RL ou in SG. Instead, you use a tool gras_stub_generator
to get the proper glue around your code generated. If you installed SimGrid in a regular place, this program is now in your path. Its source resides in the tools/gras/ directory of the archive, if you wonder.
Here is the calling syntax:
gras_stub_generator <project_name> <deployment_file.xml>
It parses the deployment file (called test.xml
in our example), searching for all the kind of processes you have in your project. It then generates the following C files:
_<project_name>_<process_kind>.c
file for each process kind you have._<project_name>_simulator.c
file.<project_name>.mk
file.In our example, we will thus obtain _test_server.c
, _test_client.c
, _test_simulator.c
and test.mk
.
There is a pitfall: no verification is made on your actual source code, so if you have a typo on the process name in the deployment file, the generated code will be wrong, and the linker will spit error messages at you. Also remember that those names are in fact C function names, so they are case-sensitive.
Now, we want to compile all the source files to build the actual binaries. It can be done manually, but it is much more convenient to use a makefile. Fortunately, gras_stub_generator generates a makefile for you under the name <project>.mk
. This file is sufficient for now. To compile our test application, just type:
make -f test.mk
You may want to rename this file to Makefile so that typing make
without argument becomes sufficient. In any case, do not edit this file without renaming it, or your changes will get overwritten at the next glue generation.
If you already have a Makefile (or a Makefile.am for automake users), you can also add the following chunk at the end of your file:
NAME=your_project_name PROCESSES=list of processes type in your project $(foreach proc, $(PROCESSES), _$(NAME)_$(proc).c) _$(NAME)_simulator.c: $(NAME).c $(NAME)_deployment.xml path/to/gras_stub_generator $(NAME) $(NAME)_deployment.xml >/dev/null
A simpler solution in our example would be to add:
_test_client.c _test_server.c _test_simulator.c: test.c test.xml path/to/gras_stub_generator test test.xml >/dev/null
There is nothing to know to start your processes in RL. Simply call the generated binaries, and that's it. To start the simulation, simply call:
./<project>_simulator platform.xml deployment.xml
If you have an error message similar to
./<project>_simulator: error while loading shared libraries: libsimgrid.so.2: cannot open shared object file: No such file or directory
it simply means that the dynamic linker of you system fails to find the simgrid library. The easiest way to solve this is to declare a LD_LIBRARY_PATH shell variable pointing to the directory where your library lives (that's /opt/simgrid/lib on my machine because I passed --prefix=/opt/simgrid to the configure script).
Here is an example of execution:
$ ./test_client [arthur:client:(28729) 0.000011] [gras/INFO] Exiting GRAS $ ./test_server [arthur:server:(28733) 0.000012] [gras/INFO] Exiting GRAS $ $ ./test_simulator platform.xml test.xml [Jacquelin:server:(1) 0.000000] [gras/INFO] Exiting GRAS [Boivin:client:(2) 0.000000] [gras/INFO] Exiting GRAS $
That's it. You are done with this lesson and can now write, build and execute GRAS applications as long as they don't do anything ;) Move to the next lessons to add some flesh on these bones.
Back to the main Simgrid Documentation page |
The version of SimGrid documented here is v3.7.1. Documentation of other versions can be found in their respective archive files (directory doc/html). |
Generated by ![]() |