X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/0a0481f82fc27b7306940b78c411a3d6e5c84d1c..e9c069dd94c45e768bbcc65e4232fdde688a7e37:/src/msg/msg_gos.c diff --git a/src/msg/msg_gos.c b/src/msg/msg_gos.c index 5cd5b9020e..7043c047d4 100644 --- a/src/msg/msg_gos.c +++ b/src/msg/msg_gos.c @@ -27,7 +27,6 @@ MSG_error_t MSG_task_execute(m_task_t task) simdata_task_t simdata = NULL; simdata_process_t p_simdata; e_smx_state_t comp_state; - CHECK_HOST(); simdata = task->simdata; @@ -153,12 +152,19 @@ MSG_parallel_task_create(const char *name, int host_nb, return task; } +/** \ingroup msg_gos_functions + * \brief Executes a parallel task and waits for its termination. + * + * \param task a #m_task_t to execute on the location on which the agent is running. + * + * \return #MSG_OK if the task was successfully completed, #MSG_TASK_CANCELED + * or #MSG_HOST_FAILURE otherwise + */ MSG_error_t MSG_parallel_task_execute(m_task_t task) { simdata_task_t simdata = NULL; e_smx_state_t comp_state; simdata_process_t p_simdata; - CHECK_HOST(); simdata = task->simdata; p_simdata = SIMIX_process_self_get_data(SIMIX_process_self()); @@ -247,6 +253,21 @@ MSG_error_t MSG_process_sleep(double nb_sec) } } +/** \ingroup msg_gos_functions + * \brief Receives a task from a mailbox from a specific host. + * + * This is a blocking function, the execution flow will be blocked + * until the task is received. See #MSG_task_irecv + * for receiving tasks asynchronously. + * + * \param task a memory location for storing a #m_task_t. + * \param alias name of the mailbox to receive the task from + * \param host a #m_host_t host from where the task was sent + * + * \return Returns + * #MSG_OK if the task was successfully received, + * #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE otherwise. + */ MSG_error_t MSG_task_receive_from_host(m_task_t * task, const char *alias, m_host_t host) @@ -254,11 +275,41 @@ MSG_task_receive_from_host(m_task_t * task, const char *alias, return MSG_task_receive_ext(task, alias, -1, host); } +/** \ingroup msg_gos_functions + * \brief 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. + * + * \param task a memory location for storing a #m_task_t. + * \param alias name of the mailbox to receive the task from + * + * \return 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) { return MSG_task_receive_with_timeout(task, alias, -1); } +/** \ingroup msg_gos_functions + * \brief 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. + * + * \param task a memory location for storing a #m_task_t. + * \param alias name of the mailbox to receive the task from + * \param timeout is the maximum wait time for completion (if -1, this call is the same as #MSG_task_receive) + * + * \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(m_task_t * task, const char *alias, double timeout) @@ -266,6 +317,23 @@ MSG_task_receive_with_timeout(m_task_t * task, const char *alias, return MSG_task_receive_ext(task, alias, timeout, NULL); } +/** \ingroup msg_gos_functions + * \brief 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. + * + * \param task a memory location for storing a #m_task_t. + * \param alias name of the mailbox to receive the task from + * \param timeout is the maximum wait time for completion (provide -1 for no timeout) + * \param host a #m_host_t host from where the task was sent + * + * \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_ext(m_task_t * task, const char *alias, double timeout, m_host_t host) @@ -312,8 +380,6 @@ XBT_INLINE msg_comm_t MSG_task_isend_with_matching(m_task_t task, const char *al m_process_t process = MSG_process_self(); msg_mailbox_t mailbox = MSG_mailbox_get_by_alias(alias); - CHECK_HOST(); - /* FIXME: these functions are not traceable */ /* Prepare the task to send */ @@ -364,8 +430,6 @@ void MSG_task_dsend(m_task_t task, const char *alias, void_f_pvoid_t cleanup) m_process_t process = MSG_process_self(); msg_mailbox_t mailbox = MSG_mailbox_get_by_alias(alias); - CHECK_HOST(); - /* FIXME: these functions are not traceable */ /* Prepare the task to send */ @@ -400,8 +464,6 @@ msg_comm_t MSG_task_irecv(m_task_t *task, const char *name) { smx_rdv_t rdv = MSG_mailbox_get_by_alias(name); - CHECK_HOST(); - /* FIXME: these functions are not traceable */ /* Sanity check */ @@ -662,7 +724,7 @@ int MSG_comm_waitany(xbt_dynar_t comms) * \ingroup msg_gos_functions * \brief Returns the error (if any) that occured during a finished communication. * \param comm a finished communication - * \return the status of the communication, or MSG_OK if no error occured + * \return the status of the communication, or #MSG_OK if no error occured * during the communication */ MSG_error_t MSG_comm_get_status(msg_comm_t comm) { @@ -670,6 +732,12 @@ MSG_error_t MSG_comm_get_status(msg_comm_t comm) { return comm->status; } +/** \ingroup msg_gos_functions + * \brief Get a task (#m_task_t) from a communication + * + * \param comm the communication where to get the task + * \return the task from the communication + */ m_task_t MSG_comm_get_task(msg_comm_t comm) { xbt_assert(comm, "Invalid parameter"); @@ -696,13 +764,39 @@ void MSG_comm_copy_data_from_SIMIX(smx_action_t comm, void* buff, size_t buff_si } } +/** \ingroup msg_gos_functions + * \brief 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. + * + * \param task the task to be sent + * \param alias the mailbox name to where the task is sent + * + * \return Returns #MSG_OK if the task was successfully sent, + * #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE otherwise. + */ MSG_error_t MSG_task_send(m_task_t task, const char *alias) { XBT_DEBUG("MSG_task_send: Trying to send a message on mailbox '%s'", alias); return MSG_task_send_with_timeout(task, alias, -1); } - +/** \ingroup msg_gos_functions + * \brief 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. + * + * \param task the task to be sent + * \param alias the mailbox name to where the task is sent + * \param maxrate the maximum communication rate for sending this task + * + * \return 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) { @@ -710,7 +804,19 @@ MSG_task_send_bounded(m_task_t task, const char *alias, double maxrate) return MSG_task_send(task, alias); } - +/** \ingroup msg_gos_functions + * \brief 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. + * + * \param task the task to be sent + * \param alias the mailbox name to where the task is sent + * \param timeout is the maximum wait time for completion (if -1, this call is the same as #MSG_task_send) + * + * \return 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(m_task_t task, const char *alias, double timeout) @@ -719,28 +825,48 @@ MSG_task_send_with_timeout(m_task_t task, const char *alias, task, timeout); } +/** \ingroup msg_gos_functions + * \brief Check if there is a communication going on in a mailbox. + * + * \param alias the name of the mailbox to be considered + * + * \return Returns 1 if there is a communication, 0 otherwise + */ int MSG_task_listen(const char *alias) { - CHECK_HOST(); - return !MSG_mailbox_is_empty(MSG_mailbox_get_by_alias(alias)); } +/** \ingroup msg_gos_functions + * \brief Check the number of communication actions of a given host pending in a mailbox. + * + * \param alias the name of the mailbox to be considered + * \param host the host to check for communication + * + * \return 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_host(const char *alias, m_host_t host) { - CHECK_HOST(); - return MSG_mailbox_get_count_host_waiting_tasks(MSG_mailbox_get_by_alias (alias), host); } +/** \ingroup msg_gos_functions + * \brief Look if there is a communication on a mailbox and return the + * PID of the sender process. + * + * \param alias the name of the mailbox to be considered + * + * \return Returns the PID of sender process, + * -1 if there is no communication in the mailbox. + */ int MSG_task_listen_from(const char *alias) { m_task_t task; - CHECK_HOST(); - if (NULL == (task = MSG_mailbox_get_head(MSG_mailbox_get_by_alias(alias)))) return -1; @@ -748,6 +874,45 @@ int MSG_task_listen_from(const char *alias) return MSG_process_get_PID(task->simdata->sender); } +/** \ingroup msg_gos_functions + * + * See \ref tracing_tracing for details on how to trace + * the (categorized) resource utilization. + * + * \brief Sets the tracing category of a task. + * + * \param task the task that is going to be categorized + * \param category the name of the category to be associated to the task + * + * \see MSG_task_get_category, TRACE_category, TRACE_category_with_color + */ +void MSG_task_set_category (m_task_t task, const char *category) +{ +#ifdef HAVE_TRACING + TRACE_msg_set_task_category (task, category); +#endif +} + + +/** \ingroup msg_gos_functions + * + * \brief Gets the current tracing category of a task. + * + * \param task the task to be considered + * + * \see MSG_task_set_category + * + * \return Returns the name of the tracing category of the given task, NULL otherwise + */ +const char *MSG_task_get_category (m_task_t task) +{ +#ifdef HAVE_TRACING + return task->category; +#else + return NULL; +#endif +} + #ifdef MSG_USE_DEPRECATED /** \ingroup msg_gos_functions * @@ -862,8 +1027,6 @@ int MSG_task_probe_from(m_channel_t channel) XBT_WARN("DEPRECATED! Now use MSG_task_listen_from"); m_task_t task; - CHECK_HOST(); - xbt_assert((channel >= 0) && (channel < msg_global->max_channel), "Invalid channel %d", channel); @@ -893,8 +1056,6 @@ int MSG_task_Iprobe(m_channel_t channel) && (channel < msg_global->max_channel), "Invalid channel %d", channel); - CHECK_HOST(); - return !MSG_mailbox_is_empty(MSG_mailbox_get_by_channel (MSG_host_self(), channel)); @@ -920,8 +1081,6 @@ int MSG_task_probe_from_host(int channel, m_host_t host) && (channel < msg_global->max_channel), "Invalid channel %d", channel); - CHECK_HOST(); - return MSG_mailbox_get_count_host_waiting_tasks(MSG_mailbox_get_by_channel (MSG_host_self(), channel), @@ -994,11 +1153,6 @@ MSG_task_get_with_timeout(m_task_t * task, m_channel_t channel, return MSG_task_get_ext(task, channel, max_duration, NULL); } -/** \defgroup msg_gos_functions MSG Operating System Functions - * \brief This section describes the functions that can be used - * by an agent for handling some task. - */ - MSG_error_t MSG_task_get_ext(m_task_t * task, m_channel_t channel, double timeout, m_host_t host)