SimGrid  3.13
Versatile Simulation of Distributed Systems
SimGrid Examples
Note
This page is under work – sorry for the inconvenience (FIXME).

SimGrid comes with many examples provided in the examples/ directory. Those examples are described in section MSG examples. Those examples are commented and should be easy to understand. for a first step into SimGrid we also provide some more detailed examples in the sections below.

You should also check our online tutorial section that contains a generic tutorial about using SimGrid.

Using MSG

You should also check our online tutorial section that contains a dedicated tutorial.

Here are some examples on how to use MSG, the most used API.

MSG comes with an extensive set of examples. It is sometimes difficult to find the one you need. This list aims at helping you finding the example from which you can learn what you want to.

Basic examples and features

Basic Master/Workers

Simulation of a master-worker application using a realistic platform and an external description of the deployment.

Table of contents:


Preliminary declarations

#include "simgrid/msg.h"
XBT_LOG_NEW_DEFAULT_CATEGORY(msg_app_masterworker, "Messages specific for this msg example");

Master code

This function has to be assigned to a msg_process_t that will behave as the master. It should not be called directly but either given as a parameter to MSG_process_create() or registered as a public function through MSG_function_register() and then automatically assigned to a process through MSG_launch_application().

C style arguments (argc/argv) are interpreted as:

  • the number of tasks to distribute
  • the computational size of each task
  • the communication size of each task
  • the number of workers managed by the master.

Tasks are evenly sent in a round-robin style.

static int master(int argc, char *argv[])
{
long number_of_tasks = xbt_str_parse_int(argv[1], "Invalid amount of tasks: %s");
double comp_size = xbt_str_parse_double(argv[2], "Invalid computational size: %s");
double comm_size = xbt_str_parse_double(argv[3], "Invalid communication size: %s");
long workers_count = xbt_str_parse_int(argv[4], "Invalid amount of workers: %s");
int i;
XBT_INFO("Got %ld workers and %ld tasks to process", workers_count, number_of_tasks);
for (i = 0; i < number_of_tasks; i++) {
char mailbox[256];
char task_name[256];
sprintf(mailbox, "worker-%ld", i % workers_count);
sprintf(task_name, "Task_%d", i);
msg_task_t task = MSG_task_create(task_name, comp_size, comm_size, NULL);
if (number_of_tasks < 10000 || i % 10000 == 0)
XBT_INFO("Sending \"%s\" (of %ld) to mailbox \"%s\"", task->name, number_of_tasks, mailbox);
MSG_task_send(task, mailbox);
}
XBT_INFO("All tasks have been dispatched. Let's tell everybody the computation is over.");
for (i = 0; i < workers_count; i++) {
char mailbox[80];
sprintf(mailbox, "worker-%ld", i % workers_count);
msg_task_t finalize = MSG_task_create("finalize", 0, 0, 0);
MSG_task_send(finalize, mailbox);
}
return 0;
}

Worker code

This function has to be assigned to a msg_process_t that has to behave as a worker. Just like the master function (described in Master code), it should not be called directly.

C style arguments (argc/argv) are interpreted as:

  • a unique id used to build the mailbox name of the worker

This function keeps waiting for tasks and executes them as it receives them. When a special task named 'finalize' is received from the master, the process ends its execution.

static int worker(int argc, char *argv[])
{
msg_task_t task = NULL;
char mailbox[80];
long id= xbt_str_parse_int(argv[1], "Invalid argument %s");
sprintf(mailbox, "worker-%ld", id);
while (1) {
int res = MSG_task_receive(&(task), mailbox);
xbt_assert(res == MSG_OK, "MSG_task_get failed");
// XBT_INFO("Received \"%s\"", MSG_task_get_name(task));
if (!strcmp(MSG_task_get_name(task), "finalize")) {
break;
}
// XBT_INFO("Processing \"%s\"", MSG_task_get_name(task));
// XBT_INFO("\"%s\" done", MSG_task_get_name(task));
task = NULL;
}
XBT_INFO("I'm done. See you!");
return 0;
}

Main function

This function is the core of the simulation and is divided only into 3 parts:

  1. Simulation settings : MSG_create_environment() creates a realistic environment
  2. Application deployment : create the processes on the right locations with MSG_launch_application()
  3. The simulation is run with MSG_main()

Its arguments are:

Example of a platform file

The following platform description can be found in examples/msg/platforms/small_platform.xml

