From: Martin Quinson Date: Wed, 4 Apr 2012 04:06:05 +0000 (-1000) Subject: improve the doc of MSG datatypes (and dispatch them in the relevant modules) X-Git-Tag: v3_7~116 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/a13889143f3dcc24f6100d07e9d20e710e74e0ad improve the doc of MSG datatypes (and dispatch them in the relevant modules) --- diff --git a/doc/FAQ.doc b/doc/FAQ.doc index 88f7afc863..381deda119 100644 --- a/doc/FAQ.doc +++ b/doc/FAQ.doc @@ -523,7 +523,7 @@ come after -lsimgrid on this command line. \subsubsection faq_trouble_lib_msg_deprecated "gcc: undefined reference to MSG_*" -Since version 3.7 all the #m_channel_t mecanism is deprecated. So functions +Since version 3.7 all the m_channel_t mecanism is deprecated. So functions about this mecanism may get removed in future releases. List of functions: diff --git a/include/msg/datatypes.h b/include/msg/datatypes.h index 4741045893..b081c6b438 100644 --- a/include/msg/datatypes.h +++ b/include/msg/datatypes.h @@ -14,12 +14,8 @@ SG_BEGIN_DECL() /* ******************************** Host ************************************ */ -/** @defgroup m_datatypes_management_details Details on MSG datatypes - @ingroup m_datatypes_management*/ typedef struct simdata_host *simdata_host_t; -/** @brief Host datatype - @ingroup m_datatypes_management_details */ typedef struct m_host { char *name; /**< @brief host name if any */ simdata_host_t simdata; /**< @brief simulator data */ @@ -27,7 +23,7 @@ typedef struct m_host { } s_m_host_t; /** @brief Host datatype - @ingroup m_datatypes_management + @ingroup m_host_management A location (or host) is any possible place where a process may run. Thus it is represented as a physical @@ -35,18 +31,13 @@ typedef struct m_host { to enable running process to communicate with remote ones, and some private data that can be only accessed by local process. - - \see m_host_management - @{ */ + */ typedef struct m_host *m_host_t; -/** @} */ /* ******************************** Task ************************************ */ typedef struct simdata_task *simdata_task_t; -/** @brief Task datatype - @ingroup m_datatypes_management_details */ typedef struct m_task { char *name; /**< @brief task name if any */ simdata_task_t simdata; /**< @brief simulator data */ @@ -58,29 +49,29 @@ typedef struct m_task { } s_m_task_t; /** @brief Task datatype - @ingroup m_datatypes_management + @ingroup m_task_management A task may then be defined by a computing amount, a message size and some private data. - \see m_task_management - @{ */ + */ typedef struct m_task *m_task_t; -/* ******************************** File ************************************ */ +/* ******************************** File ************************************ */ typedef struct simdata_file *simdata_file_t; -/** @brief File datatype - @ingroup m_datatypes_management_details */ typedef struct msg_file { char *name; /**< @brief file name */ simdata_file_t simdata; /**< @brief simulator data */ void *data; /**< @brief user data */ } s_msg_file_t; -/** @brief File datatype - @ingroup m_datatypes_management_details */ +/** @brief File datatype. + @ingroup msg_file_management + + You should consider this as an opaque object. + */ typedef struct msg_file *msg_file_t; typedef s_file_stat_t s_msg_stat_t, *msg_stat_t; @@ -89,8 +80,6 @@ typedef s_file_stat_t s_msg_stat_t, *msg_stat_t; /*************** Begin GPU ***************/ typedef struct simdata_gpu_task *simdata_gpu_task_t; -/** @brief GPU task datatype - @ingroup m_datatypes_management_details */ typedef struct m_gpu_task { char *name; /**< @brief task name if any */ simdata_gpu_task_t simdata; /**< @brief simulator data */ @@ -101,17 +90,17 @@ typedef struct m_gpu_task { } s_m_gpu_task_t; /** @brief GPU task datatype - @ingroup m_datatypes_management + @ingroup m_task_management A task may then be defined by a computing amount, a dispatch latency and a collect latency. \see m_task_management - @{ */ +*/ typedef struct m_gpu_task *m_gpu_task_t; /*************** End GPU ***************/ /** - * \brief @brief Communication action + * \brief @brief Communication action. * \ingroup m_datatypes_management * * Communication actions transfer tasks between processes. @@ -120,66 +109,34 @@ typedef struct m_gpu_task *m_gpu_task_t; typedef struct msg_comm *msg_comm_t; /** \brief Default value for an uninitialized #m_task_t. - \ingroup m_datatypes_management + \ingroup m_task_management */ #define MSG_TASK_UNINITIALIZED NULL -/** @} */ - /* ****************************** Process *********************************** */ -/** @brief Process datatype - @ingroup m_datatypes_management +/** @brief Process datatype. + @ingroup m_process_management - A process may be defined as a code, with some private - data, executing in a location. - \see m_process_management - @{ */ + A process may be defined as a code, with some + private data, executing in a location. + + You should not access directly to the fields of the pointed + structure, but always use the provided API to interact with + processes. + */ typedef struct s_smx_process *m_process_t; -/** @} */ #ifdef MSG_USE_DEPRECATED -/* ********************************* Channel ******************************** */ -/** @brief Channel datatype - @ingroup msg_deprecated_functions - - A channel is a number and identifies a mailbox type (just as a - port number does). - \see m_channel_management - @{ */ typedef int m_channel_t; -/** @} */ #endif /* ******************************** Mailbox ************************************ */ -typedef struct s_smx_rvpoint *msg_mailbox_t; /** @brief Mailbox datatype - @ingroup m_datatypes_management_details @{ */ - -void MSG_mailbox_free(void *mailbox); - - -/** @} */ - - -/* ***************************** Error handling ***************************** */ -/** @brief Error handling - @ingroup m_datatypes_management - @{ -*//* Keep these code as binary values: java bindings manipulate | of these values */ -typedef enum { - MSG_OK = 0, /**< @brief Everything is right. Keep on going this way ! */ - MSG_TIMEOUT = 1, /**< @brief nothing good happened before the timer you provided elapsed */ - MSG_TRANSFER_FAILURE = 2, /**< @brief There has been a problem during you task - transfer. Either the network is down or the remote host has been - shutdown. */ - MSG_HOST_FAILURE = 4, /**< @brief System shutdown. The host on which you are - running has just been rebooted. Free your datastructures and - return now !*/ - MSG_TASK_CANCELED = 8 /**< @brief Canceled task. This task has been canceled by somebody!*/ -} MSG_error_t; -/** @} */ + @ingroup m_datatypes_management + */ +typedef struct s_smx_rvpoint *msg_mailbox_t; SG_END_DECL() diff --git a/include/msg/msg.h b/include/msg/msg.h index c1c2d1d0e9..4dccee2737 100644 --- a/include/msg/msg.h +++ b/include/msg/msg.h @@ -14,6 +14,23 @@ SG_BEGIN_DECL() +/** @brief Return code of most MSG functions + @ingroup msg_simulation + @{ */ +/* Keep these code as binary values: java bindings manipulate | of these values */ +typedef enum { + MSG_OK = 0, /**< @brief Everything is right. Keep on going this way ! */ + MSG_TIMEOUT = 1, /**< @brief nothing good happened before the timer you provided elapsed */ + MSG_TRANSFER_FAILURE = 2, /**< @brief There has been a problem during you task + transfer. Either the network is down or the remote host has been + shutdown. */ + MSG_HOST_FAILURE = 4, /**< @brief System shutdown. The host on which you are + running has just been rebooted. Free your datastructures and + return now !*/ + MSG_TASK_CANCELED = 8 /**< @brief Canceled task. This task has been canceled by somebody!*/ +} MSG_error_t; +/** @} */ + /************************** Global ******************************************/ XBT_PUBLIC(void) MSG_config(const char *name, ...); diff --git a/src/msg/msg_mailbox.h b/src/msg/msg_mailbox.h index 5ec804bf0a..cdfe0e6ab0 100644 --- a/src/msg/msg_mailbox.h +++ b/src/msg/msg_mailbox.h @@ -4,8 +4,8 @@ /* This program is free software; you can redistribute it and/or modify it * under the terms of the license (GNU LGPL) which comes with this package. */ -#ifndef SMX_MAILBOX_H -#define SMX_MAILBOX_H +#ifndef MSG_MAILBOX_H +#define MSG_MAILBOX_H #include "xbt/fifo.h" #include "simix/simix.h" @@ -27,6 +27,8 @@ SG_BEGIN_DECL() XBT_PUBLIC(msg_mailbox_t) MSG_mailbox_new(const char *alias); +void MSG_mailbox_free(void *mailbox); + /* \brief MSG_mailbox_free - release a mailbox from the memory. * * The function MSG_mailbox_free release a mailbox from the memory but does @@ -111,4 +113,4 @@ XBT_PUBLIC(msg_mailbox_t) #endif SG_END_DECL() -#endif /* !SMX_MAILBOX_H */ +#endif /* !MSG_MAILBOX_H */