SimGrid  3.17
Versatile Simulation of Distributed Systems
SimGrid Examples

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.

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.

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:

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

Example of a platform file

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

<?xml version='1.0'?>
<!DOCTYPE platform SYSTEM "http://simgrid.gforge.inria.fr/simgrid/simgrid.dtd">
<platform version="4.1">
<zone id="zone0" routing="Full">
<host id="Tremblay" speed="98.095Mf"/>
<host id="Jupiter" speed="76.296Mf"/>
<host id="Fafard" speed="76.296Mf"/>
<host id="Ginette" speed="48.492Mf"/>
<host id="Bourassa" speed="48.492Mf"/>
<host id="Jacquelin" speed="137.333Mf"/>
<host id="Boivin" speed="98.095Mf"/>
<link id="6" bandwidth="41.279125MBps" latency="59.904us"/>
<link id="3" bandwidth="34.285625MBps" latency="514.433us"/>
<link id="7" bandwidth="11.618875MBps" latency="189.98us"/>
<link id="9" bandwidth="7.20975MBps" latency="1.461517ms"/>
<link id="2" bandwidth="118.6825MBps" latency="136.931us"/>
<link id="8" bandwidth="8.158MBps" latency="270.544us"/>
<link id="1" bandwidth="34.285625MBps" latency="514.433us"/>
<link id="4" bandwidth="10.099625MBps" latency="479.78us"/>
<link id="0" bandwidth="41.279125MBps" latency="59.904us"/>
<link id="5" bandwidth="27.94625MBps" latency="278.066us"/>
<link id="145" bandwidth="2.583375MBps" latency="410.463us"/>
<link id="10" bandwidth="34.285625MBps" latency="514.433us"/>
<link id="11" bandwidth="118.6825MBps" latency="136.931us"/>
<link id="16" bandwidth="34.285625MBps" latency="514.433us"/>
<link id="17" bandwidth="118.6825MBps" latency="136.931us"/>
<link id="44" bandwidth="10.314625MBps" latency="6.932556ms"/>
<link id="47" bandwidth="10.314625MBps" latency="6.932556ms"/>
<link id="54" bandwidth="15.376875MBps" latency="35.083019ms"/>
<link id="56" bandwidth="21.41475MBps" latency="29.5890617ms"/>
<link id="59" bandwidth="11.845375MBps" latency="370.788us"/>
<link id="78" bandwidth="27.94625MBps" latency="278.066us"/>
<link id="79" bandwidth="8.42725MBps" latency="156.056us"/>
<link id="80" bandwidth="15.376875MBps" latency="35.083019ms"/>
<link id="loopback" bandwidth="498MBps" latency="15us" sharing_policy="FATPIPE"/>
<route src="Tremblay" dst="Tremblay">
<link_ctn id="loopback"/>
</route>
<route src="Jupiter" dst="Jupiter">
<link_ctn id="loopback"/>
</route>
<route src="Fafard" dst="Fafard">
<link_ctn id="loopback"/>
</route>
<route src="Ginette" dst="Ginette">
<link_ctn id="loopback"/>
</route>
<route src="Bourassa" dst="Bourassa">
<link_ctn id="loopback"/>
</route>
<route src="Tremblay" dst="Jupiter">
<link_ctn id="9"/>
</route>
<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>
<route src="Tremblay" dst="Ginette">
<link_ctn id="4"/>
<link_ctn id="3"/>
<link_ctn id="5"/>
</route>
<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>
<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>
<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>
<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>
<route src="Jupiter" dst="Jacquelin">
<link_ctn id="145"/>
</route>
<route src="Jupiter" dst="Boivin">
<link_ctn id="47"/>
</route>
<route src="Jupiter" dst="Ginette">
<link_ctn id="9"/>
<link_ctn id="4"/>
<link_ctn id="3"/>
<link_ctn id="5"/>
</route>
<route src="Fafard" dst="Bourassa">
<link_ctn id="8"/>
<link_ctn id="6"/>
<link_ctn id="7"/>
</route>
<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>
<route src="Ginette" dst="Jacquelin">
<link_ctn id="145"/>
</route>
<route src="Ginette" dst="Boivin">
<link_ctn id="47"/>
</route>
<route src="Bourassa" dst="Jacquelin">
<link_ctn id="145"/>
</route>
<route src="Bourassa" dst="Boivin">
<link_ctn id="47"/>
</route>
<route src="Jacquelin" dst="Boivin">
<link_ctn id="145"/>
<link_ctn id="59"/>
<link_ctn id="56"/>
<link_ctn id="54"/>
<link_ctn id="17"/>
<link_ctn id="16"/>
<link_ctn id="10"/>
<link_ctn id="11"/>
<link_ctn id="44"/>
<link_ctn id="47"/>
</route>
<route src="Jacquelin" dst="Fafard">
<link_ctn id="145"/>
<link_ctn id="59"/>
<link_ctn id="56"/>
<link_ctn id="54"/>
<link_ctn id="17"/>
<link_ctn id="16"/>
<link_ctn id="10"/>
<link_ctn id="6"/>
<link_ctn id="9"/>
<link_ctn id="79"/>
<link_ctn id="78"/>
</route>
<route src="Jacquelin" dst="Tremblay">
<link_ctn id="145"/>
<link_ctn id="59"/>
<link_ctn id="56"/>
<link_ctn id="54"/>
<link_ctn id="2"/>
<link_ctn id="3"/>
</route>
<route src="Boivin" dst="Tremblay">
<link_ctn id="47"/>
<link_ctn id="44"/>
<link_ctn id="11"/>
<link_ctn id="10"/>
<link_ctn id="16"/>
<link_ctn id="0"/>
<link_ctn id="3"/>
</route>
<route src="Boivin" dst="Fafard">
<link_ctn id="47"/>
<link_ctn id="44"/>
<link_ctn id="11"/>
<link_ctn id="6"/>
<link_ctn id="9"/>
<link_ctn id="79"/>
<link_ctn id="78"/>
<link_ctn id="80"/>
</route>
</zone>
</platform>