1 <?xml version='1.0'?>
2 <!DOCTYPE platform SYSTEM "http://simgrid.gforge.inria.fr/simgrid/simgrid.dtd">
3 <platform version="4">
4  <AS id="AS0" routing="Full">
5  <host id="Tremblay" speed="98.095Mf"/>
6  <host id="Jupiter" speed="76.296Mf"/>
7  <host id="Fafard" speed="76.296Mf"/>
8  <host id="Ginette" speed="48.492Mf"/>
9  <host id="Bourassa" speed="48.492Mf"/>
10 
11  <link id="6" bandwidth="41.279125MBps" latency="59.904us"/>
12  <link id="3" bandwidth="34.285625MBps" latency="514.433us"/>
13  <link id="7" bandwidth="11.618875MBps" latency="189.98us"/>
14  <link id="9" bandwidth="7.20975MBps" latency="1.461517ms"/>
15  <link id="2" bandwidth="118.6825MBps" latency="136.931us"/>
16  <link id="8" bandwidth="8.158MBps" latency="270.544us"/>
17  <link id="1" bandwidth="34.285625MBps" latency="514.433us"/>
18  <link id="4" bandwidth="10.099625MBps" latency="479.78us"/>
19  <link id="0" bandwidth="41.279125MBps" latency="59.904us"/>
20  <link id="5" bandwidth="27.94625MBps" latency="278.066us"/>
21  <link id="loopback" bandwidth="498MBps" latency="15us" sharing_policy="FATPIPE"/>
22 
23  <route src="Tremblay" dst="Tremblay"><link_ctn id="loopback"/></route>
24  <route src="Jupiter" dst="Jupiter"><link_ctn id="loopback"/></route>
25  <route src="Fafard" dst="Fafard"><link_ctn id="loopback"/></route>
26  <route src="Ginette" dst="Ginette"><link_ctn id="loopback"/></route>
27  <route src="Bourassa" dst="Bourassa"><link_ctn id="loopback"/></route>
28  <route src="Tremblay" dst="Jupiter"><link_ctn id="9"/></route>
29  <route src="Tremblay" dst="Fafard"><link_ctn id="4"/><link_ctn id="3"/><link_ctn id="2"/><link_ctn id="0"/><link_ctn id="1"/><link_ctn id="8"/></route>
30  <route src="Tremblay" dst="Ginette"><link_ctn id="4"/><link_ctn id="3"/><link_ctn id="5"/></route>
31  <route src="Tremblay" dst="Bourassa"><link_ctn id="4"/><link_ctn id="3"/><link_ctn id="2"/><link_ctn id="0"/><link_ctn id="1"/><link_ctn id="6"/><link_ctn id="7"/></route>
32  <route src="Jupiter" dst="Fafard"><link_ctn id="9"/><link_ctn id="4"/><link_ctn id="3"/><link_ctn id="2"/><link_ctn id="0"/><link_ctn id="1"/><link_ctn id="8"/></route>
33  <route src="Jupiter" dst="Ginette"><link_ctn id="9"/><link_ctn id="4"/><link_ctn id="3"/><link_ctn id="5"/></route>
34  <route src="Jupiter" dst="Bourassa"><link_ctn id="9"/><link_ctn id="4"/><link_ctn id="3"/><link_ctn id="2"/><link_ctn id="0"/><link_ctn id="1"/><link_ctn id="6"/><link_ctn id="7"/></route>
35  <route src="Fafard" dst="Ginette"><link_ctn id="8"/><link_ctn id="1"/><link_ctn id="0"/><link_ctn id="2"/><link_ctn id="5"/></route>
36  <route src="Fafard" dst="Bourassa"><link_ctn id="8"/><link_ctn id="6"/><link_ctn id="7"/></route>
37  <route src="Ginette" dst="Bourassa"><link_ctn id="5"/><link_ctn id="2"/><link_ctn id="0"/><link_ctn id="1"/><link_ctn id="6"/><link_ctn id="7"/></route>
38  </AS>
39 </platform>

Example of a deployment file

The following application description can be found in examples/msg/app-masterworker/app-masterworker_d.xml:

1 <?xml version='1.0'?>
2 <!DOCTYPE platform SYSTEM "http://simgrid.gforge.inria.fr/simgrid/simgrid.dtd">
3 <platform version="4">
4  <!-- The master process (with some arguments) -->
5  <process host="Tremblay" function="master">
6  <argument value="20"/> <!-- Number of tasks -->
7  <argument value="50000000"/> <!-- Computation size of tasks -->
8  <argument value="1000000"/> <!-- Communication size of tasks -->
9  <argument value="5"/> <!-- Number of workers -->
10  </process>
11  <!-- The worker processes (with mailbox to listen on as argument) -->
12  <process host="Tremblay" function="worker" on_failure="RESTART"> <argument value="0"/> </process>
13  <process host="Jupiter" function="worker" on_failure="RESTART"> <argument value="1"/> </process>
14  <process host="Fafard" function="worker" on_failure="RESTART"> <argument value="2"/> </process>
15  <process host="Ginette" function="worker" on_failure="RESTART"> <argument value="3"/> </process>
16  <process host="Bourassa" function="worker" on_failure="RESTART"> <argument value="4"/> </process>
17 </platform>

