SimGrid  3.9
Versatile Simulation of Distributed Systems
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Bindings

Java Binding

Check online for our specific Simgrid-Java documentation.

Ruby Binding

Check online for our specific Simgrid-Ruby documentation.

Lua Binding

Most of Simgrid modules require a good level in C programming, since simgrid is used to be as standard C library. Sometime users prefer using some kind of “easy scripts” or a language easier to code with, for their works, which avoid dealing with C errors, and sometime an important gain of time. Besides Java Binding, Lua and Ruby bindings are available since version 3.4 of Simgrid for MSG Module, and we are currenlty working on bindings for other modules.

What is lua ?

Lua is a lightweight, reflective, imperative and functional programming language, designed as a scripting language with extensible semantics as a primary goal (see official web site here).

Why lua ?

Lua is a fast, portable and powerful script language, quite simple to use for developpers. it combines procedural features with powerful data description facilities, by using a simple, yet powerful, mechanism of tables. Lua has a relatively simple C API compared to other scripting languages, and accordingly it provides a robust, easy to use it.

How to use lua in Simgrid ?

Actually, the use of lua in Simgrid is quite simple, you have just to follow the same steps as coding with C in Simgird :

  • Coding functions coresponding to each process
  • loading the platforme/deployment XML file that describe the environment of simulation
  • and … Running the Simulation.

Master/Slave Example

  • Master Code
    function Master(...)
    if #arg ~= 4 then
    error("Wrong number of arguments (got " .. #arg ..
    ", expected 4: nb_tasks comp_size comm_size slave_count)")
    end
    simgrid.info("Hello from lua, I'm the master")
    local nb_task, comp_size, comm_size, slave_count = unpack(arg)
    -- Dispatch the tasks
    for i = 1, nb_task do
    local task = simgrid.task.new("Task " .. i, comp_size, comm_size)
    local task_name = task:get_name()
    local alias = "slave " .. (i % slave_count)
    simgrid.info("Sending '" .. task_name .. "' to '" .. alias .."'")
    task:send(alias) -- C user data set to NULL
    simgrid.info("Done sending '".. task_name .. "' to '" .. alias .."'")
    end
    -- Sending Finalize Message To Others
    simgrid.info("All tasks have been dispatched. Let's tell everybody the computation is over.")
    for i = 0, slave_count - 1 do
    local alias = "slave " .. i
    simgrid.info("Sending finalize to '" .. alias .. "'")
    local finalize = simgrid.task.new("finalize", comp_size, comm_size)
    finalize:send(alias)
    end
    simgrid.info("Everything's done.")
    end -- end_of_master
    we mainly use simgrid.Task.new(task_name,computation_size,communication_size) to create our MSG Task, then simgrid.Task.send(task,alias) to send it. we use also simgrid.Task.name(task), to get the task's name.
  • Slave Code
    function Slave(...)
    if #arg ~= 1 then
    error("Wrong number of arguments (got " .. #arg .. ", expected 1: slave_id)")
    end
    local my_mailbox = "slave " .. arg[1]
    simgrid.info("Hello from lua, I'm a poor slave with mailbox: " .. my_mailbox)
    while true do
    local task = simgrid.task.recv(my_mailbox)
    local task_name = task:get_name()
    if (task_name == "finalize") then
    simgrid.info("Got finalize message")
    break
    end
    simgrid.info("Received task '" .. task_name .. "' on mailbox '" .. my_mailbox .. "'")
    task:execute()
    simgrid.info("Task '" .. task_name .. "' is done")
    end
    simgrid.info("I'm done. See you!")
    end -- end_of_slave
    Here, we see the use of simgrid.Task.recv(alias) to receive a task with a specific alias, this function return directly the task recevied.
  • Set Environmenet and run application
    dofile 'master.lua'
    dofile 'slave.lua'
    -- Simulation Code ----------------------------------------------------------
    require "simgrid"
    simgrid.platform(arg[1])
    simgrid.application(arg[2])
    simgrid.run()
    simgrid.info("Simulation's over. See you.")
    -- end-of-master-slave

Exchanging Data

You can also exchange data between Process using lua. for that, you have to deal with lua task as a table, since lua is based itself on a mechanism of tables, so you can exchange any kind of data (tables, matrix, strings,…) between process via tasks.

  • Sender process
      task = simgrid.Task.new("data_task",task_comp,task_comm);
      task['matrix'] = my_matrix;
      task['table'] = my_table;
      task['message'] = "Hello from (Lua || Simgrid ) !! "
      …
      simgrid.Task.send(task,alias)
    
    After creating task, we associate to it various kind of data with a specific key (string in this case) to distinguish between data variables. The receiver will use this key to access easily to datas.
  • Receiver processe
      task = simgrid.Task.recv(alias);
      sender_matrix = task['matrix'];
      sender_table = task['table'];
      sender_message = task['message']
      ...
    
    Note that in lua, both sender and receiver share the same lua task. So that the receiver could joint data directly on the received task without sending it back. You can find a complet example (matrix multiplication case) in the file example/lua/mult_matrix.lua.

Bypass XML

maybe you wonder if there is a way to bypass the XML files, and describe your platform directly from the code, with lua bindings it's Possible !! how ? We provide some additional (tricky?) functions in lua that allows you to set up your own platform without using the XML files ( this can be useful for large platforms, so a simple for loop will avoid you to deal with an annoying XML File ;) )

  • set Routing mode
       simgrid.AS.new{id="AS0",mode="Full"};
    
  • set Hosts
      simgrid.Host.new{id="Tremblay",power=98095000};
      simgrid.Host.new{id="Jupiter",power=76296000};
      simgrid.Host.new{id="Fafard",power=76296000};
      simgrid.Host.new{id="Ginette",power=48492000};
      simgrid.Host.new{id="Bourassa",power=48492000};
    
    we use simgrid.Host.new{id=id_host,power=power_host} to instanciate our hosts.
  • set Links
      for i=0,11 do
        simgrid.Link.new{id=i,bandwidth=252750+ i*768,latency=0.000270544+i*0.087};    --  some crazy values ;)
      end
    
    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 ?)
  • set Routes
    -- simgrid.Route.new(src_id,des_id,links_nb,links_list)
       simgrid.Route.new("Tremblay","Jupiter",1,{"1"});
       simgrid.Route.new("Tremblay","Fafard",6,{"0","1","2","3","4","8"});
       simgrid.Route.new("Tremblay","Ginette",3,{"3","4","5"});
       simgrid.Route.new("Tremblay","Bourassa",7,{"0","1","3","2","4","6","7"});
    
       simgrid.Route.new("Jupiter","Tremblay",1,{"1"});
       simgrid.Route.new("Jupiter","Fafard",7,{"0","1","2","3","4","8","9"});
       simgrid.Route.new("Jupiter","Ginette",4,{"3","4","5","9"});
       simgrid.Route.new("Jupiter","Bourassa",8,{"0","1","2","3","4","6","7","9"});
       ...
    
    for each host you have to specify which route to choose to access to the rest of hosts connected in the grid.
  • Save platform
      simgrid.register_platform();
    
    Don't forget to register your platform, that SURF callbacks starts their work ;)
  • set application
       simgrid.Host.setFunction("Tremblay","Master",4,{"20","550000000","1000000","4"});
       simgrid.Host.setFunction("Bourassa","Slave",1,{"0"});
       simgrid.Host.setFunction("Jupiter","Slave",1,{"1"});
       simgrid.Host.setFunction("Fafard","Slave",1,{"2"});
       simgrid.Host.setFunction("Ginette","Slave",1,{"3"});
    
    you don't need to use a deployment XML file, thanks to simgrid.Host.setFunction(host_id,function,args_number,args_list) you can associate functions for each host with arguments if needed .
  •    simgrid.register_application();
    
    Yes, Here too you have to register your application before running the simulation.

