/*! \page bindings Bindings
\htmlinclude .bindings.doc.toc
\section bindings_binding_lua 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.
\subsection bindings_binding_lua_about 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).
\subsubsection bindings_binding_lua_why 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.
\subsubsection bindings_binding_lua_simgrid 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.
\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,
then simgrid.Task.send(task,alias) to send it.
we use also simgrid.Task.name(task), to get the task's name.
\dontinclude lua/masterslave/slave.lua
\li Slave Code
\until 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.
\dontinclude lua/masterslave/master_slave.lua
\li Set Environmenet and run application
\until simgrid.clean()
\subsection bindings_binding_lua_example_data 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.
\li Sender process
\verbatim
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)
\endverbatim
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.
\li Receiver processe
\verbatim
task = simgrid.Task.recv(alias);
sender_matrix = task['matrix'];
sender_table = task['table'];
sender_message = task['message']
...
\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.
\subsection bindings_binding_lua_example_bypass 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 ;) )
\li set Routing mode
\verbatim
simgrid.AS.new{id="AS0",mode="Full"};
\endverbatim
\li set Hosts
\verbatim
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};
\endverbatim
we use simgrid.Host.new{id=id_host,power=power_host} to instanciate our hosts.
\li set Links
\verbatim
for i=0,11 do
simgrid.Link.new{id=i,bandwidth=252750+ i*768,latency=0.000270544+i*0.087}; -- some crazy values ;)
end
\endverbatim
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 ?)
\li set Routes
\verbatim
-- 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"});
...
\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();
\endverbatim
Don't forget to register your platform, that SURF callbacks starts their work ;)
\li set application
\verbatim
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"});
\endverbatim
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
\verbatim
simgrid.register_application();
\endverbatim
Yes, Here too you have to resgiter your application before running the simulation.
the full example is distributed in the file examples/lua/master_slave_bypass.lua
\section bindings_binding_ruby Ruby Binding
\subsection bindings_binding_ruby_install How to install Simgrid-ruby
To use Ruby with Simgrid you have to install some dependancies:
\li Simgrid (see \ref installSimgrid_cmake). Be sure having set the environment variable "SIMGRID_ROOT".
\li Ruby package.
Then Download and install package Simgrid-ruby:
\verbatim
git clone git://scm.gforge.inria.fr/simgrid/simgrid-ruby.git
cd simgrid-ruby
cmake .
\endverbatim
Cmake output
\verbatim
-- SITE : Linux_2.6.38-8-generic_x86_64
-- BUILDNAME : Simgrid-Ruby
-- Looking for lib SimGrid
-- Looking for lib SimGrid - found
-- Simgrid version : 3.6
-- Looking for gras.h
-- Looking for gras.h - found
-- Found Tesh: /home/user/Bureau/simgrid/git/bin/tesh
-- Found gras_stub_generator: /home/user/Bureau/simgrid/git/bin/gras_stub_generator
-- Found ruby: /usr/bin/ruby
-- Looking for ruby.h
-- Looking for ruby.h - found
-- Looking for confi.h
-- Looking for config.h - found
-- Looking for lib ruby
-- Looking for lib ruby - found
-- Lib ruby version: 1.9.1
-- Configuring done
-- Generating done
-- Build files have been written to: /home/user/workspace/simgrid-ruby/build
\endverbatim
\subsection bindings_binding_ruby_simgrid Use Ruby in Simgrid
Since v3.4, the use of ruby in simgrid is available for the MSG Module.
you can find almost all MSG functionalities in Ruby code, that allows you to set up your environment, manage tasks between hosts and run the simulation.
\subsection bindings_binding_ruby_example Master/Slave Ruby Application
for each process method(master and slave in this example), you have to associate a ruby class, that should inherit from MSG::Process ruby class,
with a 'main' function that describe the behaviour of the process during the simulation.
\li required stuff
\verbatim
require 'simgrid'
include MSG
\endverbatim
\li Master code
\verbatim
class Master < MSG::Process
# main : that function that will be executed when running simulation
def main(args) # args is an array containing arguments for function master
size = args.size
for i in 0..size-1
MSG::info("args["+String(i)+"]="+args[i])
end
raise "Master needs 3 arguments" if size < 3
numberOfTask = Integer(args[0])
taskComputeSize = Float(args[1])
taskCommunicationSize = Float(args[2])
slaveCount = Integer(args[3])
# Creates and sends the tasks
for i in 0..numberOfTask-1
task = Task.new("Task_"+ i.to_s, taskComputeSize , taskCommunicationSize);
mailbox = "slave " + (i%slaveCount).to_s
MSG::info("Master Sending "+ task.name + " to " + mailbox + " with Comput Size " +
task.compSize.to_s)
task.send(mailbox)
MSG::info("Master Done Sending " + task.name + " to " + mailbox)
end
# Sending Finalize MSG::Tasks
MSG::info("Master: All tasks have been dispatched. Let's tell everybody the computation is over.")
for i in 0..slaveCount-1
mailbox = "slave " + i.to_s
finalize_task = Task.new("finalize",0,0)
finalize_task.send(mailbox)
end
MSG::info("Master : Everything's Done")
end
end
\endverbatim
the class MSG::Task contains methods that allows the management of the native MSG tasks.
in master ruby code we used :
- MSG::Task.new(task_name,compute_size,communication_size) : to instanciate a new task.
- MSG::Task.send(mailbox) : to send the task via a mailbox alias.
- MSG::Task.name : to get the task's name.
\li Slave code
\verbatim
class Slave < MSG::Process
def main(args)
mailbox = "slave " + args[0]
for i in 0..args.size-1
MSG::debug("args["+String(i)+"]="+args[i])
end
while true
MSG::info("Slave '"+ mailbox +"' waiting for new task");
task = Task.receive(mailbox)
if (task.name == "finalize")
break
end
task.execute
MSG::info("Slave '" + mailbox + "' done executing task "+ task.name + ".")
end
MSG::info("I'm done, see you")
end
end
\enverbatim
to receive a task, we use the method MSG::Task.receive(mailbox) that return a MSG:Task object (received task).
\li Main chunk
\verbatim
require 'simgrid'
include MSG
(...)
if (ARGV.length == 2)
MSG.createEnvironment(ARGV[0])
MSG.deployApplication(ARGV[1])
else
MSG.createEnvironment("platform.xml")
MSG.deployApplication("deploy.xml")
end
MSG.run
puts "Simulation time : " + MSG.getClock.to_s
MSG.exit
\endverbatim
- MSG.createEnvironment(platform_file) : set up the environment
- MSG.deployApplication(deployment_file) : load the deployment file description.
- MSG.run : run the simulation
\subsection bindings_binding_ruby_data Exchanging data
ruby bindings provides two ways to exchange data between ruby processes.
\li MSG::Task.join & MSG::Task.data
the MSG::Task class contains 2 methods that allows a data exchange between 2 process.
-MSG::Task.join : makes possible to join any kind of ruby data within a task.
\verbatim
...
myTable = Array.new
myTable <<1<<-2<<45<<67<<87<<76<<89<<56<<78<<3<<-4<<99
# Creates and send Task With the Table inside
task = MSG::Task.new("quicksort_task",taskComputeSize, taskCommunicationSize);
task.join(myTable);
...
task.send(mailbox);
\endverbatim
-MSG::Task.data : to access to the data contained into the task.
\verbatim
...
task = MSG::Task.receive(recv_mailbox.to_s)
table = task.data
quicksort(table,0,table.size-1)
...
\endverbatim
you can find a complet example illustrating the use of those methods in file /example/ruby/Quicksort.rb
\li inheritence
another 'object-oriented' way to do it, is to make your own 'task' class that inherit from MSG::Task ,
and contains data you want to deal with, the only 'tricky' thing is that "the initializer" method has no effect !
the use of some getter/setter methods would be the simple way to manage your data :)
\verbatim
class PingPongTask < MSG::Task
# The initialize method has no effect
@time
def setTime(t)
@time = t
end
def getTime()
return @time
end
end
\endverbatim
you can find an example of use in file example/ruby/PingPong.rb
\section bindings_binding_java Java Binding
\subsection bindings_binding_java_install How to install Simgrid-java
To use java with Simgrid you have to install some dependancies:
\li Simgrid (see \ref installSimgrid_cmake). Be sure having set the environment variable "SIMGRID_ROOT".
\li Java packages: sun-java6-jdk and libgcj10-dev. If you cannot find the
libgcj10-dev, try another version.
Then Download and install package Simgrid-java:
\verbatim
git clone git://scm.gforge.inria.fr/simgrid/simgrid-java.git
cd simgrid-java
cmake .
\endverbatim
Cmake output
\verbatim
-- SITE : Linux_2.6.38-8-generic_x86_64
-- BUILDNAME : Simgrid-Java
-- Looking for lib SimGrid
-- Looking for lib SimGrid - found
-- Simgrid version : 3.6
-- Looking for gras.h
-- Looking for gras.h - found
-- Found Tesh: /home/user/Bureau/simgrid/git/bin/tesh
-- Found gras_stub_generator: /home/user/Bureau/simgrid/git/bin/gras_stub_generator
-- Java version 1.6.0.22 configured successfully!
-- Looking for jni.h
-- Looking for jni.h - found
-- Add flags -I/usr/lib/jvm/java-6-openjdk/include
-- Looking for jni_md.h
-- Looking for jni_md.h - found
-- Found javac: /usr/bin/javac
-- Found jar: /usr/bin/jar
-- Configuring done
-- Generating done
-- Build files have been written to: /home/user/workspace/simgrid-java/build
\endverbatim
\subsection bindings_binding_java_use Use Java in Simgrid
The use of java in simgrid is available for the MSG Module. You can find almost all MSG functionalities
in Java code (\ref MSG_JAVA).
*/