Asynchronous communications

Simulation of asynchronous communications between a sender and a receiver using a realistic platform and an external description of the deployment.


Code of the application

Preliminary declarations

#include "simgrid/msg.h"
XBT_LOG_NEW_DEFAULT_CATEGORY(msg_async_wait, "Messages specific for this msg example");

Sender function

A host can send an asynchronous message with MSG_task_isend(). As this function is non-blocking, we have to call MSG_comm_test() to know if the communication is complete and evenetually destroy it with a call to MSG_comm_destroy(). It is also possible to call MSG_comm_wait() which provides a shortcut.

C style arguments (argc/argv) are interpreted as:

  • the number of tasks to distribute
  • the computation size of each task
  • the size of the files associated to each task
  • the number of receivers that will accept those tasks
  • the time to sleep at the beginning of the function. This time defines the process sleep time:

static int sender(int argc, char *argv[])
{
long number_of_tasks = xbt_str_parse_int(argv[1], "Invalid amount of tasks: %s");
double task_comp_size = xbt_str_parse_double(argv[2], "Invalid computational size: %s");
double task_comm_size = xbt_str_parse_double(argv[3], "Invalid communication size: %s");
long receivers_count = xbt_str_parse_int(argv[4], "Invalid amount of receivers: %s");
double sleep_start_time = xbt_str_parse_double(argv[5], "Invalid sleep start time: %s");
double sleep_test_time = xbt_str_parse_double(argv[6], "Invalid test time: %s");
XBT_INFO("sleep_start_time : %f , sleep_test_time : %f", sleep_start_time, sleep_test_time);
int i;
msg_task_t task = NULL;
msg_comm_t comm = NULL;
MSG_process_sleep(sleep_start_time);
for (i = 0; i < number_of_tasks; i++) {
char mailbox[256];
char sprintf_buffer[256];
sprintf(mailbox, "receiver-%ld", i % receivers_count);
sprintf(sprintf_buffer, "Task_%d", i);
task = MSG_task_create(sprintf_buffer, task_comp_size, task_comm_size, NULL);
comm = MSG_task_isend(task, mailbox);
XBT_INFO("Send to receiver-%ld Task_%d", i % receivers_count, i);
if (sleep_test_time == 0) {
MSG_comm_wait(comm, -1);
} else {
while (MSG_comm_test(comm) == 0) {
MSG_process_sleep(sleep_test_time);
};
}
}
for (i = 0; i < receivers_count; i++) {
char mailbox[80];
sprintf(mailbox, "receiver-%ld", i % receivers_count);
task = MSG_task_create("finalize", 0, 0, 0);
comm = MSG_task_isend(task, mailbox);
XBT_INFO("Send to receiver-%ld finalize", i % receivers_count);
if (sleep_test_time == 0) {
MSG_comm_wait(comm, -1);
} else {
while (MSG_comm_test(comm) == 0) {
MSG_process_sleep(sleep_test_time);
};
}
}
XBT_INFO("Goodbye now!");
return 0;
}

Receiver function

This function executes tasks when it receives them. As the receiving is asynchronous, we have to test the completion of the communication with MSG_comm_test() or wait for it with MSG_comm_wait().

C style arguments (argc/argv) are interpreted as:

  • the id to use for received the communication.
  • the time to sleep at the beginning of the function
  • This time defined the process sleep time

