From 22752d7347b7143b7eeb7de734cad5e469615996 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Tue, 3 Apr 2012 16:42:36 -1000 Subject: [PATCH] various MSG doc cleanups --- doc/module-msg.doc | 66 ++++++++++++++++++++------------------- include/simix/datatypes.h | 8 ++--- src/msg/msg_deployment.c | 4 +-- src/msg/msg_gos.c | 27 ++++++++-------- src/msg/msg_process.c | 24 +++++++------- 5 files changed, 65 insertions(+), 64 deletions(-) diff --git a/doc/module-msg.doc b/doc/module-msg.doc index 43443928de..5db1732a32 100644 --- a/doc/module-msg.doc +++ b/doc/module-msg.doc @@ -27,6 +27,27 @@ Also make sure to visit the page @ref MSG_examples. */ +/** +@defgroup MSG_examples MSG Examples +@ingroup MSG_API + +MSG comes with an extensive set of examples. It is sometimes difficult +to find the one you need. This list aims at helping you finding the +example from which you can learn what you want to. + +@section MSG_ex_basics Basic examples and features + +*/ + +/** @defgroup msg_simulation Main MSG simulation Functions +* @ingroup MSG_API +* @brief This section describes the functions you need to know to +* set up a simulation. You should have a look at \ref MSG_examples +* to have an overview of their usage. +* +* @htmlonly @endhtmlonly +*/ + /** @defgroup m_datatypes_management MSG Data Types @ingroup MSG_API @@ -35,24 +56,24 @@ \htmlonly \endhtmlonly */ -/** @defgroup m_process_management Processes Management Functions +/** @defgroup m_process_management Process Management Functions * @ingroup MSG_API * @brief This section describes the process structure of MSG * (#m_process_t) and the functions for managing it. */ -/** @defgroup m_host_management Management functions of Hosts +/** @defgroup m_host_management Host Management Functions * @ingroup MSG_API * @brief This section describes the host structure of MSG */ -/** @defgroup m_task_management Managing functions of Tasks +/** @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. */ - /** @defgroup m_file_management Managing functions of Files + /** @defgroup m_file_management File Management Functions * @ingroup MSG_API * @brief This section describes the file structure of MSG * (#m_file_t) and the functions for managing it. It @@ -63,19 +84,13 @@ * @ingroup MSG_API * @brief This section describes functions for managing actions. */ - + /** @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. */ -/** @defgroup msg_deprecated_functions MSG Deprecated - * @ingroup MSG_API - * @brief This section describes the deprecated functions and. They - * should be remove on next release. - */ - /** @defgroup msg_easier_life Platform and Application management * @ingroup MSG_API * @brief This section describes functions to manage the platform creation @@ -83,27 +98,6 @@ * MSG_examples for an overview of their usage. */ -/** @defgroup msg_simulation MSG simulation Functions -* @ingroup MSG_API -* @brief This section describes the functions you need to know to -* set up a simulation. You should have a look at \ref MSG_examples -* to have an overview of their usage. -* -* @htmlonly @endhtmlonly -*/ - -/** -@defgroup MSG_examples MSG Examples -@ingroup MSG_API - -MSG comes with an extensive set of examples. It is sometimes difficult -to find the one you need. This list aims at helping you finding the -example from which you can learn what you want to. - -@section MSG_ex_basics Basic examples and features - -*/ - /** @defgroup MSG_LUA Lua bindings @ingroup MSG_API @@ -141,6 +135,14 @@ example from which you can learn what you want to. is a working non-trivial example of use of the lua bindings */ +/** @defgroup msg_deprecated_functions MSG Deprecated + * @ingroup MSG_API + * @brief This section describes the deprecated functions and. They + * should be remove on next release. + */ + + + /** \defgroup MSG_ex_asynchronous_communications Asynchronous communications \ingroup MSG_examples diff --git a/include/simix/datatypes.h b/include/simix/datatypes.h index 1ed5a6abbf..b41e98944e 100644 --- a/include/simix/datatypes.h +++ b/include/simix/datatypes.h @@ -61,10 +61,10 @@ typedef struct s_smx_action *smx_action_t; /* FIXME: replace by specialized acti /* ****************************** Process *********************************** */ -/** @brief Agent datatype +/** @brief Process datatype @ingroup m_datatypes_management - An agent may be defined as a code, with some private + A processt may be defined as a code, with some private data, executing in a location. \see m_process_management @{ */ @@ -77,9 +77,9 @@ typedef struct s_smx_process *smx_process_t; * The function must accept the following parameters: * void* process: the process created will be stored there * const char *name: a name for the object. It is for user-level information and can be NULL - * xbt_main_func_t code: is a function describing the behavior of the agent + * xbt_main_func_t code: is a function describing the behavior of the process * void *data: data a pointer to any data one may want to attach to the new object. - * smx_host_t host: the location where the new agent is executed + * smx_host_t host: the location where the new process is executed * int argc, char **argv: parameters passed to code * xbt_dict_t pros: properties */ diff --git a/src/msg/msg_deployment.c b/src/msg/msg_deployment.c index e2252af5d2..ac9c5768e4 100644 --- a/src/msg/msg_deployment.c +++ b/src/msg/msg_deployment.c @@ -35,7 +35,7 @@ void MSG_launch_application(const char *file) } /** \ingroup msg_easier_life - * \brief Registers the main function of an agent in a global table. + * \brief Registers the main function of a process in a global table. * * Registers a code function in a global table. * This table is then used by #MSG_launch_application. @@ -49,7 +49,7 @@ void MSG_function_register(const char *name, xbt_main_func_t code) } /** \ingroup msg_easier_life - * \brief Registers a function as the default main function of agents. + * \brief Registers a function as the default main function of processes. * * Registers a code function as being the default value. This function will get used by MSG_launch_application() when there is no registered function of the requested name in. * \param code the function (must have the same prototype than the main function of any C program: int ..(int argc, char *argv[])) diff --git a/src/msg/msg_gos.c b/src/msg/msg_gos.c index 45e9dd460f..dc1a480c20 100644 --- a/src/msg/msg_gos.c +++ b/src/msg/msg_gos.c @@ -15,10 +15,9 @@ XBT_LOG_NEW_DEFAULT_SUBCATEGORY(msg_gos, msg, /** \ingroup msg_gos_functions * \brief Executes a task and waits for its termination. * - * This function is used for describing the behavior of an agent. It + * This function is used for describing the behavior of a process. It * takes only one parameter. - * \param task a #m_task_t to execute on the location on which the - agent is running. + * \param task a #m_task_t to execute on the location on which the process is running. * \return #MSG_OK if the task was successfully completed, #MSG_TASK_CANCELED * or #MSG_HOST_FAILURE otherwise */ @@ -155,7 +154,7 @@ MSG_parallel_task_create(const char *name, int host_nb, /** \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. + * \param task a #m_task_t to execute on the location on which the process is running. * * \return #MSG_OK if the task was successfully completed, #MSG_TASK_CANCELED * or #MSG_HOST_FAILURE otherwise @@ -934,7 +933,7 @@ MSG_error_t MSG_get_errno(void) * \brief Put a task on a channel of an host and waits for the end of the * transmission. * - * This function is used for describing the behavior of an agent. It + * This function is used for describing the behavior of a process. It * takes three parameter. * \param task a #m_task_t to send on another location. This task will not be usable anymore when the function will return. There is @@ -947,7 +946,7 @@ MSG_error_t MSG_get_errno(void) can be transfered iff it has been correctly created with MSG_task_create(). * \param dest the destination of the message - * \param channel the channel on which the agent should put this + * \param channel the channel on which the process should put this task. This value has to be >=0 and < than the maximal number of channels fixed with MSG_set_channel_number(). * \return #MSG_HOST_FAILURE if the host on which @@ -982,7 +981,7 @@ MSG_task_put_bounded(m_task_t task, m_host_t dest, m_channel_t channel, * host (with a timeout on the waiting of the destination host) and * waits for the end of the transmission. * - * This function is used for describing the behavior of an agent. It + * This function is used for describing the behavior of a process. It * takes four parameter. * \param task a #m_task_t to send on another location. This task will not be usable anymore when the function will return. There is @@ -995,7 +994,7 @@ MSG_task_put_bounded(m_task_t task, m_host_t dest, m_channel_t channel, can be transfered iff it has been correctly created with MSG_task_create(). * \param dest the destination of the message - * \param channel the channel on which the agent should put this + * \param channel the channel on which the process should put this task. This value has to be >=0 and < than the maximal number of channels fixed with MSG_set_channel_number(). * \param timeout the maximum time to wait for a task before giving @@ -1025,7 +1024,7 @@ MSG_task_put_with_timeout(m_task_t task, m_host_t dest, * \brief Test whether there is a pending communication on a channel, and who sent it. * * It takes one parameter. - * \param channel the channel on which the agent should be + * \param channel the channel on which the process should be listening. This value has to be >=0 and < than the maximal number of channels fixed with MSG_set_channel_number(). * \return -1 if there is no pending communication and the PID of the process who sent it otherwise @@ -1052,7 +1051,7 @@ int MSG_task_probe_from(m_channel_t channel) * \brief Test whether there is a pending communication on a channel. * * It takes one parameter. - * \param channel the channel on which the agent should be + * \param channel the channel on which the process should be listening. This value has to be >=0 and < than the maximal number of channels fixed with MSG_set_channel_number(). * \return 1 if there is a pending communication and 0 otherwise @@ -1075,7 +1074,7 @@ int MSG_task_Iprobe(m_channel_t channel) channel and sent by \a host. * * It takes two parameters. - * \param channel the channel on which the agent should be + * \param channel the channel on which the process should be listening. This value has to be >=0 and < than the maximal number of channels fixed with MSG_set_channel_number(). * \param host the host that is to be watched. @@ -1104,7 +1103,7 @@ int MSG_task_probe_from_host(int channel, m_host_t host) hold a task when this function will return. Thus \a task should not be equal to \c NULL and \a *task should be equal to \c NULL. If one of those two condition does not hold, there will be a warning message. - * \param channel the channel on which the agent should be + * \param channel the channel on which the process should be listening. This value has to be >=0 and < than the maximal number of channels fixed with MSG_set_channel_number(). * \param host the host that is to be watched. @@ -1125,7 +1124,7 @@ MSG_task_get_from_host(m_task_t * task, m_channel_t channel, m_host_t host) hold a task when this function will return. Thus \a task should not be equal to \c NULL and \a *task should be equal to \c NULL. If one of those two condition does not hold, there will be a warning message. - * \param channel the channel on which the agent should be + * \param channel the channel on which the process should be listening. This value has to be >=0 and < than the maximal number of channels fixed with MSG_set_channel_number(). * \return a #MSG_error_t indicating whether the operation was successful (#MSG_OK), or why it failed otherwise. @@ -1144,7 +1143,7 @@ MSG_error_t MSG_task_get(m_task_t * task, m_channel_t channel) hold a task when this function will return. Thus \a task should not be equal to \c NULL and \a *task should be equal to \c NULL. If one of those two condition does not hold, there will be a warning message. - * \param channel the channel on which the agent should be + * \param channel the channel on which the process should be listening. This value has to be >=0 and < than the maximal number of channels fixed with MSG_set_channel_number(). * \param max_duration the maximum time to wait for a task before giving diff --git a/src/msg/msg_process.c b/src/msg/msg_process.c index 0b12e42fcd..d478050cc3 100644 --- a/src/msg/msg_process.c +++ b/src/msg/msg_process.c @@ -12,7 +12,7 @@ XBT_LOG_NEW_DEFAULT_SUBCATEGORY(msg_process, msg, "Logging specific to MSG (process)"); /** @addtogroup m_process_management - * \htmlonly \endhtmlonly + * \htmlonly \endhtmlonly * * We need to simulate many independent scheduling decisions, so * the concept of process is at the heart of the @@ -91,7 +91,7 @@ m_process_t MSG_process_create(const char *name, * created, and put in the list of ready process. * \param name a name for the object. It is for user-level information and can be NULL. - * \param code is a function describing the behavior of the agent. It + * \param code is a function describing the behavior of the process. It should then only use functions described in \ref m_process_management (to create a new #m_process_t for example), in \ref m_host_management (only the read-only functions i.e. whose @@ -101,7 +101,7 @@ m_process_t MSG_process_create(const char *name, * \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. - * \param host the location where the new agent is executed. + * \param host the location where the new process is executed. * \param argc first argument passed to \a code * \param argv second argument passed to \a code * \see m_process_t @@ -125,7 +125,7 @@ m_process_t MSG_process_create_with_arguments(const char *name, * created, and put in the list of ready process. * \param name a name for the object. It is for user-level information and can be NULL. - * \param code is a function describing the behavior of the agent. It + * \param code is a function describing the behavior of the process. It should then only use functions described in \ref m_process_management (to create a new #m_process_t for example), in \ref m_host_management (only the read-only functions i.e. whose @@ -135,7 +135,7 @@ m_process_t MSG_process_create_with_arguments(const char *name, * \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. - * \param host the location where the new agent is executed. + * \param host the location where the new process is executed. * \param argc first argument passed to \a code * \param argv second argument passed to \a code * \param properties list a properties defined for this process @@ -218,7 +218,7 @@ void MSG_process_kill(m_process_t process) } /** \ingroup m_process_management - * \brief Migrates an agent to another location. + * \brief Migrates a process to another location. * * This function checks whether \a process and \a host are valid pointers and change the value of the #m_host_t on which \a process is running. @@ -278,7 +278,7 @@ XBT_PUBLIC(void) MSG_process_set_data_cleanup(void_f_pvoid_t data_cleanup) { } /** \ingroup m_process_management - * \brief Return the location on which an agent is running. + * \brief Return the location on which a process is running. * \param process a process (NULL means the current one) * \return the m_host_t corresponding to the location on which \a * process is running. @@ -336,8 +336,8 @@ int MSG_process_get_PID(m_process_t process) * \brief Returns the process ID of the parent of \a process. * * This function checks whether \a process is a valid pointer or not - and return its PID. Returns -1 if the agent has not been created by - another agent. + and return its PID. Returns -1 if the process has not been created by + any other process. */ int MSG_process_get_PPID(m_process_t process) { @@ -349,7 +349,7 @@ int MSG_process_get_PPID(m_process_t process) } /** \ingroup m_process_management - * \brief Return the name of an agent. + * \brief Return the name of a process. * * This function checks whether \a process is a valid pointer or not and return its name. @@ -388,7 +388,7 @@ xbt_dict_t MSG_process_get_properties(m_process_t process) } /** \ingroup m_process_management - * \brief Return the PID of the current agent. + * \brief Return the PID of the current process. * * This function returns the PID of the currently running #m_process_t. */ @@ -398,7 +398,7 @@ int MSG_process_self_PID(void) } /** \ingroup m_process_management - * \brief Return the PPID of the current agent. + * \brief Return the PPID of the current process. * * This function returns the PID of the parent of the currently * running #m_process_t. -- 2.20.1