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 svn checkout svn://scm.gforge.inria.fr/svn/simgrid/contrib/trunk/simgrid-ruby simgrid-ruby
168 -- Svn version : 9905
169 -- SITE : Linux_2.6.38-8-generic_x86_64
170 -- BUILDNAME : Simgrid-Ruby
171 -- Looking for lib SimGrid
172 -- Looking for lib SimGrid - found
173 -- Simgrid version : 3.6
174 -- Looking for gras.h
175 -- Looking for gras.h - found
176 -- Found Tesh: /home/user/Bureau/simgrid/git/bin/tesh
177 -- Found gras_stub_generator: /home/user/Bureau/simgrid/git/bin/gras_stub_generator
178 -- Found ruby: /usr/bin/ruby
179 -- Looking for ruby.h
180 -- Looking for ruby.h - found
181 -- Looking for confi.h
182 -- Looking for config.h - found
183 -- Looking for lib ruby
184 -- Looking for lib ruby - found
185 -- Lib ruby version: 1.9.1
188 -- Build files have been written to: /home/user/workspace/simgrid-ruby/build
191 \subsection bindings_binding_ruby_simgrid Use Ruby in Simgrid
192 Since v3.4, the use of <a href="http://ruby-lang.org">ruby</a> in simgrid is available for the MSG Module.
193 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.
195 \subsection bindings_binding_ruby_example Master/Slave Ruby Application
196 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,
197 with a 'main' function that describe the behaviour of the process during the simulation.
206 class Master < MSG::Process
207 # main : that function that will be executed when running simulation
209 def main(args) # args is an array containing arguments for function master
212 MSG::info("args["+String(i)+"]="+args[i])
215 raise "Master needs 3 arguments" if size < 3
216 numberOfTask = Integer(args[0])
217 taskComputeSize = Float(args[1])
218 taskCommunicationSize = Float(args[2])
219 slaveCount = Integer(args[3])
221 # Creates and sends the tasks
222 for i in 0..numberOfTask-1
223 task = Task.new("Task_"+ i.to_s, taskComputeSize , taskCommunicationSize);
224 mailbox = "slave " + (i%slaveCount).to_s
225 MSG::info("Master Sending "+ task.name + " to " + mailbox + " with Comput Size " +
228 MSG::info("Master Done Sending " + task.name + " to " + mailbox)
231 # Sending Finalize MSG::Tasks
232 MSG::info("Master: All tasks have been dispatched. Let's tell everybody the computation is over.")
233 for i in 0..slaveCount-1
234 mailbox = "slave " + i.to_s
235 finalize_task = Task.new("finalize",0,0)
236 finalize_task.send(mailbox)
238 MSG::info("Master : Everything's Done")
244 the class MSG::Task contains methods that allows the management of the native MSG tasks.
245 in master ruby code we used :
246 - <i>MSG::Task.new(task_name,compute_size,communication_size)</i> : to instanciate a new task.
247 - <i>MSG::Task.send(mailbox)</i> : to send the task via a mailbox alias.
248 - <i>MSG::Task.name</i> : to get the task's name.
252 class Slave < MSG::Process
255 mailbox = "slave " + args[0]
256 for i in 0..args.size-1
257 MSG::debug("args["+String(i)+"]="+args[i])
261 MSG::info("Slave '"+ mailbox +"' waiting for new task");
262 task = Task.receive(mailbox)
263 if (task.name == "finalize")
267 MSG::info("Slave '" + mailbox + "' done executing task "+ task.name + ".")
269 MSG::info("I'm done, see you")
273 to receive a task, we use the method <i>MSG::Task.receive(mailbox)</i> that return a MSG:Task object (received task).
282 if (ARGV.length == 2)
283 MSG.createEnvironment(ARGV[0])
284 MSG.deployApplication(ARGV[1])
288 MSG.createEnvironment("platform.xml")
289 MSG.deployApplication("deploy.xml")
292 puts "Simulation time : " + MSG.getClock.to_s
296 - <i>MSG.createEnvironment(platform_file)</i> : set up the environment
297 - <i>MSG.deployApplication(deployment_file)</i> : load the deployment file description.
298 - <i>MSG.run</i> : run the simulation
300 \subsection bindings_binding_ruby_data Exchanging data
301 ruby bindings provides two ways to exchange data between ruby processes.
302 \li MSG::Task.join & MSG::Task.data <br/>
304 the MSG::Task class contains 2 methods that allows a data exchange between 2 process.
306 -<i>MSG::Task.join</i> : makes possible to join any kind of ruby data within a task.
310 myTable <<1<<-2<<45<<67<<87<<76<<89<<56<<78<<3<<-4<<99
311 # Creates and send Task With the Table inside
312 task = MSG::Task.new("quicksort_task",taskComputeSize, taskCommunicationSize);
317 -<i>MSG::Task.data</i> : to access to the data contained into the task.
320 task = MSG::Task.receive(recv_mailbox.to_s)
322 quicksort(table,0,table.size-1)
325 you can find a complet example illustrating the use of those methods in file /example/ruby/Quicksort.rb
329 another 'object-oriented' way to do it, is to make your own 'task' class that inherit from MSG::Task ,
330 and contains data you want to deal with, the only 'tricky' thing is that "the initializer" method has no effect !
332 the use of some getter/setter methods would be the simple way to manage your data :)
334 class PingPongTask < MSG::Task
335 # The initialize method has no effect
345 you can find an example of use in file example/ruby/PingPong.rb
348 \section bindings_binding_java Java Binding
350 \subsection bindings_binding_java_install How to install Simgrid-java
352 To use java with Simgrid you have to install some dependancies:
353 \li Simgrid (see \ref installSimgrid_cmake). Be sure having set the environment variable "SIMGRID_ROOT".
354 \li Java packages: sun-java6-jdk and libgcj10-dev. If you cannot find the
355 libgcj10-dev, try another version.
357 Then Download and install package Simgrid-java:
359 svn checkout svn://scm.gforge.inria.fr/svn/simgrid/contrib/trunk/simgrid-java simgrid-java
366 -- Svn version : 9904
367 -- SITE : Linux_2.6.38-8-generic_x86_64
368 -- BUILDNAME : Simgrid-Java
369 -- Looking for lib SimGrid
370 -- Looking for lib SimGrid - found
371 -- Simgrid version : 3.6
372 -- Looking for gras.h
373 -- Looking for gras.h - found
374 -- Found Tesh: /home/user/Bureau/simgrid/git/bin/tesh
375 -- Found gras_stub_generator: /home/user/Bureau/simgrid/git/bin/gras_stub_generator
376 -- Java version 1.6.0.22 configured successfully!
378 -- Looking for jni.h - found
379 -- Add flags -I/usr/lib/jvm/java-6-openjdk/include
380 -- Looking for jni_md.h
381 -- Looking for jni_md.h - found
382 -- Found javac: /usr/bin/javac
383 -- Found jar: /usr/bin/jar
386 -- Build files have been written to: /home/user/workspace/simgrid-java/build
389 \subsection bindings_binding_java_use Use Java in Simgrid
391 The use of java in simgrid is available for the MSG Module. You can find almost all MSG functionalities
392 in Java code (\ref MSG_JAVA).