The MSG Interface (legacy interface)



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.

This page describes the C version of this API while the Java bindings of MSG are described in another section.

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 2020 at least.

Main MSG Functions

The basic workflow is the following:

enum msg_error_t

Return code of most MSG functions.

Values:

MSG_OK = 0

Everything is right. Keep on going this way !

MSG_TIMEOUT = 1

nothing good happened before the timer you provided elapsed

MSG_TRANSFER_FAILURE = 2

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

MSG_HOST_FAILURE = 4

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

MSG_TASK_CANCELED = 8

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 options.

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, xbt_main_func_t code)

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(xbt_main_func_t code)

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

void MSG_launch_application(const char *file)

Creates the application described in the provided file.

msg_error_t MSG_main()

Launch the MSG simulation.

void MSG_set_function(const char *host_id, const char *function_name, xbt_dynar_t arguments)

register functions bypassing the parser

Process Management Functions

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

typedef sg_actor_t msg_process_t
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, xbt_main_func_t code, 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, xbt_main_func_t code, void *data, msg_host_t host, int argc, char **argv)

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.

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. It should then only use functions described in M_process_management (to create a new #msg_process_t for example), in m_host_management (only the read-only functions i.e. whose name contains the word get), in m_task_management (to create or destroy some #msg_task_t for example) and in msg_task_usage (to handle file transfers and task processing).
  • 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, xbt_main_func_t code, 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
Return
The new corresponding object.
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. It should then only use functions described in M_process_management (to create a new #msg_process_t for example), in m_host_management (only the read-only functions i.e. whose name contains the word get), in m_task_management (to create or destroy some #msg_task_t for example) and in msg_task_usage (to handle file transfers and task processing).
  • 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

msg_process_t MSG_process_create_from_stdfunc(std::string name, std::function<void()> codevoid *data, msg_host_t host, std::unordered_map<std::string, std::string> *properties, )
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()

Detach a process attached with MSG_process_attach()

This is called when the current process has finished its job. Used in the main thread, it waits for the simulation to finish before returning. When it returns, the other simulated processes and the maestro are destroyed.

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 #msg_process_t from its PID.

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

Return
NULL if no host is found

void *MSG_process_get_data(msg_process_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(msg_process_t process)
const char *MSG_process_get_name(msg_process_t process)
int MSG_process_get_number()

Return the current number MSG processes.

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

Wait for the completion of a #msg_process_t.

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)

Imediately changes the host on which this process runs.

void MSG_process_on_exit(int_f_pvoid_pvoid_t fun, void *data)

Add a function to the list of “on_exit” functions for the current process. The on_exit functions are the functions executed when your process is killed. You should use them to free the data used by your process.

void MSG_process_ref(msg_process_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.

int MSG_process_self_PID()

Return the PID of the current process.

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

int 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)

Sleep for the specified number of seconds.

Makes the current process sleep until time seconds have elapsed.

Parameters
  • nb_sec: a number of second

void MSG_process_suspend(msg_process_t process)
void MSG_process_unref(msg_process_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 Functions

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.

xbt_dynar_t MSG_host_get_attached_storage_lists(sg_host_t host)
int MSG_host_get_core_number(sg_host_t host)
void *MSG_host_get_data(sg_host_t host)

Returns the user data of this host.

xbt_dict_t MSG_host_get_mounted_storage_list(sg_host_t host)
const char *MSG_host_get_name(sg_host_t host)

Returns the name of this host.

int MSG_host_get_nb_pstates(sg_host_t host)
double MSG_host_get_power_peak_at(sg_host_t host, int pstate_index)
void MSG_host_get_process_list(sg_host_t host, xbt_dynar_t whereto)
xbt_dict_t MSG_host_get_properties(sg_host_t host)
const char *MSG_host_get_property_value(sg_host_t host, const char *name)
int MSG_host_get_pstate(sg_host_t host)
double MSG_host_get_speed(sg_host_t host)
int MSG_host_is_off(sg_host_t h)
int MSG_host_is_on(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() and #MSG_host_is_off() to test the current state of the host and SURF_plugin_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() and #MSG_host_is_off() to test the current state of the host and SURF_plugin_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 Functions

Task structure of MSG msg_task_t and associated functions.

typedef struct 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.

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 #msg_task_t (a parallel one….).

A constructor for #msg_task_t taking six arguments and returning the corresponding object.

See
msg_task_t
Return
The new corresponding object.
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.

Return
#MSG_OK if the task was successfully completed, #MSG_TASK_CANCELED or #MSG_HOST_FAILURE otherwise
Parameters
  • task: a #msg_task_t to execute on the location on which the process is running.

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 a #msg_task_t.

Parameters
  • task: the task to cancel. If it was executed or transfered, it stops the process that were working on it.

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

Creates a new #msg_task_t.

A constructor for #msg_task_t taking four arguments and returning the corresponding object.

See
msg_task_t
Return
The new corresponding object.
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 transfered 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.

msg_error_t MSG_task_destroy(msg_task_t task)

Destroy a #msg_task_t.

Destructor for #msg_task_t. Note that you should free user data, if any, before calling this function.

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.

Return
#MSG_OK if the task was successfully completed, #MSG_TASK_CANCELED or #MSG_HOST_FAILURE otherwise
Parameters
  • task: a #msg_task_t to execute on the location on which the process is running.

double MSG_task_get_bytes_amount(msg_task_t task)

Returns the size of the data attached to a task #msg_task_t.

const char *MSG_task_get_category(msg_task_t task)

Gets the current tracing category of a task.

See
MSG_task_set_category
Return
Returns the name of the tracing category of the given task, nullptr otherwise
Parameters
  • task: the task to be considered

void *MSG_task_get_data(msg_task_t task)

Return the user data of a #msg_task_t.

This function checks whether task is a valid pointer and return the user data associated to task if possible.

double MSG_task_get_flops_amount(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(msg_task_t task)

Return the name of a #msg_task_t.

This functions returns the name of a #msg_task_t as specified on creation

double MSG_task_get_remaining_communication(msg_task_t task)

Returns the total amount received by a task #msg_task_t. 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(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(msg_task_t task)

Return the sender of a #msg_task_t.

This functions returns the #msg_process_t which sent this task

msg_host_t MSG_task_get_source(msg_task_t task)

Return the source of a #msg_task_t.

This functions returns the #msg_host_t from which this task was sent

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.

Return
the msg_comm_t communication created
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

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).

Return
the msg_comm_t communication created
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)

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.

Return
the msg_comm_t communication created
Parameters
  • task: a #msg_task_t to send on another location.
  • alias: name of the mailbox to sent the task to

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.

Return
the msg_comm_t communication created
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).

int MSG_task_listen(const char *alias)

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

Return
Returns 1 if there is a communication, 0 otherwise
Parameters
  • alias: the name of the mailbox to be considered

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.

Return
Returns the PID of sender process, -1 if there is no communication in the mailbox.
Parameters
  • alias: the name of the mailbox to be considered

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.

Return
Returns #MSG_OK if the task was successfully received, #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE otherwise.
Parameters
  • task: a memory location for storing a #msg_task_t.
  • alias: name of the mailbox to receive the task from

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)

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

msg_error_t MSG_task_receive_ext(msg_task_t *task, const char *alias, double timeout, msg_host_t host)

Receives a task from a mailbox from a specific host 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.

Return
Returns #MSG_OK if the task was successfully received, #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE, or #MSG_TIMEOUT otherwise.
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 (provide -1 for no timeout)
  • host: a #msg_host_t host from where the task was sent

msg_error_t MSG_task_receive_ext_bounded(msg_task_t *task, const char *alias, double timeout, msg_host_t host, double rate)

Receives a task from a mailbox from a specific host with a given timeout and 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_ext() 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 (provide -1 for no timeout)
  • host: a #msg_host_t host from where the task was sent
  • rate: limit the reception to rate bandwidth (byte/sec)

Return
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(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.

Return
Returns #MSG_OK if the task was successfully received, #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE, or #MSG_TIMEOUT otherwise.
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)

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)

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

