doc/bindings.doc

   1 /*! \page bindings Bindings
   2
   3 \htmlinclude .bindings.doc.toc
   4
   5 \section bindings_binding_Java Java Binding
   6 <a href="http://simgrid.gforge.inria.fr/simgrid-java/1.0/doc/">Simgrid-Java documentation</a>.
   7
   8 \section bindings_binding_Ruby Ruby Binding
   9 <a href="http://simgrid.gforge.inria.fr/simgrid-ruby/1.0/doc/">Simgrid-Ruby documentation</a>.
  10
  11 \section bindings_binding_lua Lua Binding
  12
  13 Most of Simgrid modules require a  good level in C programming, since simgrid is used to be as standard C library.
  14  Sometime users prefer using some kind of « easy scripts » or a language easier to code with, for their works,
  15  which avoid dealing with C errors, and sometime an important  gain of time.
  16 Besides Java Binding, Lua  and Ruby bindings are available since version 3.4 of Simgrid
  17 for MSG Module, and we are currenlty working on bindings for other modules.
  18
  19
  20 \subsection bindings_binding_lua_about What is lua ?
  21 Lua is a lightweight, reflective, imperative and functional programming language,
  22  designed as a scripting language with extensible semantics as a primary goal (see official web site <a href="http://www.lua.org">here</a>).
  23 \subsubsection bindings_binding_lua_why Why lua ?
  24 Lua is a fast, portable and powerful script language, quite simple to use for developpers.
  25 it combines procedural features with powerful data description facilities,
  26  by using a simple, yet powerful, mechanism of tables.
  27 Lua has a relatively simple C API compared to other scripting languages,
  28 and accordingly it provides a robust, easy to use it.
  29 \subsubsection bindings_binding_lua_simgrid How to use lua in Simgrid ?
  30 Actually, the use of lua in Simgrid is quite simple, you have just to follow the same steps as coding with C in Simgird :
  31   - Coding functions coresponding to each process
  32   - loading the platforme/deployment XML file that describe the environment of simulation
  33   - and … Running the Simulation.
  34
  35 \dontinclude lua/masterslave/master.lua
  36 \subsection bindings_binding_lua_example_master_slave Master/Slave Example
  37
  38  \li Master Code
  39  \until end_of_master
  40 we mainly  use   simgrid.Task.new(task_name,computation_size,communication_size) to create our MSG Task,
  41          then simgrid.Task.send(task,alias) to send it.
  42 we use also simgrid.Task.name(task), to get the task's name.
  43
  44 \dontinclude lua/masterslave/slave.lua
  45 \li Slave Code
  46 \until end_of_slave
  47 Here, we see the use of simgrid.Task.recv(alias) to receive a task with a specific alias,
  48 this function return directly the task recevied.
  49
  50 \dontinclude lua/masterslave/master_slave.lua
  51 \li Set Environmenet and run application
  52 \until simgrid.clean()
  53
  54 \subsection bindings_binding_lua_example_data Exchanging Data
  55 You can also exchange data between Process using lua. for that, you have to deal with lua task as a table,
  56 since lua is based itself on a mechanism of tables,
  57 so you can exchange any kind of data (tables, matrix, strings,…) between process via tasks.
  58
  59 \li Sender process
  60 \verbatim
  61   task = simgrid.Task.new("data_task",task_comp,task_comm);
  62   task['matrix'] = my_matrix;
  63   task['table'] = my_table;
  64   task['message'] = "Hello from (Lua || Simgrid ) !! "
  65   …
  66   simgrid.Task.send(task,alias)
  67 \endverbatim
  68         After creating task, we associate to it various kind of data with a specific key (string in this case)
  69         to distinguish between data variables. The receiver will use this key to access easily to datas.
  70
  71
  72 \li Receiver processe
  73 \verbatim
  74   task = simgrid.Task.recv(alias);
  75   sender_matrix = task['matrix'];
  76   sender_table = task['table'];
  77   sender_message = task['message']
  78   ...
  79 \endverbatim
  80         Note that in lua, both sender and receiver share the same lua task.
  81         So that the receiver could joint data directly on the received task without sending it back.
  82         You can find  a complet example (matrix multiplication case) in the file example/lua/mult_matrix.lua.
  83
  84
  85 \subsection bindings_binding_lua_example_bypass Bypass XML
  86         maybe you wonder if there is a way to bypass the XML files,
  87          and describe your platform directly from the code, with lua bindings it's Possible !! how ?
  88         We provide some additional (tricky?) functions in lua that allows you to set up your own platform without using the XML files
  89      ( this can be useful for large platforms, so a simple for loop will avoid you to deal with an annoying XML File ;) )
  90
  91
  92 \li set Routing mode
  93 \verbatim
  94    simgrid.AS.new{id="AS0",mode="Full"};
  95 \endverbatim
  96
  97 \li set Hosts
  98 \verbatim
  99   simgrid.Host.new{id="Tremblay",power=98095000};
 100   simgrid.Host.new{id="Jupiter",power=76296000};
 101   simgrid.Host.new{id="Fafard",power=76296000};
 102   simgrid.Host.new{id="Ginette",power=48492000};
 103   simgrid.Host.new{id="Bourassa",power=48492000};
 104 \endverbatim
 105   we use simgrid.Host.new{id=id_host,power=power_host} to instanciate our hosts.
 106
 107 \li set Links
 108 \verbatim
 109   for i=0,11 do
 110     simgrid.Link.new{id=i,bandwidth=252750+ i*768,latency=0.000270544+i*0.087};    --  some crazy values ;)
 111   end
 112 \endverbatim
 113   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 ?)
 114
 115 \li set Routes
 116 \verbatim
 117 -- simgrid.Route.new(src_id,des_id,links_nb,links_list)
 118    simgrid.Route.new("Tremblay","Jupiter",1,{"1"});
 119    simgrid.Route.new("Tremblay","Fafard",6,{"0","1","2","3","4","8"});
 120    simgrid.Route.new("Tremblay","Ginette",3,{"3","4","5"});
 121    simgrid.Route.new("Tremblay","Bourassa",7,{"0","1","3","2","4","6","7"});
 122
 123    simgrid.Route.new("Jupiter","Tremblay",1,{"1"});
 124    simgrid.Route.new("Jupiter","Fafard",7,{"0","1","2","3","4","8","9"});
 125    simgrid.Route.new("Jupiter","Ginette",4,{"3","4","5","9"});
 126    simgrid.Route.new("Jupiter","Bourassa",8,{"0","1","2","3","4","6","7","9"});
 127    ...
 128 \endverbatim
 129   for each host you have to specify which route to choose to access to the rest of hosts connected in the grid.
 130
 131 \li Save platform
 132 \verbatim
 133   simgrid.register_platform();
 134 \endverbatim
 135 Don't forget to register your platform, that SURF callbacks starts their work ;)
 136
 137 \li set application
 138 \verbatim
 139    simgrid.Host.setFunction("Tremblay","Master",4,{"20","550000000","1000000","4"});
 140    simgrid.Host.setFunction("Bourassa","Slave",1,{"0"});
 141    simgrid.Host.setFunction("Jupiter","Slave",1,{"1"});
 142    simgrid.Host.setFunction("Fafard","Slave",1,{"2"});
 143    simgrid.Host.setFunction("Ginette","Slave",1,{"3"});
 144 \endverbatim
 145   you don't  need to use a deployment XML file, thanks to  simgrid.Host.setFunction(host_id,function,args_number,args_list)
 146   you can associate functions for each host with arguments if needed .
 147
 148 \li
 149 \verbatim
 150    simgrid.register_application();
 151 \endverbatim
 152 Yes, Here too you have to resgiter your application before running the simulation.
 153
 154 the full example is distributed in the file examples/lua/master_slave_bypass.lua
 155
 156  */