1 /*! \page bindings Bindings
3 \htmlinclude .bindings.doc.toc
5 \section bindings_binding_lua Lua Binding
7 Most of Simgrid modules require a good level in C programming, since simgrid is used to be as standard C library.
8 Sometime users prefer using some kind of « easy scripts » or a language easier to code with, for their works,
9 which avoid dealing with C errors, and sometime an important gain of time.
10 Besides Java Binding, Lua and Ruby bindings are available since version 3.4 of Simgrid
11 for MSG Module, and we are currenlty working on bindings for other modules.
14 \subsection bindings_binding_lua_about What is lua ?
15 Lua is a lightweight, reflective, imperative and functional programming language,
16 designed as a scripting language with extensible semantics as a primary goal (see official web site <a href="http://www.lua.org">here</a>).
17 \subsubsection bindings_binding_lua_why Why lua ?
18 Lua is a fast, portable and powerful script language, quite simple to use for developpers.
19 it combines procedural features with powerful data description facilities,
20 by using a simple, yet powerful, mechanism of tables.
21 Lua has a relatively simple C API compared to other scripting languages,
22 and accordingly it provides a robust, easy to use it.
23 \subsubsection bindings_binding_lua_simgrid How to use lua in Simgrid ?
24 Actually, the use of lua in Simgrid is quite simple, you have just to follow the same steps as coding with C in Simgird :
25 - Coding functions coresponding to each process
26 - loading the platforme/deployment XML file that describe the environment of simulation
27 - and … Running the Simulation.
29 \dontinclude lua/masterslave/master.lua
30 \subsection bindings_binding_lua_example_master_slave Master/Slave Example
34 we mainly use simgrid.Task.new(task_name,computation_size,communication_size) to create our MSG Task,
35 then simgrid.Task.send(task,alias) to send it.
36 we use also simgrid.Task.name(task), to get the task's name.
38 \dontinclude lua/masterslave/slave.lua
41 Here, we see the use of simgrid.Task.recv(alias) to receive a task with a specific alias,
42 this function return directly the task recevied.
44 \dontinclude lua/masterslave/master_slave.lua
45 \li Set Environmenet and run application
46 \until simgrid.clean()
48 \subsection bindings_binding_lua_example_data Exchanging Data
49 You can also exchange data between Process using lua. for that, you have to deal with lua task as a table,
50 since lua is based itself on a mechanism of tables,
51 so you can exchange any kind of data (tables, matrix, strings,…) between process via tasks.
55 task = simgrid.Task.new("data_task",task_comp,task_comm);
56 task['matrix'] = my_matrix;
57 task['table'] = my_table;
58 task['message'] = "Hello from (Lua || Simgrid ) !! "
60 simgrid.Task.send(task,alias)
62 After creating task, we associate to it various kind of data with a specific key (string in this case)
63 to distinguish between data variables. The receiver will use this key to access easily to datas.
68 task = simgrid.Task.recv(alias);
69 sender_matrix = task['matrix'];
70 sender_table = task['table'];
71 sender_message = task['message']
74 Note that in lua, both sender and receiver share the same lua task.
75 So that the receiver could joint data directly on the received task without sending it back.
76 You can find a complet example (matrix multiplication case) in the file example/lua/mult_matrix.lua.
79 \subsection bindings_binding_lua_example_bypass Bypass XML
80 maybe you wonder if there is a way to bypass the XML files,
81 and describe your platform directly from the code, with lua bindings it's Possible !! how ?
82 We provide some additional (tricky?) functions in lua that allows you to set up your own platform without using the XML files
83 ( this can be useful for large platforms, so a simple for loop will avoid you to deal with an annoying XML File ;) )
88 simgrid.AS.new{id="AS0",mode="Full"};
93 simgrid.Host.new{id="Tremblay",power=98095000};
94 simgrid.Host.new{id="Jupiter",power=76296000};
95 simgrid.Host.new{id="Fafard",power=76296000};
96 simgrid.Host.new{id="Ginette",power=48492000};
97 simgrid.Host.new{id="Bourassa",power=48492000};
99 we use simgrid.Host.new{id=id_host,power=power_host} to instanciate our hosts.
104 simgrid.Link.new{id=i,bandwidth=252750+ i*768,latency=0.000270544+i*0.087}; -- some crazy values ;)
107 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 ?)
111 -- simgrid.Route.new(src_id,des_id,links_nb,links_list)
112 simgrid.Route.new("Tremblay","Jupiter",1,{"1"});
113 simgrid.Route.new("Tremblay","Fafard",6,{"0","1","2","3","4","8"});
114 simgrid.Route.new("Tremblay","Ginette",3,{"3","4","5"});
115 simgrid.Route.new("Tremblay","Bourassa",7,{"0","1","3","2","4","6","7"});
117 simgrid.Route.new("Jupiter","Tremblay",1,{"1"});
118 simgrid.Route.new("Jupiter","Fafard",7,{"0","1","2","3","4","8","9"});
119 simgrid.Route.new("Jupiter","Ginette",4,{"3","4","5","9"});
120 simgrid.Route.new("Jupiter","Bourassa",8,{"0","1","2","3","4","6","7","9"});
123 for each host you have to specify which route to choose to access to the rest of hosts connected in the grid.
127 simgrid.register_platform();
129 Don't forget to register your platform, that SURF callbacks starts their work ;)
133 simgrid.Host.setFunction("Tremblay","Master",4,{"20","550000000","1000000","4"});
134 simgrid.Host.setFunction("Bourassa","Slave",1,{"0"});
135 simgrid.Host.setFunction("Jupiter","Slave",1,{"1"});
136 simgrid.Host.setFunction("Fafard","Slave",1,{"2"});
137 simgrid.Host.setFunction("Ginette","Slave",1,{"3"});
139 you don't need to use a deployment XML file, thanks to simgrid.Host.setFunction(host_id,function,args_number,args_list)
140 you can associate functions for each host with arguments if needed .
144 simgrid.register_application();
146 Yes, Here too you have to resgiter your application before running the simulation.
148 the full example is distributed in the file examples/lua/master_slave_bypass.lua
150 \section bindings_binding_ruby Ruby Binding
152 \subsection bindings_binding_ruby_install How to install Simgrid-ruby
154 To use Ruby with Simgrid you have to install some dependancies:
155 \li Simgrid (see \ref installSimgrid_cmake). Be sure having set the environment variable "SIMGRID_ROOT".
158 Then Download and install package Simgrid-ruby:
160 git clone git://scm.gforge.inria.fr/simgrid/simgrid-ruby.git
168 -- SITE : Linux_2.6.38-8-generic_x86_64
169 -- BUILDNAME : Simgrid-Ruby
170 -- Looking for lib SimGrid
171 -- Looking for lib SimGrid - found
172 -- Simgrid version : 3.6
173 -- Looking for gras.h
174 -- Looking for gras.h - found
175 -- Found Tesh: /home/user/Bureau/simgrid/git/bin/tesh
176 -- Found gras_stub_generator: /home/user/Bureau/simgrid/git/bin/gras_stub_generator
177 -- Found ruby: /usr/bin/ruby
178 -- Looking for ruby.h
179 -- Looking for ruby.h - found
180 -- Looking for confi.h
181 -- Looking for config.h - found
182 -- Looking for lib ruby
183 -- Looking for lib ruby - found
184 -- Lib ruby version: 1.9.1
187 -- Build files have been written to: /home/user/workspace/simgrid-ruby/build
190 \subsection bindings_binding_ruby_simgrid Use Ruby in Simgrid
191 Since v3.4, the use of <a href="http://ruby-lang.org">ruby</a> in simgrid is available for the MSG Module.
192 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.
194 \subsection bindings_binding_ruby_example Master/Slave Ruby Application
195 for each process method(master and slave in this example), you have to associate a ruby class, that should inherit from <i>MSG::Process</i> ruby class,
196 with a 'main' function that describe the behaviour of the process during the simulation.
205 class Master < MSG::Process
206 # main : that function that will be executed when running simulation
208 def main(args) # args is an array containing arguments for function master
211 MSG::info("args["+String(i)+"]="+args[i])
214 raise "Master needs 3 arguments" if size < 3
215 numberOfTask = Integer(args[0])
216 taskComputeSize = Float(args[1])
217 taskCommunicationSize = Float(args[2])
218 slaveCount = Integer(args[3])
220 # Creates and sends the tasks
221 for i in 0..numberOfTask-1
222 task = Task.new("Task_"+ i.to_s, taskComputeSize , taskCommunicationSize);
223 mailbox = "slave " + (i%slaveCount).to_s
224 MSG::info("Master Sending "+ task.name + " to " + mailbox + " with Comput Size " +
227 MSG::info("Master Done Sending " + task.name + " to " + mailbox)
230 # Sending Finalize MSG::Tasks
231 MSG::info("Master: All tasks have been dispatched. Let's tell everybody the computation is over.")
232 for i in 0..slaveCount-1
233 mailbox = "slave " + i.to_s
234 finalize_task = Task.new("finalize",0,0)
235 finalize_task.send(mailbox)
237 MSG::info("Master : Everything's Done")
243 the class MSG::Task contains methods that allows the management of the native MSG tasks.
244 in master ruby code we used :
245 - <i>MSG::Task.new(task_name,compute_size,communication_size)</i> : to instanciate a new task.
246 - <i>MSG::Task.send(mailbox)</i> : to send the task via a mailbox alias.
247 - <i>MSG::Task.name</i> : to get the task's name.
251 class Slave < MSG::Process
254 mailbox = "slave " + args[0]
255 for i in 0..args.size-1
256 MSG::debug("args["+String(i)+"]="+args[i])
260 MSG::info("Slave '"+ mailbox +"' waiting for new task");
261 task = Task.receive(mailbox)
262 if (task.name == "finalize")
266 MSG::info("Slave '" + mailbox + "' done executing task "+ task.name + ".")
268 MSG::info("I'm done, see you")
272 to receive a task, we use the method <i>MSG::Task.receive(mailbox)</i> that return a MSG:Task object (received task).
281 if (ARGV.length == 2)
282 MSG.createEnvironment(ARGV[0])
283 MSG.deployApplication(ARGV[1])
287 MSG.createEnvironment("platform.xml")
288 MSG.deployApplication("deploy.xml")
291 puts "Simulation time : " + MSG.getClock.to_s
295 - <i>MSG.createEnvironment(platform_file)</i> : set up the environment
296 - <i>MSG.deployApplication(deployment_file)</i> : load the deployment file description.
297 - <i>MSG.run</i> : run the simulation
299 \subsection bindings_binding_ruby_data Exchanging data
300 ruby bindings provides two ways to exchange data between ruby processes.
301 \li MSG::Task.join & MSG::Task.data <br/>
303 the MSG::Task class contains 2 methods that allows a data exchange between 2 process.
305 -<i>MSG::Task.join</i> : makes possible to join any kind of ruby data within a task.
309 myTable <<1<<-2<<45<<67<<87<<76<<89<<56<<78<<3<<-4<<99
310 # Creates and send Task With the Table inside
311 task = MSG::Task.new("quicksort_task",taskComputeSize, taskCommunicationSize);
316 -<i>MSG::Task.data</i> : to access to the data contained into the task.
319 task = MSG::Task.receive(recv_mailbox.to_s)
321 quicksort(table,0,table.size-1)
324 you can find a complet example illustrating the use of those methods in file /example/ruby/Quicksort.rb
328 another 'object-oriented' way to do it, is to make your own 'task' class that inherit from MSG::Task ,
329 and contains data you want to deal with, the only 'tricky' thing is that "the initializer" method has no effect !
331 the use of some getter/setter methods would be the simple way to manage your data :)
333 class PingPongTask < MSG::Task
334 # The initialize method has no effect
344 you can find an example of use in file example/ruby/PingPong.rb
347 \section bindings_binding_java Java Binding
349 \subsection bindings_binding_java_install How to install Simgrid-java
351 To use java with Simgrid you have to install some dependancies:
352 \li Simgrid (see \ref installSimgrid_cmake). Be sure having set the environment variable "SIMGRID_ROOT".
353 \li Java packages: sun-java6-jdk and libgcj10-dev. If you cannot find the
354 libgcj10-dev, try another version.
356 Then Download and install package Simgrid-java:
358 git clone git://scm.gforge.inria.fr/simgrid/simgrid-java.git
365 -- SITE : Linux_2.6.38-8-generic_x86_64
366 -- BUILDNAME : Simgrid-Java
367 -- Looking for lib SimGrid
368 -- Looking for lib SimGrid - found
369 -- Simgrid version : 3.6
370 -- Looking for gras.h
371 -- Looking for gras.h - found
372 -- Found Tesh: /home/user/Bureau/simgrid/git/bin/tesh
373 -- Found gras_stub_generator: /home/user/Bureau/simgrid/git/bin/gras_stub_generator
374 -- Java version 1.6.0.22 configured successfully!
376 -- Looking for jni.h - found
377 -- Add flags -I/usr/lib/jvm/java-6-openjdk/include
378 -- Looking for jni_md.h
379 -- Looking for jni_md.h - found
380 -- Found javac: /usr/bin/javac
381 -- Found jar: /usr/bin/jar
384 -- Build files have been written to: /home/user/workspace/simgrid-java/build
387 \subsection bindings_binding_java_use Use Java in Simgrid
389 The use of java in simgrid is available for the MSG Module. You can find almost all MSG functionalities
390 in Java code (\ref MSG_JAVA).