SimGrid: Main MSG simulation Functions

SimGrid 3.10 Versatile Simulation of Distributed Systems

- Home page
- Online documentation
- Dev's Corner

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Macros | Functions
Main MSG simulation Functions
MSG

Describes how to setup and control your simulation. More...

## Macros
#define | MSG_init(argc, argv)
| Initialize the MSG internal data.

## Functions
void | MSG_launch_application (const char *file)
| An application deployer.
void | MSG_function_register (const char *name, xbt_main_func_t code)
| Registers the main function of a process in a global table.
void | MSG_function_register_default (xbt_main_func_t code)
| Registers a function as the default main function of processes.
xbt_main_func_t | MSG_get_registered_function (const char *name)
| Retrieves a registered main function.
void | MSG_create_environment (const char *file)
| A platform constructor.
void | MSG_init_nocheck (int *argc, char **argv)
| Initialize MSG with less verifications You should use the MSG_init() function instead. Failing to do so may turn into PEBKAC some day. You've been warned.
msg_error_t | MSG_main (void)
| Launch the MSG simulation.
void | MSG_config (const char *key, const char *value)
| set a configuration variable
int | MSG_process_killall (int reset_PIDs)
| Kill all running process.
double | MSG_get_clock (void)
| A clock (in second).
enum | msg_error_t { MSG_OK = 0, MSG_TIMEOUT = 1, MSG_TRANSFER_FAILURE = 2, MSG_HOST_FAILURE = 4, MSG_TASK_CANCELED = 8 }
| Return code of most MSG functions. More...

## Detailed Description

Describes how to setup and control your simulation.

The basic workflow is the following (check the MSG examples for details).

1. Initialize the library with MSG_init
2. Create a platform (usually by parsing a file with MSG_create_environment)
3. Register the functions that your processes are supposed to run with MSG_function_register (and maybe MSG_function_register_default)
4. Launch your processes from a deployment file with MSG_launch_application
5. Run the simulation with MSG_main

## Macro Definition Documentation

#define MSG_init | ( |  | argc,
|  |  | argv
| ) |  |

Initialize the MSG internal data.

It also check that the link-time and compile-time versions of SimGrid do match, so you should use this version instead of the MSG_init_nocheck function that does the same initializations, but without this check.

We allow to link against compiled versions that differ in the patch level.

## Enumeration Type Documentation

enum msg_error_t

Return code of most MSG functions.

Enumerator:

  MSG_OK | Everything is right. Keep on going this way !
  MSG_TIMEOUT | nothing good happened before the timer you provided elapsed
  MSG_TRANSFER_FAILURE | There has been a problem during you task transfer. Either the network is down or the remote host has been shutdown.
  MSG_HOST_FAILURE | System shutdown. The host on which you are running has just been rebooted. Free your datastructures and return now !
  MSG_TASK_CANCELED | Canceled task. This task has been canceled by somebody!

## Function Documentation

void MSG_launch_application | ( | const char * | file | ) |

An application deployer.

Creates the process described in file.

Parameters

  file | a filename of a xml description of the application. This file follows this DTD :
      \include simgrid.dtd

Here is a small example of such a platform

    \include msg/masterslave/deployment_masterslave.xml

Have a look in the directory examples/msg/ to have a bigger example.

void MSG_function_register | ( | const char * | name,
|  | xbt_main_func_t | code
| ) |  |

Registers the main function of a process in a global table.

Registers a code function in a global table. This table is then used by MSG_launch_application.

Parameters

  name | the reference name of the function.
  code | the function (must have the same prototype than the main function of any C program: int ..(int argc, char *argv[]))

void MSG_function_register_default | ( | xbt_main_func_t | code | ) |

Registers a function as the default main function of processes.

Registers a code function as being the default value. This function will get used by MSG_launch_application() when there is no registered function of the requested name in.

Parameters

  code | the function (must have the same prototype than the main function of any C program: int ..(int argc, char *argv[]))

xbt_main_func_t MSG_get_registered_function | ( | const char * | name | ) |

Retrieves a registered main function.

Registers a code function in a global table. This table is then used by MSG_launch_application.

Parameters

  name | the reference name of the function.

void MSG_create_environment | ( | const char * | file | ) |

A platform constructor.

Creates a new platform, including hosts, links and the routing_table.

Parameters

  file | a filename of a xml description of a platform. This file follows this DTD :
      \include simgrid.dtd

Here is a small example of such a platform

    \include small_platform.xml

Have a look in the directory examples/msg/ to have a big example.

void MSG_config | ( | const char * | key,
|  | const char * | value
| ) |  |

set a configuration variable

Do –help on any simgrid binary to see the list of currently existing configuration variables, and see Section Simgrid options and configurations.

Example: MSG_config("workstation/model","ptask_L07");

int MSG_process_killall | ( | int | reset_PIDs | ) |

Kill all running process.

Parameters

  reset_PIDs | should we reset the PID numbers. A negative number means no reset and a positive number will be used to set the PID of the next newly created process.