SimGrid: Task Actions

SimGrid 3.10 Versatile Simulation of Distributed Systems

- Home page
- Online documentation
- Dev's Corner

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
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 (msg_task_t task)
| Executes a task and waits for its termination.
msg_error_t | MSG_parallel_task_execute (msg_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 (msg_task_t *task, const char *alias, msg_host_t host)
| Deprecated function that used to receive a task from a mailbox from a specific host.
msg_error_t | MSG_task_receive (msg_task_t *task, const char *alias)
| Receives a task from a mailbox.
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.
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.
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.
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.
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.
msg_comm_t | MSG_task_isend (msg_task_t task, const char *alias)
| Sends a task on a mailbox.
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.
msg_comm_t | MSG_task_isend_with_matching (msg_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 (msg_task_t task, const char *alias, void_f_pvoid_t cleanup)
| Sends a task on a mailbox.
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.
msg_comm_t | MSG_task_irecv (msg_task_t *task, const char *name)
| Starts listening for receiving a task from an asynchronous communication.
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.
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.
msg_task_t | MSG_comm_get_task (msg_comm_t comm)
| Get a task (msg_task_t) from a communication.
msg_error_t | MSG_task_send (msg_task_t task, const char *alias)
| Sends a task to a mailbox.
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.
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.
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.
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, msg_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 (msg_task_t task, const char *category)
| Sets the tracing category of a task.
const char * | MSG_task_get_category (msg_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

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

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

msg_error_t MSG_task_receive_from_host | ( | msg_task_t * | task,
|  | const char * | alias,
|  | msg_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

  task | a memory location for storing a msg_task_t.
  alias | name of the mailbox to receive the task from
  host | a 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 otherwise.

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.

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

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.

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

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

  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

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

  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

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

Returns
  the msg_comm_t communication created

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

  task | a msg_task_t to send on another location.
  alias | name of the mailbox to sent the task to
  match_fun | boolean function which parameters are: match_data_provided_here match_data_provided_by_other_side_if_any the_smx_action_describing_the_other_side
  match_data | user provided data passed to match_fun

Returns
  the msg_comm_t communication created

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

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 NULL, no function will be called)
  maxrate | the maximum communication rate for sending this task

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

  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 * | name,
|  | double | rate
| ) |  |

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

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

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

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

void MSG_comm_destroy | ( | msg_comm_t | comm | ) |

Destroys a communication.

Parameters

  comm | the 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

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

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)

msg_error_t MSG_comm_get_status | ( | msg_comm_t | comm | ) |

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

Parameters

  comm | a finished communication

Returns
  the status of the communication, or MSG_OK if no error occured during the communication

msg_task_t MSG_comm_get_task | ( | 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

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

  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

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.

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

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

  alias | the 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,
|  | msg_host_t | host
| ) |  |

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

Parameters

  alias | the name of the mailbox to be considered
  host | the 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

  alias | the 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 | ( | 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 Tracing Simulations for details on how to trace the (categorized) resource utilization.

Parameters

  task | the task that is going to be categorized
  category | the 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 | ( | msg_task_t | task | ) |

Gets the current tracing category of a task.

Parameters

  task | the task to be considered

See Also
  MSG_task_set_category

Returns
  Returns the name of the tracing category of the given task, NULL otherwise