SimGrid  3.15
Versatile Simulation of Distributed Systems

Detailed Description

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

Typedefs

typedef struct msg_commmsg_comm_t
 Communication action. More...
 

Functions

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

Typedef Documentation

◆ msg_comm_t

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.

Function Documentation

◆ MSG_task_execute()

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
taska 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_parallel_task_execute()

msg_error_t MSG_parallel_task_execute ( msg_task_t  task)

Executes a parallel task and waits for its termination.

Parameters
taska 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_process_sleep()

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

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
taska memory location for storing a msg_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_task_receive_bounded()

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.

Parameters
taska memory location for storing a msg_task_t.
aliasname of the mailbox to receive the task from
ratelimit the reception to rate bandwidth
Returns
Returns MSG_OK if the task was successfully received, MSG_HOST_FAILURE, or MSG_TRANSFER_FAILURE otherwise.

◆ MSG_task_receive_with_timeout()

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
taska memory location for storing a msg_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_task_receive_with_timeout_bounded()

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.

Parameters
taska memory location for storing a msg_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)
ratelimit the reception to rate bandwidth
Returns
Returns MSG_OK if the task was successfully received, MSG_HOST_FAILURE, or MSG_TRANSFER_FAILURE, or MSG_TIMEOUT otherwise.

◆ MSG_task_receive_ext()

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.

Parameters
taska memory location for storing a msg_task_t.
aliasname of the mailbox to receive the task from
timeoutis the maximum wait time for completion (provide -1 for no timeout)
hosta msg_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_task_receive_ext_bounded()

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.

Parameters
taska memory location for storing a msg_task_t.
aliasname of the mailbox to receive the task from
timeoutis the maximum wait time for completion (provide -1 for no timeout)
hosta msg_host_t host from where the task was sent
ratelimit the reception to rate bandwidth
Returns
Returns MSG_OK if the task was successfully received, MSG_HOST_FAILURE, or MSG_TRANSFER_FAILURE, or MSG_TIMEOUT otherwise.

◆ MSG_task_isend()

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
taska msg_task_t to send on another location.
aliasname of the mailbox to sent the task to
Returns
the msg_comm_t communication created

◆ MSG_task_isend_bounded()

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
taska msg_task_t to send on another location.
aliasname of the mailbox to sent the task to
maxratethe maximum communication rate for sending this task .
Returns
the msg_comm_t communication created

◆ MSG_task_isend_with_matching()

msg_comm_t MSG_task_isend_with_matching ( msg_task_t  task,
const char *  alias,
int(*)(void *, void *, smx_activity_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 msg_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_synchro_describing_the_other_side
match_datauser provided data passed to match_fun
Returns
the msg_comm_t communication created

◆ MSG_task_dsend()

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
taska msg_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 nullptr, no function will be called)

◆ MSG_task_dsend_bounded()

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.

Parameters
taska msg_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 nullptr, no function will be called)
maxratethe maximum communication rate for sending this task

◆ MSG_task_irecv()

msg_comm_t MSG_task_irecv ( msg_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 msg_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

◆ MSG_task_irecv_bounded()

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

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

Parameters
taska memory location for storing a msg_task_t. has to be valid until the end of the communication.
nameof the mailbox to receive the task on
ratelimit the bandwidth to the given rate
Returns
the msg_comm_t communication created

◆ MSG_comm_test()

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.

◆ MSG_comm_testany()

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

◆ MSG_comm_destroy()

void MSG_comm_destroy ( msg_comm_t  comm)

Destroys a communication.

Parameters
commthe communication to destroy.

◆ MSG_comm_wait()

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. You can provide a -1 timeout to obtain an infinite timeout.
Returns
msg_error_t

◆ MSG_comm_waitall()

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

◆ MSG_comm_waitany()

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)

◆ MSG_comm_get_status()

msg_error_t MSG_comm_get_status ( msg_comm_t  comm)

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

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

◆ MSG_comm_get_task()

msg_task_t MSG_comm_get_task ( msg_comm_t  comm)

Get a task (msg_task_t) from a communication.

Parameters
commthe communication where to get the task
Returns
the task from the communication

◆ MSG_task_send()

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

msg_error_t MSG_task_send_bounded ( msg_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_task_send_with_timeout()

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

◆ MSG_task_send_with_timeout_bounded()

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.

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)
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, or MSG_TIMEOUT otherwise.

◆ MSG_task_listen()

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

◆ MSG_task_listen_from()

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.

◆ MSG_task_set_category()

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 Visualization and Statistical Analysis 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

◆ MSG_task_get_category()

const char* MSG_task_get_category ( msg_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, nullptr otherwise