From: Martin Quinson Date: Wed, 4 Apr 2012 04:21:33 +0000 (-1000) Subject: Doc improvement: rename GOS into task usage X-Git-Tag: v3_7~115 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/5db8a803e049ab79dc49c94d276cb3e9dd8db04c Doc improvement: rename GOS into task usage who remember of Globus GOS anyway? And Operating System-like names sound really strange now that the 21 century finally came. --- diff --git a/doc/install.doc b/doc/install.doc index b737c17747..92f9806a7b 100644 --- a/doc/install.doc +++ b/doc/install.doc @@ -415,7 +415,7 @@ feel free to organize it as you want). \li sched.c: a C file including sched.h and implementing the core of the scheduler. Most of these functions use the MSG functions defined in section \ref - msg_gos_functions. + msg_task_usage. \li masterslave.c: a C file with the main function, i.e. the MSG initialization (MSG_global_init()), the platform diff --git a/doc/module-msg.doc b/doc/module-msg.doc index 9aaeb9e6dc..e6282dde3c 100644 --- a/doc/module-msg.doc +++ b/doc/module-msg.doc @@ -13,15 +13,16 @@ the documentation provided in the relevant packages. \section MSG_funct Offered functionnalities + - \ref msg_simulation - \ref m_process_management - \ref m_datatypes_management - \ref m_host_management - \ref m_task_management - \ref msg_file_management + - \ref msg_task_usage - \ref msg_trace_driven - - \ref msg_gos_functions - \ref msg_deprecated_functions - - \ref msg_simulation + Also make sure to visit the page @ref MSG_examples. */ @@ -83,16 +84,26 @@ details). /** @defgroup m_task_management Task Management Functions * @ingroup MSG_API * @brief This section describes the task structure of MSG - * (#m_task_t) and the functions for managing it. + * (#m_task_t) and the functions for managing it. See + * \ref msg_task_usage to see how to put the tasks in action. + * + * \htmlonly \endhtmlonly */ - /** @defgroup msg_file_management File Management Functions +/** @defgroup msg_task_usage Task Usage + * @ingroup MSG_API + * @brief This section describes the functions that can be used + * by a process to execute, communicate or otherwise handle some task. + */ + +/** @defgroup msg_file_management File Management Functions * @ingroup MSG_API * @brief This section describes the file structure of MSG * (#msg_file_t) and the functions for managing it. It * is based on POSIX functions. */ - + + /** @defgroup msg_trace_driven Trace-driven simulations @ingroup MSG_API @@ -117,11 +128,6 @@ Check the examples in examples/msg/actions/actions.c for details. */ -/** @defgroup msg_gos_functions MSG Operating System Functions - * @ingroup MSG_API - * @brief This section describes the functions that can be used - * by a process for handling some task. - */ /** diff --git a/src/msg/msg_gos.c b/src/msg/msg_gos.c index dc1a480c20..4623eb68a1 100644 --- a/src/msg/msg_gos.c +++ b/src/msg/msg_gos.c @@ -12,7 +12,7 @@ XBT_LOG_NEW_DEFAULT_SUBCATEGORY(msg_gos, msg, "Logging specific to MSG (gos)"); -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * \brief Executes a task and waits for its termination. * * This function is used for describing the behavior of a process. It @@ -151,7 +151,7 @@ MSG_parallel_task_create(const char *name, int host_nb, return task; } -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * \brief Executes a parallel task and waits for its termination. * * \param task a #m_task_t to execute on the location on which the process is running. @@ -214,7 +214,7 @@ MSG_error_t MSG_parallel_task_execute(m_task_t task) } -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * \brief Sleep for the specified number of seconds * * Makes the current process sleep until \a time seconds have elapsed. @@ -252,7 +252,7 @@ MSG_error_t MSG_process_sleep(double nb_sec) } } -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * \brief Receives a task from a mailbox from a specific host. * * This is a blocking function, the execution flow will be blocked @@ -274,7 +274,7 @@ 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 +/** \ingroup msg_task_usage * \brief Receives a task from a mailbox. * * This is a blocking function, the execution flow will be blocked @@ -293,7 +293,7 @@ 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 +/** \ingroup msg_task_usage * \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 @@ -316,7 +316,7 @@ 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 +/** \ingroup msg_task_usage * \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 @@ -344,7 +344,7 @@ MSG_task_receive_ext(m_task_t * task, const char *alias, double timeout, host, timeout); } -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * \brief Sends a task on a mailbox. * * This is a non blocking function: use MSG_comm_wait() or MSG_comm_test() @@ -359,7 +359,7 @@ msg_comm_t MSG_task_isend(m_task_t task, const char *alias) return MSG_task_isend_with_matching(task,alias,NULL,NULL); } -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * \brief 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() @@ -406,7 +406,7 @@ XBT_INLINE msg_comm_t MSG_task_isend_with_matching(m_task_t task, const char *al return comm; } -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * \brief Sends a task on a mailbox. * * This is a non blocking detached send function. @@ -449,7 +449,7 @@ void MSG_task_dsend(m_task_t task, const char *alias, void_f_pvoid_t cleanup) t_simdata->comm = comm; } -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * \brief Starts listening for receiving a task from an asynchronous communication. * * This is a non blocking function: use MSG_comm_wait() or MSG_comm_test() @@ -482,7 +482,7 @@ msg_comm_t MSG_task_irecv(m_task_t *task, const char *name) return comm; } -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * \brief Checks whether a communication is done, and if yes, finalizes it. * \param comm the communication to test * \return TRUE if the communication is finished @@ -529,7 +529,7 @@ int MSG_comm_test(msg_comm_t comm) return finished; } -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * \brief This function checks if a communication is finished. * \param comms a vector of communications * \return the position of the finished communication if any @@ -592,7 +592,7 @@ int MSG_comm_testany(xbt_dynar_t comms) return finished_index; } -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * \brief Destroys a communication. * \param comm the communication to destroy. */ @@ -601,7 +601,7 @@ void MSG_comm_destroy(msg_comm_t comm) xbt_free(comm); } -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * \brief Wait for the completion of a communication. * * It takes two parameters. @@ -642,7 +642,7 @@ MSG_error_t MSG_comm_wait(msg_comm_t comm, double timeout) return comm->status; } -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * \brief This function is called by a sender and permit to wait for each communication * * \param comm a vector of communication @@ -657,7 +657,7 @@ void MSG_comm_waitall(msg_comm_t * comm, int nb_elem, double timeout) } } -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * \brief This function waits for the first communication finished in a list. * \param comms a vector of communications * \return the position of the first finished communication @@ -720,7 +720,7 @@ int MSG_comm_waitany(xbt_dynar_t comms) } /** - * \ingroup msg_gos_functions + * \ingroup msg_task_usage * \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 @@ -731,7 +731,7 @@ MSG_error_t MSG_comm_get_status(msg_comm_t comm) { return comm->status; } -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * \brief Get a task (#m_task_t) from a communication * * \param comm the communication where to get the task @@ -763,7 +763,7 @@ void MSG_comm_copy_data_from_SIMIX(smx_action_t comm, void* buff, size_t buff_si } } -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * \brief Sends a task to a mailbox * * This is a blocking function, the execution flow will be blocked @@ -782,7 +782,7 @@ MSG_error_t MSG_task_send(m_task_t task, const char *alias) return MSG_task_send_with_timeout(task, alias, -1); } -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * \brief Sends a task to a mailbox with a maximum rate * * This is a blocking function, the execution flow will be blocked @@ -803,7 +803,7 @@ MSG_task_send_bounded(m_task_t task, const char *alias, double maxrate) return MSG_task_send(task, alias); } -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * \brief Sends a task to a mailbox with a timeout * * This is a blocking function, the execution flow will be blocked @@ -824,7 +824,7 @@ MSG_task_send_with_timeout(m_task_t task, const char *alias, task, timeout); } -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * \brief Check if there is a communication going on in a mailbox. * * \param alias the name of the mailbox to be considered @@ -836,7 +836,7 @@ int MSG_task_listen(const char *alias) return !MSG_mailbox_is_empty(MSG_mailbox_get_by_alias(alias)); } -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * \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 @@ -853,7 +853,7 @@ int MSG_task_listen_from_host(const char *alias, m_host_t host) (alias), host); } -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * \brief Look if there is a communication on a mailbox and return the * PID of the sender process. * @@ -873,7 +873,7 @@ int MSG_task_listen_from(const char *alias) return MSG_process_get_PID(task->simdata->sender); } -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * \brief Sets the tracing category of a task. * * This function should be called after the creation of @@ -899,7 +899,7 @@ void MSG_task_set_category (m_task_t task, const char *category) #endif } -/** \ingroup msg_gos_functions +/** \ingroup msg_task_usage * * \brief Gets the current tracing category of a task. * diff --git a/src/msg/msg_process.c b/src/msg/msg_process.c index df2bf648ce..8f73cbb22f 100644 --- a/src/msg/msg_process.c +++ b/src/msg/msg_process.c @@ -97,7 +97,7 @@ m_process_t MSG_process_create(const char *name, in \ref m_host_management (only the read-only functions i.e. whose name contains the word get), in \ref m_task_management (to create or destroy some #m_task_t for example) and in \ref - msg_gos_functions (to handle file transfers and task processing). + msg_task_usage (to handle file transfers and task processing). * \param data a pointer to any data one may want to attach to the new object. It is for user-level information and can be NULL. It can be retrieved with the function \ref MSG_process_get_data. @@ -131,7 +131,7 @@ m_process_t MSG_process_create_with_arguments(const char *name, in \ref m_host_management (only the read-only functions i.e. whose name contains the word get), in \ref m_task_management (to create or destroy some #m_task_t for example) and in \ref - msg_gos_functions (to handle file transfers and task processing). + msg_task_usage (to handle file transfers and task processing). * \param data a pointer to any data one may want to attach to the new object. It is for user-level information and can be NULL. It can be retrieved with the function \ref MSG_process_get_data. diff --git a/src/msg/msg_task.c b/src/msg/msg_task.c index 0ae9b464b2..60d26b6bae 100644 --- a/src/msg/msg_task.c +++ b/src/msg/msg_task.c @@ -9,7 +9,7 @@ #include "xbt/log.h" /** @addtogroup m_task_management - * \htmlonly \endhtmlonly + * * * Since most scheduling algorithms rely on a concept of task * that can be either computed locally or