doc/user_guide/doxygen/bindings.doc

   1 /*! \page bindings Bindings
   2
   3
   4 \section bindings_binding_Java Java Binding
   5 Check online for our specific <a href="http://simgrid.gforge.inria.fr/documentation.html">Simgrid-Java documentation</a>.
   6
   7 \section bindings_binding_Ruby Ruby Binding
   8 Check online for our specific <a href="http://simgrid.gforge.inria.fr/documentation.html">Simgrid-Ruby documentation</a>.
   9
  10 \section bindings_binding_lua Lua Binding
  11
  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.
  17
  18
  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.
  33
  34 \dontinclude lua/masterslave/master.lua
  35 \subsection bindings_binding_lua_example_master_slave Master/Slave Example
  36
  37  \li Master Code
  38  \until end_of_master
  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.
  42
  43 \dontinclude lua/masterslave/slave.lua
  44 \li Slave Code
  45 \until end_of_slave
  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.
  48
  49 \dontinclude lua/masterslave/master_slave.lua
  50 \li Set Environmenet and run application
  51 \until end-of-master-slave
  52
  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.
  57
  58 \li Sender process
  59 \verbatim
  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 ) !! "
  64   …
  65   simgrid.Task.send(task,alias)
  66 \endverbatim
  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.
  69
  70
  71 \li Receiver processe
  72 \verbatim
  73   task = simgrid.Task.recv(alias);
  74   sender_matrix = task['matrix'];
  75   sender_table = task['table'];
  76   sender_message = task['message']
  77   ...
  78 \endverbatim
  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.
  82
  83
  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 ;) )
  89
  90
  91 \li set Routing mode
  92 \verbatim
  93    simgrid.AS.new{id="AS0",mode="Full"};
  94 \endverbatim
  95
  96 \li set Hosts
  97 \verbatim
  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};
 103 \endverbatim
 104   we use simgrid.Host.new{id=id_host,power=power_host} to instanciate our hosts.
 105
 106 \li set Links
 107 \verbatim
 108   for i=0,11 do
 109     simgrid.Link.new{id=i,bandwidth=252750+ i*768,latency=0.000270544+i*0.087};    --  some crazy values ;)
 110   end
 111 \endverbatim
 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 ?)
 113
 114 \li set Routes
 115 \verbatim
 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"});
 121
 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"});
 126    ...
 127 \endverbatim
 128   for each host you have to specify which route to choose to access to the rest of hosts connected in the grid.
 129
 130 \li Save platform
 131 \verbatim
 132   simgrid.register_platform();
 133 \endverbatim
 134 Don't forget to register your platform, that SURF callbacks starts their work ;)
 135
 136 \li set application
 137 \verbatim
 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"});
 143 \endverbatim
 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 .
 146
 147 \li
 148 \verbatim
 149    simgrid.register_application();
 150 \endverbatim
 151 Yes, Here too you have to register your application before running the simulation.
 152
 153 the full example is distributed in the file examples/lua/master_slave_bypass.lua
 154
 155 \subsection MSG_ex_master_slave_lua Master/slave Lua application
 156
 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
 161 - \ref MSG_ext_ms_helping
 162 - \ref MSG_ext_ms_application
 163 - \ref MSG_ext_ms_platform
 164
 165
 166
 167 \subsubsection MSG_ext_ms_master_lua Master code
 168
 169 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.
 170
 171 Lua style arguments (...) in for the master are interpreted as:
 172 - the number of tasks to distribute
 173 - the computation size of each task
 174 - the size of the files associated to each task
 175 - a list of host that will accept those tasks.
 176
 177 Tasks are dumbly sent in a round-robin style.
 178 \dontinclude lua/masterslave/master.lua
 179 \skip Dispatch the tasks
 180 \until Done sending
 181 \until end
 182
 183
 184 \subsubsection MSG_ext_ms_slave_lua Slave code
 185
 186 This function has to be assigned to a #msg_process_t that has to behave as a slave.
 187 This function keeps waiting for tasks and executes them as it receives them.
 188 \dontinclude lua/masterslave/slave.lua
 189 \until end_of_slave
 190 \subsubsection MSG_ext_ms_core_lua Simulation core
 191
 192 in this section the core of the simulation which start by including the simgrid lib for bindings
 193 : <i>require "simgrid" </i>
 194
 195 -# Simulation settings : <i>simgrid.platform</i> creates a realistic
 196    environment
 197 -# Application deployment : create the processes on the right locations with
 198     <i>simgrid.application</i>
 199 -# The simulation is run with <i>simgrid.run</i>
 200
 201 Its arguments are:
 202 - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.( first command line argument)
 203 - <i>application_file</i>: the name of a file containing a valid surfxml application description ( second commande line argument )
 204 \dontinclude lua/masterslave/master_slave.lua
 205 \skip platform
 206 \until run
 207
 208
 209 \subsection MSG_ex_master_slave_lua_bypass Master/slave Bypass Lua application
 210
 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
 215
 216
 217
 218 \subsubsection MSG_ext_ms_bp_master_lua Master code
 219
 220 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.
 221
 222 Lua style arguments (...) in for the master are interpreted as:
 223 - the number of tasks to distribute
 224 - the computation size of each task
 225 - the size of the files associated to each task
 226 - a list of host that will accept those tasks.
 227
 228 Tasks are dumbly sent in a round-robin style.
 229
 230 \dontinclude lua/console/master.lua
 231 \until end_of_master
 232
 233 \subsubsection MSG_ext_ms_bp_slave_lua Slave code
 234
 235 This function has to be assigned to a #msg_process_t that has to behave as a slave.
 236 This function keeps waiting for tasks and executes them as it receives them.
 237
 238 \dontinclude lua/console/slave.lua
 239 \until end_of_slave
 240
 241 \subsubsection MSG_ext_ms_bp_core_lua Simulation core
 242
 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>
 245
 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.
 250
 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.
 254
 255 \include lua/console/master_slave_bypass.lua
 256
 257
 258  */