SimGrid: Bindings

SimGrid 3.10 Versatile Simulation of Distributed Systems

- Home page
- Online documentation
- Dev's Corner

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Bindings

# Ruby Binding

Check online for our specific Simgrid-Ruby documentation.

# Java Binding

Simgrid-java is a java API that let you use Simgrid MSG API in your favorite language (java). Without it, you would be forced to use C or one of the other bindings provided.

MSG was the first distributed programming environment provided within SimGrid. While almost realistic, it remains quite simple. This describes the Java bindings to this interface.

The javadoc is accessible here

## 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. SimGrid-java let you use MSG while coding in Java. So if your need is MSG + Java, you're in the right section!

## Usage overview

To make a long story short, it's a JNI binding, so it implies that:

- Most of the MSG and SimGrid documentation about behavioral aspects applies directly to what you are programming.
- MSG data structures are mapped to Java objects. So it means that from the syntax point of view, you have to know how those objects are. Fortunately, we have generated the Javadoc for those objects. So take a look at it

Finally, it implies also that your program can crash for 3 main reasons:

- Your Java part is not good: you'll have a good old java exception thrown, and hence you should be able to correct it by yourself.
- Our java part is not good: you'll also have a java exception thrown, but we have real doubts this can happen, since the java part is only a JNI binding. The other option is that it crashed because you used incorrectly the MSG API, so this means also you should have an MSGException. It means you should read carefully MSG samples and/or documentation.
- Something has crashed in the C part. Okay, here comes the tricky thing.

C crashes mainly for 2 reasons:

- When something goes wrong in your simulation, sometimes the C part stops because you used SimGrid incorrectly, and JNI bindings are not fond of that. It means that you'll have something that looks ugly, but you should be able to identify what's going wrong in your code by carefully reading the whole error message
- It may happen that the problem comes directly from SimGrid: in this case, the error should be uglier. In that case, you may submit a bug directly to SimGrid.

## How to install Simgrid-java

To use java with Simgrid you have to install some dependencies:

- Java JDK packages, such as `openjdk7` or `sun-java6-jdk` (with `libgcj10-dev` or another version of gcj). For maximal performance and scalability, use a coroutine-enabled JVM (see How to use the coroutines context factory).

Then build Simgrid with the Java bindings enabled:

cmake -Denable_java=ON .

If cmake complains that jni could not be found, you need to tell it where JNI header files are located. the following command should tell you:

$ locate jni.h
/usr/lib/jvm/java-6-openjdk-amd64/include/jni.h
/usr/lib/jvm/java-7-openjdk-amd64/include/jni.h

If you have several version of jni installed (as in the example above), you need to check the version of java that is used by default on your machine (using javac -version), and pick the right one. Then set the `JAVA_INCLUDE_PATH` environment variable to the right path (note that we remove the filename `jni.h` from that path), and relaunch cmake.

$ export JAVA_INCLUDE_PATH=/usr/lib/jvm/java-6-openjdk-amd64/include/
$ cmake .

### How to use Simgrid-java

To execute the examples you need to add the path where you installed the generated `libsimgrid-java` and `libsimgrid` libraries into the `LD_LIBRARY_PATH`.

Be careful on Mac, this variable is called `DYLD_LIBRARY_PATH` and not `LD_LIBRARY_PATH`.

$ export SIMGRID_ROOT="$HOME/Install/simgrid/" # change it to the path where you installed the SimGrid library
$ export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:+$LD_LIBRARY_PATH:}$SIMGRID_ROOT/lib
$ cd examples
$ java -classpath .:../simgrid.jar basic/BasicTest platform.xml basic/basicDeployment.xml

If you want to make these settings permanent even after a reboot, you need to add the export lines into your `~/.bashrc` file, or equivalent.

### How to use the coroutines context factory

There is two main motivations to use the coroutine variant of SimGrid Java bindings: it's about 5 times faster than the default thread-based context factory, and the amount of runnable processes is then only limited by the amount of RAM that you have. The drawbacks are that it requires a specific and rather experimental JVM to run, and that this context factory itself remains a bit experimental so far.

### Getting a mlvm JVM

You need to get a patched JVM from here (many thanks to Lukas Stadler for this work!).

