The MSG Interface (legacy interface)

Warning

MSG used to be the main API of SimGrid 3, but we are currently in the process of releasing SimGrid 4. So MSG is frozen and will probably never evolve. If you are starting a new project, you should consider S4U instead. Note that the support for MSG will not be removed from SimGrid before 2020Q4 or 2021Q1.

This interface is disabled by default. Pass -Denable_msg=ON to cmake if you still need it.

MSG is a simple API to write algorithms organized with Concurrent Sequential Processes (CSP) that interact by exchanging messages. It constitutes a convenient simplification of the reality of distributed systems. It can be used to build rather realistic simulations, but remains simple to use: most unpleasant technical elements can be abstracted away rather easily.

C API reference

Main MSG Functions

The basic workflow is the following:

enum msg_error_t

Return code of most MSG functions.

Values:

enumerator MSG_OK

Everything is right. Keep on going this way !

enumerator MSG_TIMEOUT

nothing good happened before the timer you provided elapsed

enumerator MSG_TRANSFER_FAILURE

There has been a problem during you task transfer. Either the network is down or the remote host has been shutdown.

enumerator MSG_HOST_FAILURE

System shutdown. The host on which you are running has just been rebooted. Free your datastructures and return now !

enumerator MSG_TASK_CANCELED

Canceled task. This task has been canceled by somebody!

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

Example: MSG_config(“host/model”,”ptask_L07”);

void MSG_create_environment(const char *file)

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

void MSG_function_register(const char *name, int (*code)(int, char**))

Registers the main function of a process 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(int (*code)(int, char**))

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[]))

double MSG_get_clock()

A clock (in second).

unsigned long int MSG_get_sent_msg()

Returns the amount of messages sent since the simulation start.

MSG_init(argc, argv)

Initialize the MSG internal data.

It also checks 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 linking against compiled versions that differ in the patch level.

void MSG_launch_application(const char *file)

Creates the application described in the provided file.

msg_error_t MSG_main()

Launch the MSG simulation.

Process Management

This describes the process structure msg_process_t and the functions for managing it.

typedef sg_actor_t msg_process_t

Processes are independent agents that can do stuff on their own. They are in charge of executing your code interacting with the simulated world. A process may be defined as a code with some private data. Processes must be located on hosts (msg_host_t), and they exchange data by sending tasks (msg_task_t) that are similar to envelops containing data.

msg_process_t MSG_process_attach(const char *name, void *data, msg_host_t host, xbt_dict_t properties)
void MSG_process_auto_restart_set(msg_process_t process, int auto_restart)

Sets the “auto-restart” flag of the process.

If the flag is set, the process will be automatically restarted when its host comes back up.

msg_process_t MSG_process_create(const char *name, int (*code)(int, char**), void *data, msg_host_t host, )

Creates and runs a new msg_process_t.

Does exactly the same as MSG_process_create_with_arguments but without providing standard arguments (argc, argv, start_time, kill_time).

msg_process_t MSG_process_create_with_arguments(const char *name, int (*code)(int, char**), void *data, msg_host_t host, int argc, char **argv, )

Creates and runs a new process.

A constructor for msg_process_t taking four arguments and returning the corresponding object. The structure (and the corresponding thread) is created, and put in the list of ready process.

Parameters
  • name – a name for the object. It is for user-level information and can be nullptr.

  • code – is a function describing the behavior of the process.

  • data – a pointer to any data one may want to attach to the new object. It is for user-level information and can be nullptr. It can be retrieved with the function MSG_process_get_data().

  • host – the location where the new process is executed.

  • argc – first argument passed to code

  • argv – second argument passed to code

msg_process_t MSG_process_create_with_environment(const char *name, int (*code)(int, char**), void *data, msg_host_t host, int argc, char **argv, xbt_dict_t properties, )

Creates and runs a new msg_process_t.

A constructor for msg_process_t taking four arguments and returning the corresponding object. The structure (and the corresponding thread) is created, and put in the list of ready process.

See

msg_process_t

