1 /*! \page bindings Bindings
4 \section bindings_binding_Java Java Binding
5 Check online for our specific <a href="http://simgrid.gforge.inria.fr/documentation.php">Simgrid-Java documentation</a>.
7 \section bindings_binding_Ruby Ruby Binding
8 Check online for our specific <a href="http://simgrid.gforge.inria.fr/documentation.php">Simgrid-Ruby documentation</a>.
10 \section bindings_binding_lua Lua Binding
12 Most of Simgrid modules require a good level in C programming, since simgrid is used to be as standard C library.
13 Sometime users prefer using some kind of “easy scripts” or a language easier to code with, for their works,
14 which avoid dealing with C errors, and sometime an important gain of time.
15 Besides Java Binding, Lua and Ruby bindings are available since version 3.4 of Simgrid
16 for MSG Module, and we are currenlty working on bindings for other modules.
19 \subsection bindings_binding_lua_about What is lua ?
20 Lua is a lightweight, reflective, imperative and functional programming language,
21 designed as a scripting language with extensible semantics as a primary goal (see official web site <a href="http://www.lua.org">here</a>).
22 \subsubsection bindings_binding_lua_why Why lua ?
23 Lua is a fast, portable and powerful script language, quite simple to use for developpers.
24 it combines procedural features with powerful data description facilities,
25 by using a simple, yet powerful, mechanism of tables.
26 Lua has a relatively simple C API compared to other scripting languages,
27 and accordingly it provides a robust, easy to use it.
28 \subsubsection bindings_binding_lua_simgrid How to use lua in Simgrid ?
29 Actually, the use of lua in Simgrid is quite simple, you have just to follow the same steps as coding with C in Simgird :
30 - Coding functions coresponding to each process
31 - loading the platforme/deployment XML file that describe the environment of simulation
32 - and … Running the Simulation.
34 \dontinclude lua/masterslave/master.lua
35 \subsection bindings_binding_lua_example_master_slave Master/Slave Example
39 we mainly use simgrid.Task.new(task_name,computation_size,communication_size) to create our MSG Task,
40 then simgrid.Task.send(task,alias) to send it.
41 we use also simgrid.Task.name(task), to get the task's name.
43 \dontinclude lua/masterslave/slave.lua
46 Here, we see the use of simgrid.Task.recv(alias) to receive a task with a specific alias,
47 this function return directly the task recevied.
49 \dontinclude lua/masterslave/master_slave.lua
50 \li Set Environmenet and run application
51 \until simgrid.clean()
53 \subsection bindings_binding_lua_example_data Exchanging Data
54 You can also exchange data between Process using lua. for that, you have to deal with lua task as a table,
55 since lua is based itself on a mechanism of tables,
56 so you can exchange any kind of data (tables, matrix, strings,…) between process via tasks.
60 task = simgrid.Task.new("data_task",task_comp,task_comm);
61 task['matrix'] = my_matrix;
62 task['table'] = my_table;
63 task['message'] = "Hello from (Lua || Simgrid ) !! "
65 simgrid.Task.send(task,alias)
67 After creating task, we associate to it various kind of data with a specific key (string in this case)
68 to distinguish between data variables. The receiver will use this key to access easily to datas.
73 task = simgrid.Task.recv(alias);
74 sender_matrix = task['matrix'];
75 sender_table = task['table'];
76 sender_message = task['message']
79 Note that in lua, both sender and receiver share the same lua task.
80 So that the receiver could joint data directly on the received task without sending it back.
81 You can find a complet example (matrix multiplication case) in the file example/lua/mult_matrix.lua.
84 \subsection bindings_binding_lua_example_bypass Bypass XML
85 maybe you wonder if there is a way to bypass the XML files,
86 and describe your platform directly from the code, with lua bindings it's Possible !! how ?
87 We provide some additional (tricky?) functions in lua that allows you to set up your own platform without using the XML files
88 ( this can be useful for large platforms, so a simple for loop will avoid you to deal with an annoying XML File ;) )
93 simgrid.AS.new{id="AS0",mode="Full"};
98 simgrid.Host.new{id="Tremblay",power=98095000};
99 simgrid.Host.new{id="Jupiter",power=76296000};
100 simgrid.Host.new{id="Fafard",power=76296000};
101 simgrid.Host.new{id="Ginette",power=48492000};
102 simgrid.Host.new{id="Bourassa",power=48492000};
104 we use simgrid.Host.new{id=id_host,power=power_host} to instanciate our hosts.
109 simgrid.Link.new{id=i,bandwidth=252750+ i*768,latency=0.000270544+i*0.087}; -- some crazy values ;)
112 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 ?)
116 -- simgrid.Route.new(src_id,des_id,links_nb,links_list)
117 simgrid.Route.new("Tremblay","Jupiter",1,{"1"});
118 simgrid.Route.new("Tremblay","Fafard",6,{"0","1","2","3","4","8"});
119 simgrid.Route.new("Tremblay","Ginette",3,{"3","4","5"});
120 simgrid.Route.new("Tremblay","Bourassa",7,{"0","1","3","2","4","6","7"});
122 simgrid.Route.new("Jupiter","Tremblay",1,{"1"});
123 simgrid.Route.new("Jupiter","Fafard",7,{"0","1","2","3","4","8","9"});
124 simgrid.Route.new("Jupiter","Ginette",4,{"3","4","5","9"});
125 simgrid.Route.new("Jupiter","Bourassa",8,{"0","1","2","3","4","6","7","9"});
128 for each host you have to specify which route to choose to access to the rest of hosts connected in the grid.
132 simgrid.register_platform();
134 Don't forget to register your platform, that SURF callbacks starts their work ;)
138 simgrid.Host.setFunction("Tremblay","Master",4,{"20","550000000","1000000","4"});
139 simgrid.Host.setFunction("Bourassa","Slave",1,{"0"});
140 simgrid.Host.setFunction("Jupiter","Slave",1,{"1"});
141 simgrid.Host.setFunction("Fafard","Slave",1,{"2"});
142 simgrid.Host.setFunction("Ginette","Slave",1,{"3"});
144 you don't need to use a deployment XML file, thanks to simgrid.Host.setFunction(host_id,function,args_number,args_list)
145 you can associate functions for each host with arguments if needed .
149 simgrid.register_application();
151 Yes, Here too you have to register your application before running the simulation.
153 the full example is distributed in the file examples/lua/master_slave_bypass.lua
155 \subsection MSG_ex_master_slave_lua Master/slave Lua application
157 Simulation of a master-slave application using lua bindings
158 - \ref MSG_ext_ms_master_lua
159 - \ref MSG_ext_ms_slave_lua
160 - \ref MSG_ext_ms_core_lua
162 - \ref MSG_ext_ms_helping
163 - \ref MSG_ext_ms_application
164 - \ref MSG_ext_ms_platform
167 \dontinclude lua/masterslave/master_slave.lua
170 \subsubsection MSG_ext_ms_master_lua Master code
172 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.
174 Lua style arguments (...) in for the master are interpreted as:
175 - the number of tasks to distribute
176 - the computation size of each task
177 - the size of the files associated to each task
178 - a list of host that will accept those tasks.
180 Tasks are dumbly sent in a round-robin style.
185 \subsubsection MSG_ext_ms_slave_lua Slave code
187 This function has to be assigned to a #msg_process_t that has to behave as a slave.
188 This function keeps waiting for tasks and executes them as it receives them.
191 \subsubsection MSG_ext_ms_core_lua Simulation core
193 in this section the core of the simulation which start by including the simgrid lib for bindings
194 : <i>require "simgrid" </i>
196 -# Simulation settings : <i>simgrid.platform</i> creates a realistic
198 -# Application deployment : create the processes on the right locations with
199 <i>simgrid.application</i>
200 -# The simulation is run with <i>simgrid.run</i>
203 - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.( first command line argument)
204 - <i>application_file</i>: the name of a file containing a valid surfxml application description ( second commande line argument )
206 \until simgrid.clean()
209 \subsection MSG_ex_master_slave_lua_bypass Master/slave Bypass Lua application
211 Simulation of a master-slave application using lua bindings, Bypassing the XML parser
212 - \ref MSG_ext_ms_bp_master_lua
213 - \ref MSG_ext_ms_bp_slave_lua
214 - \ref MSG_ext_ms_bp_core_lua
217 \dontinclude lua/console/master_slave_bypass.lua
220 \subsubsection MSG_ext_ms_bp_master_lua Master code
222 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.
224 Lua style arguments (...) in for the master are interpreted as:
225 - the number of tasks to distribute
226 - the computation size of each task
227 - the size of the files associated to each task
228 - a list of host that will accept those tasks.
230 Tasks are dumbly sent in a round-robin style.
235 \subsubsection MSG_ext_ms_bp_slave_lua Slave code
237 This function has to be assigned to a #msg_process_t that has to behave as a slave.
238 This function keeps waiting for tasks and executes them as it receives them.
241 \subsubsection MSG_ext_ms_bp_core_lua Simulation core
243 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.
244 : <i>require "simgrid" </i>
246 -# Hosts : <i>simgrid.Host.new</i> instanciate a new host with an id, and power.
247 -# Links : <i>simgrid.Link.new</i> instanictae a new link that will require an id, bandwith and latency values.
248 -# Route : <i>simgrid.Route.new</i> define a route between two hosts specifying the links to use.
249 -# Simulation settings : <i>simgrid.register_platform();</i> register own platform without using the XML SURF parser.
251 we can also bypass the XML deployment file, and associate functions for each of defined hosts.
252 - <i>simgrid.Host.setFunction</i>: associate a function to a host, specifying arguments if needed.
253 - <i>simgrid.register_application()</i>: saving the deployment settings before running the simualtion.
255 \until simgrid.clean()