You can either get a prebuilt binary, or recompile your own JVM. Make sure to get a coro-simple version, as we don't need to serialize nor migrate stacks in SimGrid. You should be able to follow the `README.txt` that you'll get in the repository, but here is how we did it, just in case. The instructions are given for a debian or Ubuntu box, but I think you should manage to convert it to your system quite easily. Finally, if you're really stuck, you can get the version compiled by Jonathan Rouzaud-Cornabas from his web page. This version is known to work with SimGrid for sure! http://graal.ens-lyon.fr/~jrouzaud/files/corosimple-linux-amd64-20120914.tgz

1. Install mercurial and some dependencies
   sudo apt-get install mercurial ksh libfreetype6-dev libcups2-dev libasound2-dev gawk openjdk-7-jdk libxext-dev libxrender-dev libxtst-dev
   # Grab the forest extension: we need to source-install it
   hg clone https://bitbucket.org/gxti/hgforest hgforest \endverbatim

2. Configure the mercurial extensions: Edit ~/.hgrc and paste the following lines. Don't forget to change the /path/to/forest.py to point to where you just downloaded the source.

   Forest extension is needed to download the openjdk source code and patches while the mq line is needed to apply the patches. The username is needed at the step "preparing the sources", not sure why.

       [ui]
       username = YouUserameWithoutSpaces
       [extensions]
       forest=/path/to/forest.py
       mq=