Parameters
  • name – a name for the object. It is for user-level information and can be nullptr.

  • code – is a function describing the behavior of the process.

  • data – a pointer to any data one may want to attach to the new object. It is for user-level information and can be nullptr. It can be retrieved with the function MSG_process_get_data().

  • host – the location where the new process is executed.

  • argc – first argument passed to code

  • argv – second argument passed to code. WARNING, these strings are freed by the SimGrid kernel when the process exits, so they cannot be static nor shared between several processes.

  • properties – list a properties defined for this process

Returns

The new corresponding object.

void MSG_process_daemonize(msg_process_t process)

Indicates that this process should not prevent the simulation from ending.

SimGrid simulations run until all non-daemon processes are stopped.

void MSG_process_detach()
xbt_dynar_t MSG_processes_as_dynar()

returns a list of all currently existing processes

sg_actor_t MSG_process_from_PID(int pid)

Return a process from its PID (or NULL if not found).

Note that the PID are unique in the whole simulation, not only on a given host.

void *MSG_process_get_data(const_sg_actor_t process)

Returns the user data of a process.

This function checks whether process is a valid pointer and returns the user data associated to this process.

sg_host_t MSG_process_get_host(const_sg_actor_t process)
const char *MSG_process_get_name(const_sg_actor_t process)
int MSG_process_get_number()

Return the current number MSG processes.

int MSG_process_get_PID(const_sg_actor_t process)
int MSG_process_get_PPID(const_sg_actor_t process)
xbt_dict_t MSG_process_get_properties(const_sg_actor_t process)
const char *MSG_process_get_property_value(const_sg_actor_t process, const char *name)
int MSG_process_is_suspended(const_sg_actor_t process)
void MSG_process_join(const_sg_actor_t process, double timeout)

Wait for the completion of a process.

Parameters
  • process – the process to wait for

  • timeout – wait until the process is over, or the timeout occurs

void MSG_process_kill(msg_process_t process)

Kills a process.

void MSG_process_killall()

Kill all running process.

void MSG_process_migrate(msg_process_t process, msg_host_t host)

Immediately changes the host on which this process runs.

void MSG_process_on_exit(int_f_int_pvoid_t fun, void *data)
void MSG_process_ref(const_sg_actor_t process)

Take an extra reference on that process to prevent it to be garbage-collected.

void MSG_process_restart(msg_process_t process)
void MSG_process_resume(msg_process_t process)
msg_process_t MSG_process_self()

Return the current process.

This function returns the currently running msg_process_t.

const char *MSG_process_self_name()

Return the name of the current process.

aid_t MSG_process_self_PID()
aid_t MSG_process_self_PPID()

Return the PPID of the current process.

This function returns the PID of the parent of the currently running msg_process_t.

msg_error_t MSG_process_set_data(msg_process_t process, void *data)

Sets the user data of a process.

This function checks whether process is a valid pointer and sets the user data associated to this process.

void MSG_process_set_data_cleanup(void_f_pvoid_t data_cleanup)

Sets a cleanup function to be called to free the userdata of a process when a process is destroyed.

Parameters

data_cleanup – a cleanup function for the userdata of a process, or nullptr to call no function

void MSG_process_set_kill_time(msg_process_t process, double kill_time)

Specifies the time at which the process should be automatically killed.

msg_error_t MSG_process_sleep(double nb_sec)
void MSG_process_suspend(msg_process_t process)
void MSG_process_unref(const_sg_actor_t process)

Release a reference on that process so that it can get be garbage-collected.

void MSG_process_yield()

Yield the current actor; let the other actors execute first.

Host Management

typedef sg_host_t msg_host_t

Host datatype.

A location (or host) is any possible place where a process may run. Thus it is represented as a physical resource with computing capabilities, some mailboxes to enable running process to communicate with remote ones, and some private data that can be only accessed by local process.

sg_host_t MSG_host_by_name(const char *name)

Finds a msg_host_t using its name.

sg_host_t MSG_get_host_by_name(const char *name)

Finds a msg_host_t using its name.

size_t MSG_get_host_number()

Returns the amount of host found in the platform.

int MSG_host_get_core_number(const_sg_host_t host)
void *MSG_host_get_data(const_sg_host_t host)

Returns the user data of this host.

const char *MSG_host_get_name(const_sg_host_t host)

Returns the name of this host.

