SimGrid  3.7
Scalable simulation of distributed systems
Typedefs | Functions
Task Actions
MSG

This section describes the functions that can be used by a process to execute, communicate or otherwise handle some task. More...

Typedefs

typedef struct s_smx_rvpoint * msg_mailbox_t
 Mailbox datatypeObject representing a communication rendez-vous point, on which the sender finds the receiver it wants to communicate with. As a MSG user, you will only rarely manipulate any of these objects directly, since most of the public interface (such as MSG_task_send and friends) hide this object behind a string alias. That mean that you don't provide the mailbox on which you want to send your task, but only the name of this mailbox.
typedef struct msg_comm * msg_comm_t
 Communication action.Object representing an ongoing communication between processes. Such beast is usually obtained by using MSG_task_isend, MSG_task_irecv or friends.

Functions

MSG_error_t MSG_task_execute (m_task_t task)
 Executes a task and waits for its termination.
MSG_error_t MSG_parallel_task_execute (m_task_t task)
 Executes a parallel task and waits for its termination.
MSG_error_t MSG_process_sleep (double nb_sec)
 Sleep for the specified number of seconds.
MSG_error_t MSG_task_receive_from_host (m_task_t *task, const char *alias, m_host_t host)
 Deprecated function that used to receive a task from a mailbox from a specific host.
MSG_error_t MSG_task_receive (m_task_t *task, const char *alias)
 Receives a task from a mailbox.
MSG_error_t MSG_task_receive_with_timeout (m_task_t *task, const char *alias, double timeout)
 Receives a task from a mailbox with a given timeout.
MSG_error_t MSG_task_receive_ext (m_task_t *task, const char *alias, double timeout, m_host_t host)
 Receives a task from a mailbox from a specific host with a given timeout.
msg_comm_t MSG_task_isend (m_task_t task, const char *alias)
 Sends a task on a mailbox.
msg_comm_t MSG_task_isend_with_matching (m_task_t task, const char *alias, int(*match_fun)(void *, void *, smx_action_t), void *match_data)
 Sends a task on a mailbox, with support for matching requests.
void MSG_task_dsend (m_task_t task, const char *alias, void_f_pvoid_t cleanup)
 Sends a task on a mailbox.
msg_comm_t MSG_task_irecv (m_task_t *task, const char *name)
 Starts listening for receiving a task from an asynchronous communication.
int MSG_comm_test (msg_comm_t comm)
 Checks whether a communication is done, and if yes, finalizes it.
int MSG_comm_testany (xbt_dynar_t comms)
 This function checks if a communication is finished.
void MSG_comm_destroy (msg_comm_t comm)
 Destroys a communication.
MSG_error_t MSG_comm_wait (msg_comm_t comm, double timeout)
 Wait for the completion of a communication.
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.
int MSG_comm_waitany (xbt_dynar_t comms)
 This function waits for the first communication finished in a list.
MSG_error_t MSG_comm_get_status (msg_comm_t comm)
 Returns the error (if any) that occured during a finished communication.
m_task_t MSG_comm_get_task (msg_comm_t comm)
 Get a task (m_task_t) from a communication.
MSG_error_t MSG_task_send (m_task_t task, const char *alias)
 Sends a task to a mailbox.
MSG_error_t MSG_task_send_bounded (m_task_t task, const char *alias, double maxrate)
 Sends a task to a mailbox with a maximum rate.
MSG_error_t MSG_task_send_with_timeout (m_task_t task, const char *alias, double timeout)
 Sends a task to a mailbox with a timeout.
int MSG_task_listen (const char *alias)
 Check if there is a communication going on in a mailbox.
int MSG_task_listen_from_host (const char *alias, m_host_t host)
 Check the number of communication actions of a given host pending in a mailbox.
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.
void MSG_task_set_category (m_task_t task, const char *category)
 Sets the tracing category of a task.
const char * MSG_task_get_category (m_task_t task)
 Gets the current tracing category of a task.

Detailed Description

This section describes the functions that can be used by a process to execute, communicate or otherwise handle some task.


Function Documentation

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:
taska m_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

Executes a parallel task and waits for its termination.

Parameters:
taska m_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_process_sleep ( double  nb_sec)

Sleep for the specified number of seconds.

Makes the current process sleep until time seconds have elapsed.

Parameters:
nb_seca number of second
MSG_error_t MSG_task_receive_from_host ( m_task_t task,
const char *  alias,
m_host_t  host 
)

Deprecated function that used to receive a task from a mailbox from a specific host.

Sorry, this function is not supported anymore. That wouldn't be impossible to reimplement it, but we are lacking the time to do so ourselves. If you need this functionality, you can either:

  • implement the buffering mechanism on the user-level by queuing all messages received in the mailbox that do not match your expectation
  • change your application logic to leverage the mailboxes features. For example, if you have A receiving messages from B and C, you could have A waiting on mailbox "A" most of the time, but on "A#B" when it's waiting for specific messages from B and "A#C" when waiting for messages from C. You could even get A sometime waiting on all these mailboxes using MSG_comm_waitany. You can find an example of use of this function in the MSG Examples section.
  • Provide a proper patch to implement this functionality back in MSG. That wouldn't be very difficult actually. Check the function MSG_mailbox_get_task_ext. During its call to simcall_comm_recv(), the 5th argument, match_fun, is NULL. Create a function that filters messages according to the host (that you will pass as sixth argument to simcall_comm_recv() and that your filtering function will receive as first parameter, and then, the filter could simply compare the host names, for example. After sufficient testing, provide an example that we could add to the distribution, and your first contribution to SimGrid is ready. Thanks in advance.