Warning

doxygenfunction: Cannot find function “MSG_task_recv” in doxygen xml output for project “simgrid” from directory: ../build/xml

Warning

doxygenfunction: Cannot find function “MSG_task_recv_bounded” in doxygen xml output for project “simgrid” from directory: ../build/xml

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.

Return
Returns #MSG_OK if the task was successfully sent, #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE otherwise.
Parameters
  • task: the task to be sent
  • alias: the mailbox name to where the task is sent

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).

Return
Returns #MSG_OK if the task was successfully sent, #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE otherwise.
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)

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.

Return
Returns #MSG_OK if the task was successfully sent, #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE, or #MSG_TIMEOUT otherwise.
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)

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).

Return
Returns #MSG_OK if the task was successfully sent, #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE, or #MSG_TIMEOUT otherwise.
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)

void MSG_task_set_bound(msg_task_t task, double bound)

Changes the maximum CPU utilization of a computation task. Unit is 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 a task #msg_task_t.

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 outcomes_vizu 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_copy_callback(void (*callback)(msg_task_t task, msg_process_t src, msg_process_t dst))
void MSG_task_set_data(msg_task_t task, void *data)

Sets the user data of a #msg_task_t.

This function allows to associate a new pointer to the user data associated of task.

void MSG_task_set_flops_amount(msg_task_t task, double flops_amount)

