X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/07db45c31602a15fae0e244e856f8a34b971686e..0ee6fdb41d9ba663184bdd4d48f79ef28a0e6fbb:/include/gras/messages.h

diff --git a/include/gras/messages.h b/include/gras/messages.h
index 1a025195c0..8158b0b90c 100644
--- a/include/gras/messages.h
+++ b/include/gras/messages.h
@@ -37,7 +37,7 @@ BEGIN_DECL()
  *  @{
  */
 
-/** @name Message declaration and retrival 
+/** @name 1. Message declaration and retrival 
  *  
  *  GRAS messages can only accept one type of payload. If you absolutely want to declare a message
  *  able to convey several datatypes, you can always say that it conveys a generic reference (see 
@@ -47,29 +47,24 @@ BEGIN_DECL()
  *  to add a version number to the message (by default, the version is set to 0). Any messages of the 
  *  wrong version will be ignored by the applications not providing any specific callback for them.
  *  
- *  This mecanism (stolen from the dynamic loader one) should ensure you to change the semantic of a given
+ *  This mechanism (stolen from the dynamic loader one) should ensure you to change the semantic of a given
  *  message while still understanding the old one.
  */
 /** @{ */  
 /** \brief Opaque type */
 typedef struct s_gras_msgtype *gras_msgtype_t;
 
-/** \brief declare a new message type of the given name. It only accepts the given datadesc as payload */
-void gras_msgtype_declare  (const char           *name,
-			    gras_datadesc_type_t  payload);
-/** \brief declare a new versionned message type of the given name and payload. */
-void gras_msgtype_declare_v(const char           *name,
-			    short int             version,
-			    gras_datadesc_type_t  payload);
-
-/** \brief retrive an existing message type from its name. */
-gras_msgtype_t gras_msgtype_by_name (const char     *name);
-/** \brief retrive an existing message type from its name and version number. */
-gras_msgtype_t gras_msgtype_by_namev(const char     *name,
-				     short int       version);
-/** @} */  
+  void gras_msgtype_declare  (const char           *name,
+			      gras_datadesc_type_t  payload);
+  void gras_msgtype_declare_v(const char           *name,
+			      short int             version,
+			      gras_datadesc_type_t  payload);
+
+  gras_msgtype_t gras_msgtype_by_name (const char *name);
+  gras_msgtype_t gras_msgtype_by_namev(const char *name, short int version);
 
-/** @name Callback declaration and use
+/** @} */  
+/** @name 2. Callback declaration and use
  * 
  * This is how to register a given function so that it gets called when a
  * given type of message arrives.
@@ -83,46 +78,41 @@ gras_msgtype_t gras_msgtype_by_namev(const char     *name,
  * @{
  */
  
-/** \brief Type of message callback functions. 
- * \param msg: The message itself
- * \return true if the message was consumed by the callback, false if the message was
- * refused by the callback (and should be passed to the next callback of the stack for
- * this message)
- *
- * Once a such a function is registered to handle messages of a given type with 
- * \ref gras_cb_register(), it will be called each time such a message arrives.
- *
- * If the callback accepts the message, it should free it after use.
- */
-typedef int (*gras_cb_t)(gras_socket_t  expeditor,
-			 void          *payload);
-/** \brief Bind the given callback to the given message type 
- *
- * Several callbacks can be attached to a given message type. The lastly added one will get the message first, and 
- * if it returns false, the message will be passed to the second one. 
- * And so on until one of the callbacks accepts the message.
- */
-void gras_cb_register  (gras_msgtype_t msgtype,
-			gras_cb_t      cb);
-/** \brief Unbind the given callback from the given message type */
-void gras_cb_unregister(gras_msgtype_t msgtype,
-			gras_cb_t      cb);
+  /** \brief Type of message callback functions. 
+   *
+   * \param expeditor: a socket to contact who sent this message
+   * \param payload: the message itself
+   *
+   * \return true if the message was consumed by the callback, 
+   *  false if the message was refused by the callback (and should be 
+   *  passed to the next callback of the stack for this message)
+   *
+   * Once a such a function is registered to handle messages of a given
+   * type with \ref gras_cb_register(), it will be called each time such
+   * a message arrives (unless a gras_msg_wait() intercepts it on arrival).
+   *
+   * If the callback accepts the message, it should free it after use.
+   */
+  typedef int (*gras_msg_cb_t)(gras_socket_t  expeditor,
+			       void          *payload);
+
+  void gras_cb_register  (gras_msgtype_t msgtype, gras_msg_cb_t cb);
+  void gras_cb_unregister(gras_msgtype_t msgtype, gras_msg_cb_t cb);
 
 /** @} */  
-/** @name Message exchange */
+/** @name 3. Message exchange */
 /** @{ */
-/** \brief Send the data pointed by \a payload as a message of type \a msgtype to the peer \a sock */
-xbt_error_t gras_msg_send(gras_socket_t   sock,
-			   gras_msgtype_t  msgtype,
-			   void           *payload);
-/** \brief Waits for a message to come in over a given socket. */
-xbt_error_t gras_msg_wait(double          timeout,    
-			   gras_msgtype_t  msgt_want,
-			   gras_socket_t  *expeditor,
-			   void           *payload);
-xbt_error_t gras_msg_handle(double timeOut);
-
-/*@}*/
+
+  xbt_error_t gras_msg_send(gras_socket_t   sock,
+			    gras_msgtype_t  msgtype,
+			    void           *payload);
+  xbt_error_t gras_msg_wait(double          timeout,    
+			    gras_msgtype_t  msgt_want,
+			    gras_socket_t  *expeditor,
+			    void           *payload);
+  xbt_error_t gras_msg_handle(double timeOut);
+
+/* @} */
 
 END_DECL()