Example of a deployment file

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

<?xml version='1.0'?>
<!DOCTYPE platform SYSTEM "http://simgrid.gforge.inria.fr/simgrid/simgrid.dtd">
<platform version="4.1">
<!-- The master actor (with some arguments) -->
<actor host="Tremblay" function="master">
<argument value="20"/> <!-- Number of tasks -->
<argument value="50000000"/> <!-- Computation size of tasks -->
<argument value="1000000"/> <!-- Communication size of tasks -->
<argument value="5"/> <!-- Number of workers -->
</actor>
<!-- The worker processes (with mailbox to listen on as argument) -->
<actor host="Tremblay" function="worker" on_failure="RESTART">
<argument value="0"/>
</actor>
<actor host="Jupiter" function="worker" on_failure="RESTART">
<argument value="1"/>
</actor>
<actor host="Fafard" function="worker" on_failure="RESTART">
<argument value="2"/>
</actor>
<actor host="Ginette" function="worker" on_failure="RESTART">
<argument value="3"/>
</actor>
<actor host="Bourassa" function="worker" on_failure="RESTART">
<argument value="4"/>
</actor>
</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");
/* Main function of the Sender process */

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[])
{
xbt_assert(argc==7, "The sender function expects 6 arguments from the XML deployment file");
long number_of_tasks = xbt_str_parse_int(argv[1], "Invalid amount of tasks: %s"); /* - number of tasks */
double task_comp_size = xbt_str_parse_double(argv[2], "Invalid computational size: %s"); /* - computational cost */
double task_comm_size = xbt_str_parse_double(argv[3], "Invalid communication size: %s"); /* - communication cost */
long receivers_count = xbt_str_parse_int(argv[4], "Invalid amount of receivers: %s"); /* - number of receivers */
double sleep_start_time = xbt_str_parse_double(argv[5], "Invalid sleep start time: %s"); /* - start time */
double sleep_test_time = xbt_str_parse_double(argv[6], "Invalid test time: %s"); /* - test time */
XBT_INFO("sleep_start_time : %f , sleep_test_time : %f", sleep_start_time, sleep_test_time);
MSG_process_sleep(sleep_start_time);
for (int i = 0; i < number_of_tasks; i++) {
char mailbox[80];
char taskname[80];
snprintf(mailbox,79, "receiver-%ld", i % receivers_count);
snprintf(taskname,79, "Task_%d", i);
/* This process first creates a task and send it asynchronously with @ref MSG_task_isend. Then, if: */
msg_task_t task = MSG_task_create(taskname, task_comp_size, task_comm_size, NULL);
msg_comm_t comm = MSG_task_isend(task, mailbox);
XBT_INFO("Send to receiver-%ld Task_%d", i % receivers_count, i);
if (sleep_test_time > 0) { /* - "test_time" is set to 0, wait on @ref MSG_comm_wait */
while (MSG_comm_test(comm) == 0) { /* - Call @ref MSG_comm_test every "test_time" otherwise */
MSG_process_sleep(sleep_test_time);
}
} else {
MSG_comm_wait(comm, -1);
}
}
for (int i = 0; i < receivers_count; i++) {
char mailbox[80];
snprintf(mailbox, 79, "receiver-%d", i);
msg_task_t task = MSG_task_create("finalize", 0, 0, 0);
msg_comm_t comm = MSG_task_isend(task, mailbox);
XBT_INFO("Send to receiver-%d finalize", i);
if (sleep_test_time > 0) {
while (MSG_comm_test(comm) == 0) {
MSG_process_sleep(sleep_test_time);
}
} else {
MSG_comm_wait(comm, -1);
}
}
XBT_INFO("Goodbye now!");
return 0;
}
/* Receiver process expects 3 arguments: */

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[])
{
xbt_assert(argc==4, "The relay_runner function does not accept any parameter from the XML deployment file");
int id = xbt_str_parse_int(argv[1], "Invalid id: %s"); /* - unique id */
double sleep_start_time = xbt_str_parse_double(argv[2], "Invalid sleep start parameter: %s"); /* - start time */
double sleep_test_time = xbt_str_parse_double(argv[3], "Invalid sleep test parameter: %s"); /* - test time */
XBT_INFO("sleep_start_time : %f , sleep_test_time : %f", sleep_start_time, sleep_test_time);
MSG_process_sleep(sleep_start_time); /* This process first sleeps for "start time" seconds. */
char mailbox[80];
snprintf(mailbox,79, "receiver-%d", id);
while (1) {
msg_task_t task = NULL;
msg_comm_t comm = MSG_task_irecv(&task, mailbox); /* Then it posts asynchronous receives (@ref MSG_task_irecv) and*/
XBT_INFO("Wait to receive a task");
if (sleep_test_time > 0) { /* - if "test_time" is set to 0, wait on @ref MSG_comm_wait */
while (MSG_comm_test(comm) == 0) { /* - Call @ref MSG_comm_test every "test_time" otherwise */
MSG_process_sleep(sleep_test_time);
}
} else {
msg_error_t res = MSG_comm_wait(comm, -1);
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") == 0) { /* If the received task is "finalize", the process ends */
break;
}
XBT_INFO("Processing \"%s\"", MSG_task_get_name(task)); /* Otherwise, the task is processed */
XBT_INFO("\"%s\" done", MSG_task_get_name(task));
}
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]);
MSG_create_environment(argv[1]);/* - Load the platform description */
MSG_function_register("sender", sender);
MSG_function_register("receiver", receiver);
MSG_launch_application(argv[2]);/* - Deploy the sender and receiver processes */
msg_error_t res = MSG_main(); /* - Run the simulation */
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[])
{
xbt_assert(argc==5,"This function expects 4 parameters from the XML deployment file");
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);
for (int i = 0; i < number_of_tasks; i++) {
char mailbox[80];
char taskname[80];
snprintf(mailbox,79, "receiver-%ld", i % receivers_count);
snprintf(taskname,79, "Task_%d", i);
msg_task_t task = MSG_task_create(taskname, 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 (int i = 0; i < receivers_count; i++) {
char mailbox[80];
snprintf(mailbox,79, "receiver-%ld", i % receivers_count);
msg_task_t 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 (int 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[])
{
xbt_assert(argc==2,"This function expects 1 parameter from the XML deployment file");
int id = xbt_str_parse_int(argv[1], "Any process of this example must have a numerical name, not %s");
char mailbox[80];
snprintf(mailbox,79, "receiver-%d", id);
while (1) {
XBT_INFO("Wait to receive a task");
msg_task_t task = NULL;
msg_comm_t comm = MSG_task_irecv(&task, mailbox);
msg_error_t res = MSG_comm_wait(comm, -1);
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") == 0) {
break;
}
XBT_INFO("Processing \"%s\"", MSG_task_get_name(task));
XBT_INFO("\"%s\" done", MSG_task_get_name(task));
}
XBT_INFO("I'm done. See you!");
return 0;
}