SimGrid  3.7
Scalable simulation of distributed systems
Lesson 1: Setting up your own project

Table of Contents


Any GRAS project should be constituted of at least 3 files, and possibly much more.

If we start a project called test, we have to write 3 files: test.c, platform.xml and test.xml

The C source file

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

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.

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.

Glueing things together

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:

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.

A typical Makefile

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

Actually running the processes

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.

Go to Lesson 2: Exchanging simple messages


Back to the main Simgrid Documentation page The version of SimGrid documented here is v3.7.
Documentation of other versions can be found in their respective archive files (directory doc/html).
Generated by doxygen