static int receiver(int argc, char *argv[])
{
msg_task_t task = NULL;
char mailbox[80];
msg_comm_t res_irecv;
int id = xbt_str_parse_int(argv[1], "Invalid id: %s");
double sleep_start_time = xbt_str_parse_double(argv[2], "Invalid sleep start parameter: %s");
double sleep_test_time = xbt_str_parse_double(argv[3], "Invalid sleep test parameter: %s");
XBT_INFO("sleep_start_time : %f , sleep_test_time : %f", sleep_start_time, sleep_test_time);
MSG_process_sleep(sleep_start_time);
sprintf(mailbox, "receiver-%d", id);
while (1) {
res_irecv = MSG_task_irecv(&(task), mailbox);
XBT_INFO("Wait to receive a task");
if (sleep_test_time == 0) {
res = MSG_comm_wait(res_irecv, -1);
xbt_assert(res == MSG_OK, "MSG_task_get failed");
} else {
while (MSG_comm_test(res_irecv) == 0) {
MSG_process_sleep(sleep_test_time);
};
}
MSG_comm_destroy(res_irecv);
XBT_INFO("Received \"%s\"", MSG_task_get_name(task));
if (!strcmp(MSG_task_get_name(task), "finalize")) {
break;
}
XBT_INFO("Processing \"%s\"", MSG_task_get_name(task));
XBT_INFO("\"%s\" done", MSG_task_get_name(task));
task = NULL;
}
XBT_INFO("I'm done. See you!");
return 0;
}

Main function

This function is the core of the simulation and is divided only into 3 parts:

  1. Simulation settings : MSG_create_environment() loads a platform description
  2. Application deployment : create the processes on the right locations with MSG_launch_application()
  3. The simulation is run with MSG_main()

Its arguments are:

  • platform_file: the name of a file containing an valid platform description.
  • application_file: the name of a file containing a valid application deployment.

int main(int argc, char *argv[])
{
MSG_init(&argc, argv);
xbt_assert(argc > 2, "Usage: %s platform_file deployment_file\n"
"\tExample: %s msg_platform.xml msg_deployment.xml\n", argv[0], argv[0]);
res = MSG_main();
XBT_INFO("Simulation time %g", MSG_get_clock());
return res != MSG_OK;
}

Waitall function

The use of MSG_comm_waitall() allows a process to send all the tasks and then wait for the completion of all in one call.

static int sender(int argc, char *argv[])
{
long number_of_tasks = xbt_str_parse_int(argv[1], "Invalid amount of tasks: %s");
double task_comp_size = xbt_str_parse_double(argv[2], "Invalid computational size: %s");
double task_comm_size = xbt_str_parse_double(argv[3], "Invalid communication size: %s");
long receivers_count = xbt_str_parse_int(argv[4], "Invalid amount of receivers: %s");
msg_comm_t *comm = xbt_new(msg_comm_t, number_of_tasks + receivers_count);
int i;
msg_task_t task = NULL;
for (i = 0; i < number_of_tasks; i++) {
char mailbox[256];
char sprintf_buffer[256];
sprintf(mailbox, "receiver-%ld", i % receivers_count);
sprintf(sprintf_buffer, "Task_%d", i);
task = MSG_task_create(sprintf_buffer, task_comp_size, task_comm_size, NULL);
comm[i] = MSG_task_isend(task, mailbox);
XBT_INFO("Send to receiver-%ld Task_%d", i % receivers_count, i);
}
for (i = 0; i < receivers_count; i++) {
char mailbox[80];
sprintf(mailbox, "receiver-%ld", i % receivers_count);
task = MSG_task_create("finalize", 0, 0, 0);
comm[i + number_of_tasks] = MSG_task_isend(task, mailbox);
XBT_INFO("Send to receiver-%ld finalize", i % receivers_count);
}
/* Here we are waiting for the completion of all communications */
MSG_comm_waitall(comm, (number_of_tasks + receivers_count), -1);
for (i = 0; i < number_of_tasks + receivers_count; i++)
MSG_comm_destroy(comm[i]);
XBT_INFO("Goodbye now!");
xbt_free(comm);
return 0;
}

Waitany function

The MSG_comm_waitany() function returns the place of the first message send or receive from a xbt_dynar.

static int receiver(int argc, char *argv[])
{
msg_task_t task = NULL;
int id = -1;
char mailbox[80];
msg_comm_t res_irecv;
read = sscanf(argv[1], "%d", &id);
xbt_assert(read, "Invalid argument %s\n", argv[1]);
sprintf(mailbox, "receiver-%d", id);
while (1) {
res_irecv = MSG_task_irecv(&(task), mailbox);
XBT_INFO("Wait to receive a task");
res = MSG_comm_wait(res_irecv, -1);
MSG_comm_destroy(res_irecv);
xbt_assert(res == MSG_OK, "MSG_task_get failed");
XBT_INFO("Received \"%s\"", MSG_task_get_name(task));
if (!strcmp(MSG_task_get_name(task), "finalize")) {
break;
}
XBT_INFO("Processing \"%s\"", MSG_task_get_name(task));
XBT_INFO("\"%s\" done", MSG_task_get_name(task));
task = NULL;
}
XBT_INFO("I'm done. See you!");
return 0;
}