int MSG_host_get_nb_pstates(const_sg_host_t host)
double MSG_host_get_load(const_sg_host_t host)
double MSG_host_get_power_peak_at(const_sg_host_t host, int pstate_index)
void MSG_host_get_process_list(const_sg_host_t host, xbt_dynar_t whereto)
xbt_dict_t MSG_host_get_properties(const_sg_host_t host)
const char *MSG_host_get_property_value(const_sg_host_t host, const char *name)
int MSG_host_get_pstate(const_sg_host_t host)
double MSG_host_get_speed(const_sg_host_t host)
int MSG_host_is_on(const_sg_host_t h)
void MSG_host_off(sg_host_t h)

Stop the host if it is on.

See also MSG_host_is_on() to test the current state of the host, and Host Energy for more info on DVFS.

void MSG_host_on(sg_host_t h)

Start the host if it is off.

See also MSG_host_is_on() to test the current state of the host, and Host Energy for more info on DVFS.

xbt_dynar_t MSG_hosts_as_dynar()

Returns a dynar with all existing hosts.

The host order in the returned array is generally different from the host creation/declaration order in the XML platform (we use a hash table internally).

sg_host_t MSG_host_self()

Return the location on which the current process is executed.

void MSG_host_set_data(sg_host_t host, void *data)

Sets the user data of this host.

void MSG_host_set_property_value(sg_host_t host, const char *name, const char *value)
void MSG_host_set_pstate(sg_host_t host, int pstate)

Task Management

Task structure of MSG msg_task_t and associated functions.

typedef sg_msg_Task *msg_task_t

Task datatype.

Since most scheduling algorithms rely on a concept of task that can be either computed locally or transferred on another processor, it seems to be the right level of abstraction for our purposes. A task may then be defined by a computing amount, a message size and some private data.

typedef const sg_msg_Task *const_msg_task_t
MSG_TASK_UNINITIALIZED

Default value for an uninitialized msg_task_t.

msg_task_t MSG_parallel_task_create(const char *name, int host_nb, const msg_host_t *host_list, double *flops_amount, double *bytes_amount, void *data)

Creates a new parallel task.

A constructor for msg_task_t taking six arguments.

See simgrid::s4u::this_actor::parallel_execute() for the exact semantic of the parameters.

Parameters
  • name – a name for the object. It is for user-level information and can be nullptr.

  • host_nb – the number of hosts implied in the parallel task.

  • host_list – an array of host_nb msg_host_t.

  • flops_amount – an array of host_nb doubles. flops_amount[i] is the total number of operations that have to be performed on host_list[i].

  • bytes_amount – an array of host_nb* host_nb doubles.

  • data – a pointer to any data may want to attach to the new object. It is for user-level information and can be nullptr. It can be retrieved with the function MSG_task_get_data().

msg_error_t MSG_parallel_task_execute(msg_task_t task)

Executes a parallel task and waits for its termination.

Parameters

task – a msg_task_t to execute on the location on which the process is running.

Returns

MSG_OK if the task was successfully completed, MSG_TASK_CANCELED or MSG_HOST_FAILURE otherwise

msg_error_t MSG_parallel_task_execute_with_timeout(msg_task_t task, double timeout)
msg_error_t MSG_task_cancel(msg_task_t task)

Cancel the given task.

If it was currently executed or transferred, the working process is stopped.

msg_task_t MSG_task_create(const char *name, double flops_amount, double bytes_amount, void *data)

Creates a new task.

A constructor for msg_task_t taking four arguments.

Parameters
  • name – a name for the object. It is for user-level information and can be nullptr.

  • flop_amount – a value of the processing amount (in flop) needed to process this new task. If 0, then it cannot be executed with MSG_task_execute(). This value has to be >=0.

  • message_size – a value of the amount of data (in bytes) needed to transfer this new task. If 0, then it cannot be transferred with MSG_task_send() and MSG_task_recv(). This value has to be >=0.

  • data – a pointer to any data may want to attach to the new object. It is for user-level information and can be nullptr. It can be retrieved with the function MSG_task_get_data().

Returns

The new corresponding object.

msg_error_t MSG_task_destroy(msg_task_t task)

Destroys the given task.

You should free user data, if any, before calling this destructor.

Only the process that owns the task can destroy it. The owner changes after a successful send. If a task is successfully sent, the receiver becomes the owner and is supposed to destroy it. The sender should not use it anymore. If the task failed to be sent, the sender remains the owner of the task.