the full example is distributed in the file examples/lua/master_slave_bypass.lua

Master/slave Lua application

Simulation of a master-slave application using lua bindings

Master code

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.

Lua style arguments (...) in for the master are interpreted as:

  • the number of tasks to distribute
  • the computation size of each task
  • the size of the files associated to each task
  • a list of host that will accept those tasks.

Tasks are dumbly sent in a round-robin style.

-- Dispatch the tasks
for i = 1, nb_task do
local task = simgrid.task.new("Task " .. i, comp_size, comm_size)
local task_name = task:get_name()
local alias = "slave " .. (i % slave_count)
simgrid.info("Sending '" .. task_name .. "' to '" .. alias .."'")
task:send(alias) -- C user data set to NULL
simgrid.info("Done sending '".. task_name .. "' to '" .. alias .."'")
end

Slave code

This function has to be assigned to a msg_process_t that has to behave as a slave. This function keeps waiting for tasks and executes them as it receives them.

function Slave(...)
if #arg ~= 1 then
error("Wrong number of arguments (got " .. #arg .. ", expected 1: slave_id)")
end
local my_mailbox = "slave " .. arg[1]
simgrid.info("Hello from lua, I'm a poor slave with mailbox: " .. my_mailbox)
while true do
local task = simgrid.task.recv(my_mailbox)
local task_name = task:get_name()
if (task_name == "finalize") then
simgrid.info("Got finalize message")
break
end
simgrid.info("Received task '" .. task_name .. "' on mailbox '" .. my_mailbox .. "'")
task:execute()
simgrid.info("Task '" .. task_name .. "' is done")
end
simgrid.info("I'm done. See you!")
end -- end_of_slave

Simulation core

in this section the core of the simulation which start by including the simgrid lib for bindings : require "simgrid"

  1. Simulation settings : simgrid.platform creates a realistic environment
  2. Application deployment : create the processes on the right locations with simgrid.application
  3. The simulation is run with simgrid.run

Its arguments are:

  • platform_file: the name of a file containing an valid surfxml platform description.( first command line argument)
  • application_file: the name of a file containing a valid surfxml application description ( second commande line argument )
    simgrid.platform(arg[1])
    simgrid.application(arg[2])
    simgrid.run()

Master/slave Bypass Lua application

Simulation of a master-slave application using lua bindings, Bypassing the XML parser

Master code

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.

Lua style arguments (...) in for the master are interpreted as:

  • the number of tasks to distribute
  • the computation size of each task
  • the size of the files associated to each task
  • a list of host that will accept those tasks.

Tasks are dumbly sent in a round-robin style.

--Master Function
function Master(...)
if #arg ~= 4 then
error("Wrong number of arguments (got " .. #arg ..
", expected 4: nb_tasks comp_size comm_size slave_count)")
end
simgrid.info("Hello from lua, I'm the master")
for i,v in ipairs(arg) do
simgrid.info("Got " .. v)
end
local nb_task, comp_size, comm_size, slave_count = unpack(arg)
simgrid.info("Argc=" .. (#arg) .. " (should be 4)")
-- Dispatch the tasks
for i = 1, nb_task do
task = simgrid.task.new("Task " .. i, comp_size, comm_size);
local task_name = simgrid.task.get_name(task)
alias = "slave " .. (i%slave_count);
simgrid.info("Master sending '" .. task_name .. "' To '" .. alias .. "'");
simgrid.task.send(task, alias); -- C user data set to NULL
simgrid.info("Master done sending '" .. task_name .. "' To '" .. alias .. "'");
end
-- Sending Finalize Message To Others
simgrid.info("Master: All tasks have been dispatched. Let's tell everybody the computation is over.");
for i = 0, slave_count-1 do
alias = "slave " .. i;
simgrid.info("Master: sending finalize to " .. alias);
finalize = simgrid.task.new("finalize", comp_size, comm_size);
simgrid.task.send(finalize, alias)
end
simgrid.info("Master: Everything's done.");
end
--end_of_master

Slave code

This function has to be assigned to a msg_process_t that has to behave as a slave. This function keeps waiting for tasks and executes them as it receives them.

-- Slave Function ---------------------------------------------------------
function Slave(...)
if #arg ~= 1 then
error("Wrong number of arguments (got " .. #arg .. ", expected 1: slave_id)")
end
local my_mailbox = "slave " .. arg[1]
simgrid.info("Hello from lua, I'm a poor slave with mbox: " .. my_mailbox)
while true do
local task = simgrid.task.recv(my_mailbox);
--print(task)
local task_name = task:get_name()
if (task:get_name() == "finalize") then
simgrid.info("Slave '" .. my_mailbox .. "' got finalize msg");
break
end
--local tk_name = simgrid.task.get_name(tk)
simgrid.info("Slave '" .. my_mailbox .. "' processing " .. task:get_name())
simgrid.task.execute(task)
simgrid.info("Slave '" .. my_mailbox .. "': task " .. task:get_name() .. " done")
end -- while
simgrid.info("Slave '" .. my_mailbox .. "': I'm Done . See You !!");
end
-- end_of_slave

Simulation core

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. : require "simgrid"

  1. Hosts : simgrid.Host.new instanciate a new host with an id, and power.
  2. Links : simgrid.Link.new instanictae a new link that will require an id, bandwith and latency values.
  3. Route : simgrid.Route.new define a route between two hosts specifying the links to use.
  4. Simulation settings : simgrid.register_platform(); register own platform without using the XML SURF parser.

we can also bypass the XML deployment file, and associate functions for each of defined hosts.

  • simgrid.Host.setFunction: associate a function to a host, specifying arguments if needed.
  • simgrid.register_application(): saving the deployment settings before running the simualtion.
require "simgrid"
dofile 'platform.lua'
dofile 'deploy.lua'
--Rutform.lua'
dofile 'master.lua'
dofile 'slave.lua'
simgrid.run()
simgrid.info("Simulation's over.See you.")