set the computation amount needed to process a task #msg_task_t.

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 a #msg_task_t.

This functions allows to associate a name to a 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 the other ones.

Mailbox Management Functions

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.

void MSG_comm_destroy(msg_comm_t comm)

Destroys the provided communication.

msg_error_t MSG_comm_get_status(msg_comm_t comm)

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

Return
the status of the communication, or #MSG_OK if no error occurred during the communication
Parameters
  • comm: a finished communication

msg_task_t MSG_comm_get_task(msg_comm_t comm)

Get a task (#msg_task_t) from a communication.

Return
the task from the communication
Parameters
  • comm: the communication where to get the task

int MSG_comm_test(msg_comm_t comm)

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

Return
’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.
Parameters
  • comm: the communication to test

int MSG_comm_testany(xbt_dynar_t comms)

This function checks if a communication is finished.

Return
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
Parameters
  • comms: a vector of communications

msg_error_t MSG_comm_wait(msg_comm_t comm, double timeout)

Wait for the completion of a communication.

It takes two parameters.

Return
msg_error_t
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.

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

This function is called by a sender and permit to wait 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(xbt_dynar_t comms)

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

Return
the position of the first finished communication (but it may have failed, use MSG_comm_get_status() to know its status)
Parameters
  • comms: a vector of communications

Explicit Synchronization Functions

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(msg_bar_t bar)

Destroys barrier.

msg_bar_t MSG_barrier_init(unsigned int count)

Initializes a barier, with count elements.

int MSG_barrier_wait(msg_bar_t bar)

Performs a barrier already initialized.

Semaphores

typedef struct s_smx_sem_t *msg_sem_t

Opaque type representing a semaphore.

void MSG_sem_acquire(msg_sem_t sem)

locks on a semaphore object

msg_error_t MSG_sem_acquire_timeout(msg_sem_t sem, double timeout)

locks on a semaphore object up until the provided timeout expires

void MSG_sem_destroy(msg_sem_t sem)
int MSG_sem_get_capacity(msg_sem_t sem)
msg_sem_t MSG_sem_init(int initial_value)

creates a semaphore object of the given initial capacity

void MSG_sem_release(msg_sem_t sem)

releases the semaphore object

int MSG_sem_would_block(msg_sem_t sem)

returns a boolean indicating if this semaphore would block at this very specific time

Note that the returned value may be wrong right after the function call, when you try to use it… But that’s a classical semaphore issue, and SimGrid’s semaphore are not different to usual ones here.

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
sg_vm_t MSG_vm_create(sg_host_t ind_pm, const char *name, int coreAmount, int ramsize, int mig_netspeed, int dp_intensity)
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(msg_vm_t vm)
msg_host_t MSG_vm_get_pm(msg_vm_t vm)
size_t MSG_vm_get_ramsize(msg_vm_t vm)
int MSG_vm_is_created(msg_vm_t vm)
int MSG_vm_is_running(msg_vm_t vm)
int MSG_vm_is_suspended(msg_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)

Storage Management Functions

Storage structure of MSG (msg_storage_t) and associated functions, inspired from POSIX.

typedef sg_storage_t msg_storage_t
msg_storage_t MSG_storage_get_by_name(const char *name)
void *MSG_storage_get_data(msg_storage_t storage)
const char *MSG_storage_get_host(msg_storage_t storage)
const char *MSG_storage_get_name(msg_storage_t storage)
xbt_dict_t MSG_storage_get_properties(msg_storage_t storage)
const char *MSG_storage_get_property_value(msg_storage_t storage, const char *name)
sg_size_t MSG_storage_read(msg_storage_t storage, sg_size_t size)
xbt_dynar_t MSG_storages_as_dynar()
void MSG_storage_set_data(msg_storage_t storage, void *data)
void MSG_storage_set_property_value(msg_storage_t storage, const char *name, const char *value)
sg_size_t MSG_storage_write(msg_storage_t storage, sg_size_t size)

Zone Management Functions

Network Zone (msg_file_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(msg_netzone_t zone, xbt_dynar_t whereto)
const char *MSG_zone_get_name(msg_netzone_t zone)
const char *MSG_zone_get_property_value(msg_netzone_t zone, const char *name)
msg_netzone_t MSG_zone_get_root()
void MSG_zone_get_sons(msg_netzone_t zone, xbt_dict_t whereto)
void MSG_zone_set_property_value(msg_netzone_t zone, const char *name, char *value)