void MSG_task_dsend(msg_task_t task, const char *alias, void_f_pvoid_t cleanup)

Sends a task on a mailbox.

This is a non blocking detached send function. Think of it as a best effort send. Keep in mind that the third parameter is only called if the communication fails. If the communication does work, it is responsibility of the receiver code to free anything related to the task, as usual. More details on this can be obtained on this thread in the SimGrid-user mailing list archive.

Parameters
  • task – a msg_task_t to send on another location.

  • alias – name of the mailbox to sent the task to

  • cleanup – a function to destroy the task if the communication fails, e.g. MSG_task_destroy (if nullptr, no function will be called)

void MSG_task_dsend_bounded(msg_task_t task, const char *alias, void_f_pvoid_t cleanup, double maxrate)

Sends a task on a mailbox with a maximal rate.

This is a non blocking detached send function. Think of it as a best effort send. Keep in mind that the third parameter is only called if the communication fails. If the communication does work, it is responsibility of the receiver code to free anything related to the task, as usual. More details on this can be obtained on this thread in the SimGrid-user mailing list archive.

The rate parameter can be used to send a task with a limited bandwidth (smaller than the physical available value). Use MSG_task_dsend() if you don’t limit the rate (or pass -1 as a rate value do disable this feature).

Parameters
  • task – a msg_task_t to send on another location.

  • alias – name of the mailbox to sent the task to

  • cleanup – a function to destroy the task if the communication fails, e.g. MSG_task_destroy (if nullptr, no function will be called)

  • maxrate – the maximum communication rate for sending this task (byte/sec)

msg_error_t MSG_task_execute(msg_task_t task)

Executes a task and waits for its termination.

This function is used for describing the behavior of a process. It takes only one parameter.

Parameters

task – a msg_task_t to execute on the location on which the process is running.

Returns

MSG_OK if the task was successfully completed, MSG_TASK_CANCELED or MSG_HOST_FAILURE otherwise

double MSG_task_get_bytes_amount(const_msg_task_t task)

Returns the size of the data attached to the given task.

const char *MSG_task_get_category(const_msg_task_t task)

Gets the current tracing category of a task. (.

See

MSG_task_set_category)

Parameters

task – the task to be considered

Returns

Returns the name of the tracing category of the given task, “” otherwise

void *MSG_task_get_data(const_msg_task_t task)

Return the user data of the given task.

double MSG_task_get_flops_amount(const_msg_task_t task)

Returns the amount of flops that remain to be computed.

The returned value is initially the cost that you defined for the task, then it decreases until it reaches 0

It works for sequential tasks, but the remaining amount of work is not a scalar value for parallel tasks. So you will get an exception if you call this function on parallel tasks. Just don’t do it.

const char *MSG_task_get_name(const_msg_task_t task)

Returns the name of the given task.

double MSG_task_get_remaining_communication(const_msg_task_t task)

Returns the total amount received by the given task.

If the communication does not exist it will return 0. So, if the communication has FINISHED or FAILED it returns zero.

double MSG_task_get_remaining_work_ratio(const_msg_task_t task)