Parameters:
taska memory location for storing a m_task_t.
aliasname of the mailbox to receive the task from
hosta m_host_t host from where the task was sent
Returns:
Returns MSG_OK if the task was successfully received, MSG_HOST_FAILURE, or MSG_TRANSFER_FAILURE otherwise.
MSG_error_t MSG_task_receive ( m_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:
taska memory location for storing a m_task_t.
aliasname 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_with_timeout ( m_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:
taska memory location for storing a m_task_t.
aliasname of the mailbox to receive the task from
timeoutis 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_ext ( m_task_t task,
const char *  alias,
double  timeout,
m_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.

Parameters:
taska memory location for storing a m_task_t.
aliasname of the mailbox to receive the task from
timeoutis the maximum wait time for completion (provide -1 for no timeout)
hosta m_host_t host from where the task was sent
Returns:
Returns MSG_OK if the task was successfully received, MSG_HOST_FAILURE, or MSG_TRANSFER_FAILURE, or MSG_TIMEOUT otherwise.
msg_comm_t MSG_task_isend ( m_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:
taska m_task_t to send on another location.
aliasname of the mailbox to sent the task to
Returns:
the msg_comm_t communication created
msg_comm_t MSG_task_isend_with_matching ( m_task_t  task,
const char *  alias,
int(*)(void *, void *, smx_action_t)  match_fun,
void *  match_data 
)

Sends a task on a mailbox, with support for matching requests.

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

Parameters:
taska m_task_t to send on another location.
aliasname of the mailbox to sent the task to
match_funboolean function which parameters are:
  • match_data_provided_here
  • match_data_provided_by_other_side_if_any
  • the_smx_action_describing_the_other_side
match_datauser provided data passed to match_fun
Returns:
the msg_comm_t communication created
void MSG_task_dsend ( m_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:
taska m_task_t to send on another location.
aliasname of the mailbox to sent the task to
cleanupa function to destroy the task if the communication fails, e.g. MSG_task_destroy (if NULL, no function will be called)
msg_comm_t MSG_task_irecv ( m_task_t task,
const char *  name 
)

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:
taska memory location for storing a m_task_t. has to be valid until the end of the communication.
nameof the mailbox to receive the task on
Returns:
the msg_comm_t communication created
int MSG_comm_test ( msg_comm_t  comm)

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

Parameters:
commthe 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 ( xbt_dynar_t  comms)

This function checks if a communication is finished.

Parameters:
commsa 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
void MSG_comm_destroy ( msg_comm_t  comm)

Destroys a communication.

Parameters:
commthe communication to destroy.
MSG_error_t MSG_comm_wait ( msg_comm_t  comm,
double  timeout 
)

Wait for the completion of a communication.

It takes two parameters.

Parameters:
commthe communication to wait.
timeoutWait until the communication terminates or the timeout occurs
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 permit to wait for each communication.

Parameters:
comma vector of communication
nb_elemis the size of the comm vector
timeoutfor 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.

Parameters:
commsa 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)

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

Parameters:
comma finished communication
Returns:
the status of the communication, or MSG_OK if no error occured during the communication

Get a task (m_task_t) from a communication.

Parameters:
commthe communication where to get the task
Returns:
the task from the communication
MSG_error_t MSG_task_send ( m_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 in the other side if MSG_task_receive is used). See MSG_task_isend for sending tasks asynchronously.

Parameters:
taskthe task to be sent
aliasthe 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 ( m_task_t  task,
const char *  alias,
double  maxrate 
)

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.

Parameters:
taskthe task to be sent
aliasthe mailbox name to where the task is sent
maxratethe maximum communication rate for sending this task
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 ( m_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:
taskthe task to be sent
aliasthe mailbox name to where the task is sent
timeoutis 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.
int MSG_task_listen ( const char *  alias)

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

Parameters:
aliasthe name of the mailbox to be considered
Returns:
Returns 1 if there is a communication, 0 otherwise
int MSG_task_listen_from_host ( const char *  alias,
m_host_t  host 
)

Check the number of communication actions of a given host pending in a mailbox.

Parameters:
aliasthe name of the mailbox to be considered
hostthe host to check for communication
Returns:
Returns the number of pending communication actions of the host in the given mailbox, 0 if there is no pending communication actions.
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:
aliasthe name of the mailbox to be considered
Returns:
Returns the PID of sender process, -1 if there is no communication in the mailbox.
void MSG_task_set_category ( m_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 Tracing Simulations for Visualization for details on how to trace the (categorized) resource utilization.

Parameters:
taskthe task that is going to be categorized
categorythe name of the category to be associated to the task
See also:
MSG_task_get_category, TRACE_category, TRACE_category_with_color
const char* MSG_task_get_category ( m_task_t  task)

Gets the current tracing category of a task.

Parameters:
taskthe task to be considered
See also:
MSG_task_set_category
Returns:
Returns the name of the tracing category of the given task, NULL otherwise


Back to the main Simgrid Documentation page The version of SimGrid documented here is v3.7.
Documentation of other versions can be found in their respective archive files (directory doc/html).
Generated by doxygen