SimGrid  3.16
Versatile Simulation of Distributed Systems
Main MSG simulation Functions

Detailed Description

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

Macros

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

Functions

void MSG_launch_application (const char *file)
 An application deployer. More...
 
void MSG_function_register (const char *name, xbt_main_func_t code)
 Registers the main function of a process in a global table. More...
 
void MSG_function_register_default (xbt_main_func_t code)
 Registers a function as the default main function of processes. More...
 
void MSG_create_environment (const char *file)
 A platform constructor. More...
 
void MSG_init_nocheck (int *argc, char **argv)
 Initialize MSG with less verifications You should use the MSG_init() function instead. More...
 
msg_error_t MSG_main ()
 Launch the MSG simulation. More...
 
void MSG_config (const char *key, const char *value)
 set a configuration variable More...
 
int MSG_process_killall (int reset_PIDs)
 Kill all running process. More...
 
double MSG_get_clock ()
 A clock (in second). More...
 
enum  msg_error_t {
  MSG_OK = 0, MSG_TIMEOUT = 1, MSG_TRANSFER_FAILURE = 2, MSG_HOST_FAILURE = 4,
  MSG_TASK_CANCELED = 8, 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...
 
enum  msg_error_t {
  MSG_OK = 0, MSG_TIMEOUT = 1, MSG_TRANSFER_FAILURE = 2, MSG_HOST_FAILURE = 4,
  MSG_TASK_CANCELED = 8, 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...
 

Macro Definition Documentation

◆ MSG_init [1/2]

#define MSG_init (   argc,
  argv 
)
Value:
do { \
MSG_init_nocheck(argc,argv); \
} while (0)
#define SIMGRID_VERSION_MAJOR
Define the version numbers of the used header files.
Definition: simgrid_config.h:14
#define SIMGRID_VERSION_MINOR
Definition: simgrid_config.h:15
#define SIMGRID_VERSION_PATCH
Definition: simgrid_config.h:16
static char ** argv
Definition: surfxml_sax_cb.cpp:1018
static int argc
Definition: surfxml_sax_cb.cpp:1017

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.

Examples:
examples/msg/actions-comm/actions-comm.c, examples/msg/actions-storage/actions-storage.c, examples/msg/app-masterworker/app-masterworker.c, examples/msg/app-pingpong/app-pingpong.c, examples/msg/app-token-ring/app-token-ring.c, examples/msg/async-wait/async-wait.c, examples/msg/async-waitall/async-waitall.c, examples/msg/async-waitany/async-waitany.c, examples/msg/dht-chord/dht-chord.c, examples/msg/io-file/io-file.c, examples/msg/io-remote/io-remote.c, examples/msg/io-storage/io-storage.c, examples/msg/network-ns3/network-ns3.c, examples/msg/platform-properties/platform-properties.c, examples/msg/process-create/process-create.c, examples/msg/process-kill/process-kill.c, examples/msg/process-migration/process-migration.c, examples/msg/process-startkilltime/process-startkilltime.c, examples/msg/process-suspend/process-suspend.c, examples/msg/task-priority/task-priority.c, examples/msg/trace-categories/trace-categories.c, examples/msg/trace-host-user-variables/trace-host-user-variables.c, examples/msg/trace-link-user-variables/trace-link-user-variables.c, examples/msg/trace-masterworker/trace-masterworker.c, examples/msg/trace-platform/trace-platform.c, examples/msg/trace-process-migration/trace-process-migration.c, and examples/msg/trace-route-user-variables/trace-route-user-variables.c.

◆ MSG_init [2/2]

#define MSG_init (   argc,
  argv 
)
Value:
do { \
MSG_init_nocheck(argc,argv); \
} while (0)
#define SIMGRID_VERSION_MAJOR
Define the version numbers of the used header files.
Definition: simgrid_config.h:14
#define SIMGRID_VERSION_MINOR
Definition: simgrid_config.h:15
#define SIMGRID_VERSION_PATCH
Definition: simgrid_config.h:16
static char ** argv
Definition: surfxml_sax_cb.cpp:1018
static int argc
Definition: surfxml_sax_cb.cpp:1017

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

◆ msg_error_t [1/2]

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!

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!

◆ msg_error_t [2/2]

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!

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

◆ MSG_launch_application()

void MSG_launch_application ( const char *  file)

An application deployer.

Creates the process described in file.

Parameters
filea 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.

◆ MSG_function_register()

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
namethe reference name of the function.
codethe function (must have the same prototype than the main function of any C program: int ..(int argc, char *argv[]))

◆ MSG_function_register_default()

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
codethe function (must have the same prototype than the main function of any C program: int ..(int argc, char *argv[]))

◆ MSG_create_environment()

void MSG_create_environment ( const char *  file)

A platform constructor.

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

Parameters
filea 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.

◆ MSG_init_nocheck()

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_main()

msg_error_t MSG_main ( )

Launch the MSG simulation.

◆ MSG_config()

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 Configure SimGrid.

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

◆ MSG_process_killall()

int MSG_process_killall ( int  reset_PIDs)

Kill all running process.

Parameters
reset_PIDsshould 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.

◆ MSG_get_clock()

double MSG_get_clock ( )

A clock (in second).