Returns a value in ]0,1[ that represent the task remaining work to do: starts at 1 and goes to 0. Returns 0 if not started or finished.

It works for either parallel or sequential tasks.

msg_process_t MSG_task_get_sender(const_msg_task_t task)

Returns the sender of the given task.

msg_host_t MSG_task_get_source(const_msg_task_t task)

Returns the source (the sender’s host) of the given task.

msg_comm_t MSG_task_irecv(msg_task_t *task, const char *alias)

Starts listening for receiving a task from an asynchronous communication.

This is a non blocking function: use MSG_comm_wait() or MSG_comm_test() to end the communication.

Parameters
  • task – a memory location for storing a msg_task_t. has to be valid until the end of the communication.

  • name – of the mailbox to receive the task on

Returns

the msg_comm_t communication created

msg_comm_t MSG_task_irecv_bounded(msg_task_t *task, const char *alias, double rate)

Starts listening for receiving a task from an asynchronous communication at a given rate.

The rate parameter can be used to receive a task with a limited bandwidth (smaller than the physical available value). Use MSG_task_irecv() if you don’t limit the rate (or pass -1 as a rate value do disable this feature).

Parameters
  • task – a memory location for storing a msg_task_t. has to be valid until the end of the communication.

  • name – of the mailbox to receive the task on

  • rate – limit the bandwidth to the given rate (byte/sec)

Returns

the msg_comm_t communication created

msg_comm_t MSG_task_isend(msg_task_t task, const char *alias)

Sends a task on a mailbox.

This is a non blocking function: use MSG_comm_wait() or MSG_comm_test() to end the communication.

Parameters
  • task – a msg_task_t to send on another location.

  • alias – name of the mailbox to sent the task to

Returns

the msg_comm_t communication created

msg_comm_t MSG_task_isend_bounded(msg_task_t task, const char *alias, double maxrate)

Sends a task on a mailbox with a maximum rate.

This is a non blocking function: use MSG_comm_wait() or MSG_comm_test() to end the communication. The maxrate parameter allows the application to limit the bandwidth utilization of network links when sending the task.

Parameters
  • task – a msg_task_t to send on another location.

  • alias – name of the mailbox to sent the task to

  • maxrate – the maximum communication rate for sending this task (byte/sec).

Returns

the msg_comm_t communication created

int MSG_task_listen(const char *alias)

Check if there is a communication going on in a mailbox.

Parameters

alias – the name of the mailbox to be considered

Returns

Returns 1 if there is a communication, 0 otherwise

int MSG_task_listen_from(const char *alias)

Look if there is a communication on a mailbox and return the PID of the sender process.

Parameters

alias – the name of the mailbox to be considered

Returns

Returns the PID of sender process (or -1 if there is no communication in the mailbox)

msg_error_t MSG_task_receive(msg_task_t *task, const char *alias)

Receives a task from a mailbox.

This is a blocking function, the execution flow will be blocked until the task is received. See MSG_task_irecv for receiving tasks asynchronously.

Parameters
  • task – a memory location for storing a msg_task_t.

  • alias – name of the mailbox to receive the task from

Returns

Returns MSG_OK if the task was successfully received, MSG_HOST_FAILURE, or MSG_TRANSFER_FAILURE otherwise.

msg_error_t MSG_task_receive_bounded(msg_task_t *task, const char *alias, double rate)

Receives a task from a mailbox at a given rate.

The rate parameter can be used to receive a task with a limited bandwidth (smaller than the physical available value). Use MSG_task_receive() if you don’t limit the rate (or pass -1 as a rate value do disable this feature).

Parameters
  • task – a memory location for storing a msg_task_t.

  • alias – name of the mailbox to receive the task from

  • rate – limit the reception to rate bandwidth (byte/sec)

Returns

Returns MSG_OK if the task was successfully received, MSG_HOST_FAILURE, or MSG_TRANSFER_FAILURE otherwise.

msg_error_t MSG_task_receive_with_timeout(msg_task_t *task, const char *alias, double timeout)

Receives a task from a mailbox with a given timeout.

This is a blocking function with a timeout, the execution flow will be blocked until the task is received or the timeout is achieved. See MSG_task_irecv for receiving tasks asynchronously. You can provide a -1 timeout to obtain an infinite timeout.

Parameters
  • task – a memory location for storing a msg_task_t.

  • alias – name of the mailbox to receive the task from

  • timeout – is the maximum wait time for completion (if -1, this call is the same as MSG_task_receive)

Returns

Returns MSG_OK if the task was successfully received, MSG_HOST_FAILURE, or MSG_TRANSFER_FAILURE, or MSG_TIMEOUT otherwise.

msg_error_t MSG_task_receive_with_timeout_bounded(msg_task_t *task, const char *alias, double timeout, double rate)

Receives a task from a mailbox with a given timeout and at a given rate.

The rate parameter can be used to send a task with a limited bandwidth (smaller than the physical available value). Use MSG_task_receive() if you don’t limit the rate (or pass -1 as a rate value do disable this feature).

Parameters
  • task – a memory location for storing a msg_task_t.

  • alias – name of the mailbox to receive the task from

  • timeout – is the maximum wait time for completion (if -1, this call is the same as MSG_task_receive)

  • rate – limit the reception to rate bandwidth (byte/sec)

Returns

Returns MSG_OK if the task was successfully received, MSG_HOST_FAILURE, or MSG_TRANSFER_FAILURE, or MSG_TIMEOUT otherwise.

MSG_task_recv(t, a)
MSG_task_recv_bounded(t, a, r)
msg_error_t MSG_task_send(msg_task_t task, const char *alias)

Sends a task to a mailbox.

This is a blocking function, the execution flow will be blocked until the task is sent (and received on the other side if MSG_task_receive is used). See MSG_task_isend for sending tasks asynchronously.

Parameters
  • task – the task to be sent

  • alias – the mailbox name to where the task is sent

Returns

Returns MSG_OK if the task was successfully sent, MSG_HOST_FAILURE, or MSG_TRANSFER_FAILURE otherwise.

msg_error_t MSG_task_send_bounded(msg_task_t task, const char *alias, double rate)

Sends a task to a mailbox with a maximum rate.

This is a blocking function, the execution flow will be blocked until the task is sent. The maxrate parameter allows the application to limit the bandwidth utilization of network links when sending the task.

The maxrate parameter can be used to send a task with a limited bandwidth (smaller than the physical available value). Use MSG_task_send() if you don’t limit the rate (or pass -1 as a rate value do disable this feature).

Parameters
  • task – the task to be sent

  • alias – the mailbox name to where the task is sent

  • maxrate – the maximum communication rate for sending this task (byte/sec)

Returns

Returns MSG_OK if the task was successfully sent, MSG_HOST_FAILURE, or MSG_TRANSFER_FAILURE otherwise.

msg_error_t MSG_task_send_with_timeout(msg_task_t task, const char *alias, double timeout)

Sends a task to a mailbox with a timeout.

This is a blocking function, the execution flow will be blocked until the task is sent or the timeout is achieved.

Parameters
  • task – the task to be sent

  • alias – the mailbox name to where the task is sent

  • timeout – is the maximum wait time for completion (if -1, this call is the same as MSG_task_send)

Returns

Returns MSG_OK if the task was successfully sent, MSG_HOST_FAILURE, or MSG_TRANSFER_FAILURE, or MSG_TIMEOUT otherwise.

msg_error_t MSG_task_send_with_timeout_bounded(msg_task_t task, const char *alias, double timeout, double maxrate)

Sends a task to a mailbox with a timeout and with a maximum rate.

This is a blocking function, the execution flow will be blocked until the task is sent or the timeout is achieved.

The maxrate parameter can be used to send a task with a limited bandwidth (smaller than the physical available value). Use MSG_task_send_with_timeout() if you don’t limit the rate (or pass -1 as a rate value do disable this feature).

Parameters
  • task – the task to be sent

  • alias – the mailbox name to where the task is sent

  • timeout – is the maximum wait time for completion (if -1, this call is the same as MSG_task_send)

  • maxrate – the maximum communication rate for sending this task (byte/sec)

Returns

Returns MSG_OK if the task was successfully sent, MSG_HOST_FAILURE, or MSG_TRANSFER_FAILURE, or MSG_TIMEOUT otherwise.

void MSG_task_set_bound(msg_task_t task, double bound)

Changes the maximum CPU utilization of a computation task (in flops/s).

For VMs, there is a pitfall. Please see MSG_vm_set_bound().

void MSG_task_set_bytes_amount(msg_task_t task, double bytes_amount)

set the amount data attached with the given task.

Warning

If the transfer is ongoing (already started and not finished), it is not modified by this call.

void MSG_task_set_category(msg_task_t task, const char *category)

Sets the tracing category of a task.

This function should be called after the creation of a MSG task, to define the category of that task. The first parameter task must contain a task that was =created with the function MSG_task_create(). The second parameter category must contain a category that was previously declared with the function TRACE_category (or with TRACE_category_with_color).

See Graphical and statistical logging for details on how to trace the (categorized) resource utilization.

See

MSG_task_get_category, TRACE_category, TRACE_category_with_color

Parameters
  • task – the task that is going to be categorized

  • category – the name of the category to be associated to the task

void MSG_task_set_data(msg_task_t task, void *data)

Sets the user data of a given task.

void MSG_task_set_flops_amount(msg_task_t task, double flops_amount)

set the computation amount needed to process the given task.

Warning

If the computation is ongoing (already started and not finished), it is not modified by this call. Moreover, after its completion, the ongoing execution with set the flops_amount to zero, overriding any value set during the execution.

void MSG_task_set_name(msg_task_t task, const char *name)

Sets the name of the given task.

void MSG_task_set_priority(msg_task_t task, double priority)

Changes the priority of a computation task.

This priority doesn’t affect the transfer rate. A priority of 2 will make a task receive two times more cpu power than regular tasks.

Mailbox Management

void MSG_mailbox_set_async(const char *alias)

Communications

typedef sg_msg_Comm *msg_comm_t

Object representing an ongoing communication between processes.

Such beast is usually obtained by using MSG_task_isend(), MSG_task_irecv() or friends.

typedef const sg_msg_Comm *const_msg_comm_t
void MSG_comm_destroy(const_msg_comm_t comm)

Destroys the provided communication.

msg_error_t MSG_comm_get_status(const_msg_comm_t comm)

Returns the error (if any) that occurred during a finished communication.

Parameters

comm – a finished communication

Returns

the status of the communication, or MSG_OK if no error occurred during the communication

msg_task_t MSG_comm_get_task(const_msg_comm_t comm)

Get a task (msg_task_t) from a communication.

Parameters

comm – the communication where to get the task

Returns

the task from the communication

int MSG_comm_test(msg_comm_t comm)

Checks whether a communication is done, and if yes, finalizes it.

Parameters

comm – the communication to test

Returns

‘true’ if the communication is finished (but it may have failed, use MSG_comm_get_status() to know its status) or ‘false’ if the communication is not finished yet If the status is ‘false’, don’t forget to use MSG_process_sleep() after the test.

int MSG_comm_testany(const_xbt_dynar_t comms)

This function checks if a communication is finished.

Parameters

comms – a vector of communications

Returns

the position of the finished communication if any (but it may have failed, use MSG_comm_get_status() to know its status), or -1 if none is finished

msg_error_t MSG_comm_wait(msg_comm_t comm, double timeout)

Wait for the completion of a communication.

It takes two parameters.

Parameters
  • comm – the communication to wait.

  • timeout – Wait until the communication terminates or the timeout occurs. You can provide a -1 timeout to obtain an infinite timeout.

Returns

msg_error_t

void MSG_comm_waitall(msg_comm_t *comm, int nb_elem, double timeout)

This function is called by a sender and permits waiting for each communication.

Parameters
  • comm – a vector of communication

  • nb_elem – is the size of the comm vector

  • timeout – for each call of MSG_comm_wait

int MSG_comm_waitany(const_xbt_dynar_t comms)

This function waits for the first communication finished in a list.

Parameters

comms – a vector of communications

Returns

the position of the first finished communication (but it may have failed, use MSG_comm_get_status() to know its status)

Explicit Synchronization

Explicit synchronization mechanisms: semaphores (msg_sem_t) and friends.

In some situations, these things are very helpful to synchronize processes without message exchanges.

Barriers

typedef sg_bar_t msg_bar_t

Opaque type representing a barrier identifier.

void MSG_barrier_destroy(const_sg_bar_t bar)

Destroys barrier.

msg_bar_t MSG_barrier_init(unsigned int count)

Initializes a barrier, with count elements.

int MSG_barrier_wait(msg_bar_t bar)

Performs a barrier already initialized.

Semaphores

typedef sg_sem_t msg_sem_t

Opaque type representing a semaphore.

void MSG_sem_acquire(msg_sem_t sem)
int MSG_sem_acquire_timeout(msg_sem_t sem, double timeout)
void MSG_sem_destroy(const_sg_sem_t sem)
int MSG_sem_get_capacity(const_sg_sem_t sem)
msg_sem_t MSG_sem_init(int initial_value)
void MSG_sem_release(msg_sem_t sem)
int MSG_sem_would_block(const_sg_sem_t sem)

Virtual Machines

This interface mimics IaaS clouds. With it, you can create virtual machines to put your processes into, and interact directly with the VMs to manage groups of processes.

typedef sg_vm_t msg_vm_t
msg_vm_t MSG_vm_create_core(msg_host_t pm, const char *name)
msg_vm_t MSG_vm_create_multicore(msg_host_t pm, const char *name, int coreAmount)
void MSG_vm_destroy(msg_vm_t vm)
const char *MSG_vm_get_name(const_sg_vm_t vm)
msg_host_t MSG_vm_get_pm(const_sg_vm_t vm)
size_t MSG_vm_get_ramsize(const_sg_vm_t vm)
int MSG_vm_is_created(const_sg_vm_t vm)
int MSG_vm_is_running(const_sg_vm_t vm)
int MSG_vm_is_suspended(const_sg_vm_t vm)
void MSG_vm_resume(msg_vm_t vm)
void MSG_vm_set_bound(msg_vm_t vm, double bound)
void MSG_vm_set_ramsize(msg_vm_t vm, size_t size)
void MSG_vm_shutdown(msg_vm_t vm)
void MSG_vm_start(msg_vm_t vm)
void MSG_vm_suspend(msg_vm_t vm)

NetZone Management

Network Zone (msg_netzone_t) and associated functions.

typedef sg_netzone_t msg_netzone_t
msg_netzone_t MSG_zone_get_by_name(const char *name)
void MSG_zone_get_hosts(const_sg_netzone_t zone, xbt_dynar_t whereto)
const char *MSG_zone_get_name(const_sg_netzone_t zone)
const char *MSG_zone_get_property_value(const_sg_netzone_t zone, const char *name)
msg_netzone_t MSG_zone_get_root()
void MSG_zone_get_sons(const_sg_netzone_t zone, xbt_dict_t whereto)
void MSG_zone_set_property_value(msg_netzone_t zone, const char *name, const char *value)

Java bindings

This section describes jMSG, the Java API to Simgrid. This API mimics MSG, which is a simple yet somehow realistic interface. The full reference documentation is provided at the end of this page.

Most of the documentation of the MSG API in C applies directly to the Java bindings (any divergence is seen as a bug that we should fix). MSG structures are mapped to Java objects as expected, and the MSG functions are methods in these objects.

Installing the Java bindings

The easiest is to use a precompiled jarfile, but some people may prefer to compile it from the sources.

Using the Java bindings

In most cases, you can use the SimGrid bindings as if it was a Java library:

$ javac -classpath .:path/to/simgrid.jar your/java/Code.java
$ java -classpath .:path/to/simgrid.jar your.java.Code the/parameter/to/your/code

For example:

$ cd examples/deprecated/java
$ java -classpath ../../simgrid.jar:. .:../../simgrid.jar app.pingpong.Main ../platforms/platform.xml

Any SimGrid simulation (java or not) is usually constituted of several kind of actors or processes (classes extending @c Msg.Process) that are deployed over the hosts of the virtual platform. So, your code should declare these actors, plus a Main class in charge of deploying your actors on the platform. Please refer to the examples for details.

Troubleshooting

Actually, these bindings are not only implemented in Java. They do use the C implementation of SimGrid. This should be transparent as this library is directly included in the simgrid.jar file but things can still go wrong is several ways.

Error: library simgrid not found

This means that the JVM fails to load the native library. If you use a precompiled jarfile, please report this bug.

If you built it yourself, you can try to use an installed version of the library instead of the one included in the jar. For that, add the path to the native library into the LD_LIBRARY_PATH variable (or in the DYLD_LIBRARY_PATH on macOS).

pthread_create failed

You reached the amount of threads that can be run on your system. Try increasing the thread limits of your operating system.

Other errors

When using jMSG, your program can crash for 3 main reasons:

  • Your Java part is not good: you’ll have a good old java exception thrown, and hence you should be able to correct it by yourself.

  • Our java part is not good: you’ll also have a java exception thrown, but we have real doubts this can happen, since the java part is only a JNI binding. The other option is that it crashed because you used incorrectly the MSG API, so this means also you should have an MSGException. It means you should read carefully MSG samples and/or documentation.

  • Something has crashed in the C part. Okay, here comes the tricky thing. It happens mainly for 2 reasons:

    • When something goes wrong in your simulation, sometimes the C part stops because you used SimGrid incorrectly, and JNI bindings are not fond of that. It means that you’ll have something that looks ugly, but you should be able to identify what’s going wrong in your code by carefully reading the whole error message

    • It may happen that the problem comes directly from SimGrid: in this case, the error should be uglier. In that case, you may submit a bug directly to SimGrid.