3. Prepare the source code
   # create a working directory, and enter it
   mkdir davinci; cd davinci
   # Grab the sources
   hg fclone http://hg.openjdk.java.net/hsx/hotspot-comp sources
   # Grab the patches
   hg fclone http://hg.openjdk.java.net/mlvm/mlvm patches
   # Link the patch directories into the sources
   bash patches/make/link-patch-dirs.sh sources patches
   # Test wether the previous command worked with
   ls -i patches/hotspot/series sources/hotspot/.hg/patches/series
   # It should display something like the following.
   # (note that both file share the same inode number)
   # 9707849 patches/hotspot/series
   # 9707849 sources/hotspot/.hg/patches/series
   # Specify what to compile.
   export davinci=$(pwd) guards="buildable testable coro-simple"
   # Apply the patches
   sh patches/make/each-patch-repo.sh hg qselect --reapply $guards '$(sh $davinci/patches/make/current-release.sh)'
   # Check that it understood that you want the patch applied:
   grep GLOBAL_GUARDS patches/make/* -r
   # this should display something like the following (maybe amonst other unrelated lines)
   # GLOBAL_GUARDS=buildable testable coro-simple
   # If this does not work, edit patches/make/Makefile,
   # manually coro-simple to GLOBAL_GUARDS and then
   # rerun the patches/make/each-patch-repo.sh script as earlier
   # Finish the setup
   (cd patches/make; make setup && make force && make && make FORCE_VERSIONS=1 && echo "Sources are properly setup")
   # If this last command failed, check your mercurial config within ~/.hgrc (see above)
4. Compile it all
   unset LD_LIBRARY_PATH
   export ALT_BOOTDIR=/usr/lib/jvm/java-7-openjdk-amd64/
   cd sources
   # Check that everything is fine
   make sanity
   # Go for it (it takes about half an hour on my machine)
   make all
   # Check that the coroutine library got compiled in
   ls sources/build/linux-amd64/classes/java/dyn/
   # This should display a bunch of class files. If not, something went wrong, you need to investigate further

### Using coroutine contexts

SimGrid Java will automatically switch to the coroutine context factory if your JVM support it, so you will just need to execute your simulation with the correct JVM. The selected context factory gets displayed automatically.

export LD_LIBRARY_PATH=/path/to/simgrid.so:/path/to/libsimgrid-java.so
cd examples
$PATH_TO_COROUTINE_JVM/java -classpath .:../simgrid.jar masterslave.Masterslave masterslave/ masterslaveDeployment.xml platform.xml

Note that you may have to adjust the "coro.stacksPerThread" configuration option to run large simulations. The default is 100 and you want to increase it to run more processes.

$ $PATH_TO_COROUTINE_JVM/java -Dcoro.stacksPerThread=$STACKS_NUMBER -classpath .:../simgrid.jar basic/BasicTest platform.xml basic/basicDeployment.xml

If you reach the point where the creation of new simulated processes fail with the message "Can't create coroutine object", you may need to increase the relevant system limit with the following command.

sysctl -w vm.max_map_count = 131072

The full story is that each coroutine requires two memory maps, and that Linux puts a limit on the total amount of memory maps that each process can manage (by default, this limit is often at 65535). Since the JVM needs a few dozen of such maps on its own (three maps per dynamic library – check `/proc/the_pid/maps` if you don't believe it), this is enough to create over 30,000 simulated processes. But to go futher, that limit must be modified.

If you want to make this change permanent on your machine, edit your `/etc/sysctl.conf` file. Otherwise, you have to redo it by calling sysctl after each reboot.

# Lua Binding

Most of Simgrid modules require a good level in C programming, since simgrid is used to be as standard C library. Sometime users prefer using some kind of “easy scripts” or a language easier to code with, for their works, which avoid dealing with C errors, and sometime an important gain of time. Besides Java Binding, Lua and Ruby bindings are available since version 3.4 of Simgrid for MSG Module, and we are currenlty working on bindings for other modules.

## What is lua ?

Lua is a lightweight, reflective, imperative and functional programming language, designed as a scripting language with extensible semantics as a primary goal (see official web site here).

### Why lua ?

Lua is a fast, portable and powerful script language, quite simple to use for developpers. it combines procedural features with powerful data description facilities, by using a simple, yet powerful, mechanism of tables. Lua has a relatively simple C API compared to other scripting languages, and accordingly it provides a robust, easy to use it.

### How to use lua in Simgrid ?

Actually, the use of lua in Simgrid is quite simple, you have just to follow the same steps as coding with C in Simgird :

- Coding functions coresponding to each process
- loading the platforme/deployment XML file that describe the environment of simulation
- and … Running the Simulation.

## Master/Slave Example

- Master Code
  function Master(...)
  if #arg ~= 4 then
  error("Wrong number of arguments (got " .. #arg ..
  ", expected 4: nb_tasks comp_size comm_size slave_count)")
  end
  simgrid.info("Hello from lua, I'm the master")
  local nb_task, comp_size, comm_size, slave_count = unpack(arg)
  -- Dispatch the tasks
  for i = 1, nb_task do
  local task = simgrid.task.new("Task " .. i, comp_size, comm_size)
  local task_name = task:get_name()
  local alias = "slave " .. (i % slave_count)
  simgrid.info("Sending '" .. task_name .. "' to '" .. alias .."'")
  task:send(alias) -- C user data set to NULL
  simgrid.info("Done sending '".. task_name .. "' to '" .. alias .."'")
  end
  -- Sending Finalize Message To Others
  simgrid.info("All tasks have been dispatched. Let's tell everybody the computation is over.")
  for i = 0, slave_count - 1 do
  local alias = "slave " .. i
  simgrid.info("Sending finalize to '" .. alias .. "'")
  local finalize = simgrid.task.new("finalize", comp_size, comm_size)
  finalize:send(alias)
  end
  simgrid.info("Everything's done.")
  end -- end_of_master
  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.

- Slave Code
  function Slave(...)
  if #arg ~= 1 then
  error("Wrong number of arguments (got " .. #arg .. ", expected 1: slave_id)")
  end
  local my_mailbox = "slave " .. arg[1]
  simgrid.info("Hello from lua, I'm a poor slave with mailbox: " .. my_mailbox)
  while true do
  local task = simgrid.task.recv(my_mailbox)
  local task_name = task:get_name()
  if (task_name == "finalize") then
  simgrid.info("Got finalize message")
  break
  end
  simgrid.info("Received task '" .. task_name .. "' on mailbox '" .. my_mailbox .. "'")
  task:execute()
  simgrid.info("Task '" .. task_name .. "' is done")
  end
  simgrid.info("I'm done. See you!")
  end -- end_of_slave
  Here, we see the use of simgrid.Task.recv(alias) to receive a task with a specific alias, this function return directly the task recevied.

- Set Environmenet and run application
  dofile 'master.lua'
  dofile 'slave.lua'
  -- Simulation Code ----------------------------------------------------------
  require "simgrid"
  simgrid.platform(arg[1])
  simgrid.application(arg[2])
  simgrid.run()
  simgrid.info("Simulation's over. See you.")
  -- end-of-master-slave

## Exchanging Data

You can also exchange data between Process using lua. for that, you have to deal with lua task as a table, since lua is based itself on a mechanism of tables, so you can exchange any kind of data (tables, matrix, strings,…) between process via tasks.

- Sender process

        task = simgrid.Task.new("data_task",task_comp,task_comm);
        task['matrix'] = my_matrix;
        task['table'] = my_table;
        task['message'] = "Hello from (Lua || Simgrid ) !! "
        …
        simgrid.Task.send(task,alias)

  After creating task, we associate to it various kind of data with a specific key (string in this case) to distinguish between data variables. The receiver will use this key to access easily to datas.

- Receiver processe

        task = simgrid.Task.recv(alias);
        sender_matrix = task['matrix'];
        sender_table = task['table'];
        sender_message = task['message']
        ...

  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.

## Bypass XML

maybe you wonder if there is a way to bypass the XML files, 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 ;) )

- set Routing mode

         simgrid.AS.new{id="AS0",mode="Full"};

- set Hosts

        simgrid.Host.new{id="Tremblay",power=98095000};
        simgrid.Host.new{id="Jupiter",power=76296000};
        simgrid.Host.new{id="Fafard",power=76296000};
        simgrid.Host.new{id="Ginette",power=48492000};
        simgrid.Host.new{id="Bourassa",power=48492000};

  we use simgrid.Host.new{id=id_host,power=power_host} to instanciate our hosts.

- set Links

        for i=0,11 do
          simgrid.Link.new{id=i,bandwidth=252750+ i*768,latency=0.000270544+i*0.087};    --  some crazy values ;)
        end

  we used simgrid.Link.new{id=link_id,bandwidth=bw,latency=lat} with a simple for loop to create all links we need (much easier than XML hein ?)

- set Routes

      -- simgrid.Route.new(src_id,des_id,links_nb,links_list)
         simgrid.Route.new("Tremblay","Jupiter",1,{"1"});
         simgrid.Route.new("Tremblay","Fafard",6,{"0","1","2","3","4","8"});
         simgrid.Route.new("Tremblay","Ginette",3,{"3","4","5"});
         simgrid.Route.new("Tremblay","Bourassa",7,{"0","1","3","2","4","6","7"});

         simgrid.Route.new("Jupiter","Tremblay",1,{"1"});
         simgrid.Route.new("Jupiter","Fafard",7,{"0","1","2","3","4","8","9"});
         simgrid.Route.new("Jupiter","Ginette",4,{"3","4","5","9"});
         simgrid.Route.new("Jupiter","Bourassa",8,{"0","1","2","3","4","6","7","9"});
         ...

  for each host you have to specify which route to choose to access to the rest of hosts connected in the grid.

- Save platform

        simgrid.register_platform();

  Don't forget to register your platform, that SURF callbacks starts their work ;)

- set application

         simgrid.Host.setFunction("Tremblay","Master",4,{"20","550000000","1000000","4"});
         simgrid.Host.setFunction("Bourassa","Slave",1,{"0"});
         simgrid.Host.setFunction("Jupiter","Slave",1,{"1"});
         simgrid.Host.setFunction("Fafard","Slave",1,{"2"});
         simgrid.Host.setFunction("Ginette","Slave",1,{"3"});

  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 .

-        simgrid.register_application();

  Yes, Here too you have to register your application before running the simulation.

the full example is distributed in the file examples/lua/master_slave_bypass.lua

## Master/slave Lua application

Simulation of a master-slave application using lua bindings

- Master code
- Slave code
- Simulation core
- Helping files
- Example of application file
- Example of platform file

### Master code

as described in the C native master/Slave example, this function has to be assigned to a msg_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
- the size of the files associated to each task
- a list of host that will accept those tasks.

Tasks are dumbly sent in a round-robin style.

-- Dispatch the tasks
for i = 1, nb_task do
local task = simgrid.task.new("Task " .. i, comp_size, comm_size)
local task_name = task:get_name()
local alias = "slave " .. (i % slave_count)
simgrid.info("Sending '" .. task_name .. "' to '" .. alias .."'")
task:send(alias) -- C user data set to NULL
simgrid.info("Done sending '".. task_name .. "' to '" .. alias .."'")
end

### Slave code

This function has to be assigned to a msg_process_t that has to behave as a slave. This function keeps waiting for tasks and executes them as it receives them.

function Slave(...)
if #arg ~= 1 then
error("Wrong number of arguments (got " .. #arg .. ", expected 1: slave_id)")
end
local my_mailbox = "slave " .. arg[1]
simgrid.info("Hello from lua, I'm a poor slave with mailbox: " .. my_mailbox)
while true do
local task = simgrid.task.recv(my_mailbox)
local task_name = task:get_name()
if (task_name == "finalize") then
simgrid.info("Got finalize message")
break
end
simgrid.info("Received task '" .. task_name .. "' on mailbox '" .. my_mailbox .. "'")
task:execute()
simgrid.info("Task '" .. task_name .. "' is done")
end
simgrid.info("I'm done. See you!")
end -- end_of_slave

### Simulation core

in this section the core of the simulation which start by including the simgrid lib for bindings : require "simgrid"

1. Simulation settings : simgrid.platform creates a realistic environment
2. Application deployment : create the processes on the right locations with simgrid.application
3. The simulation is run with simgrid.run

Its arguments are:

- platform_file: the name of a file containing an valid surfxml platform description.( first command line argument)
- application_file: the name of a file containing a valid surfxml application description ( second commande line argument )
  simgrid.platform(arg[1])
  simgrid.application(arg[2])
  simgrid.run()

## Master/slave Bypass Lua application

Simulation of a master-slave application using lua bindings, Bypassing the XML parser

- Master code
- Slave code
- Simulation core

### Master code

as described in the C native master/Slave example, this function has to be assigned to a msg_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
- the size of the files associated to each task
- a list of host that will accept those tasks.

Tasks are dumbly sent in a round-robin style.

--Master Function
function Master(...)
if #arg ~= 4 then
error("Wrong number of arguments (got " .. #arg ..
", expected 4: nb_tasks comp_size comm_size slave_count)")
end
simgrid.info("Hello from lua, I'm the master")
for i,v in ipairs(arg) do
simgrid.info("Got " .. v)
end
local nb_task, comp_size, comm_size, slave_count = unpack(arg)
simgrid.info("Argc=" .. (#arg) .. " (should be 4)")
-- Dispatch the tasks
for i = 1, nb_task do
task = simgrid.task.new("Task " .. i, comp_size, comm_size);
local task_name = simgrid.task.get_name(task)
alias = "slave " .. (i%slave_count);
simgrid.info("Master sending '" .. task_name .. "' To '" .. alias .. "'");
simgrid.task.send(task, alias); -- C user data set to NULL
simgrid.info("Master done sending '" .. task_name .. "' To '" .. alias .. "'");
end
-- Sending Finalize Message To Others
simgrid.info("Master: All tasks have been dispatched. Let's tell everybody the computation is over.");
for i = 0, slave_count-1 do
alias = "slave " .. i;
simgrid.info("Master: sending finalize to " .. alias);
finalize = simgrid.task.new("finalize", comp_size, comm_size);
simgrid.task.send(finalize, alias)
end
simgrid.info("Master: Everything's done.");
end
--end_of_master

### Slave code

This function has to be assigned to a msg_process_t that has to behave as a slave. This function keeps waiting for tasks and executes them as it receives them.

-- Slave Function ---------------------------------------------------------
function Slave(...)
if #arg ~= 1 then
error("Wrong number of arguments (got " .. #arg .. ", expected 1: slave_id)")
end
local my_mailbox = "slave " .. arg[1]
simgrid.info("Hello from lua, I'm a poor slave with mbox: " .. my_mailbox)
while true do
local task = simgrid.task.recv(my_mailbox);
--print(task)
local task_name = task:get_name()
if (task:get_name() == "finalize") then
simgrid.info("Slave '" .. my_mailbox .. "' got finalize msg");
break
end
--local tk_name = simgrid.task.get_name(tk)
simgrid.info("Slave '" .. my_mailbox .. "' processing " .. task:get_name())
simgrid.task.execute(task)
simgrid.info("Slave '" .. my_mailbox .. "': task " .. task:get_name() .. " done")
end -- while
simgrid.info("Slave '" .. my_mailbox .. "': I'm Done . See You !!");
end
-- end_of_slave

### 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. : require "simgrid"

1. Hosts : simgrid.Host.new instanciate a new host with an id, and power.
2. Links : simgrid.Link.new instanictae a new link that will require an id, bandwith and latency values.
3. Route : simgrid.Route.new define a route between two hosts specifying the links to use.
4. Simulation settings : simgrid.register_platform(); register own platform without using the XML SURF parser.

we can also bypass the XML deployment file, and associate functions for each of defined hosts.

- simgrid.Host.setFunction: associate a function to a host, specifying arguments if needed.
- simgrid.register_application(): saving the deployment settings before running the simualtion.

require "simgrid"
dofile 'platform.lua'
dofile 'deploy.lua'
--Rutform.lua'
dofile 'master.lua'
dofile 'slave.lua'
simgrid.run()
simgrid.info("Simulation's over.See you.")