New function to have a finer control on what kind of message you're disposed to wait

[simgrid.git] / include / gras / messages.h

diff --git a/include/gras/messages.h b/include/gras/messages.h
index 8158b0b..bb6e5b1 100644 (file)
--- a/include/gras/messages.h
+++ b/include/gras/messages.h
@@ -15,11 +15,16 @@
 #include "gras/transport.h"
 #include "gras/datadesc.h"
 
-BEGIN_DECL()
+SG_BEGIN_DECL()
 
 /** @addtogroup GRAS_msg
  *  @brief Defining messages and callbacks, and exchanging messages (Communication facility) 
  * 
+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]
+ *                <tr><td><b>Prev</b>   <td> [\ref GRAS_sock]
+ *                <tr><td><b>Next</b>   <td> [\ref GRAS_timer]
+ *                <tr><td><b>Down</b>   <td> [\ref GRAS_msg_decl]            </table></center>
+ *
  *  There is two way to receive messages in GRAS. The first one is to
  *  register a given function as callback to a given type of messages (see
  *  \ref gras_cb_register and associated section). But you can also
@@ -33,12 +38,15 @@ BEGIN_DECL()
  *  passed to the callback.
  * 
  *  For an example of use, please refer to \ref GRAS_ex_ping.
- * 
- *  @{
  */
 
-/** @name 1. Message declaration and retrival 
+/** @defgroup GRAS_msg_decl Message declaration and retrival 
+ *  @ingroup  GRAS_msg
  *  
+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_msg]
+ *                <tr><td>   Prev       <td> 
+ *                <tr><td><b>Next</b>   <td> [\ref GRAS_msg_cb]               </table></center>
+ *
  *  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 
  *  \ref gras_datadesc_ref_generic).
@@ -62,10 +70,16 @@ typedef struct s_gras_msgtype *gras_msgtype_t;
 
   gras_msgtype_t gras_msgtype_by_name (const char *name);
   gras_msgtype_t gras_msgtype_by_namev(const char *name, short int version);
+  gras_msgtype_t gras_msgtype_by_id(int id);
 
 /** @} */  
-/** @name 2. Callback declaration and use
+/** @defgroup GRAS_msg_cb Callback declaration and use
+ *  @ingroup  GRAS_msg
  * 
+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_msg]
+ *                <tr><td><b>Prev</b>   <td> [\ref GRAS_msg_decl]
+ *                <tr><td><b>Next</b>   <td> [\ref GRAS_msg_exchange]       </table></center>
+ *
  * This is how to register a given function so that it gets called when a
  * given type of message arrives.
  * 
@@ -100,21 +114,36 @@ typedef struct s_gras_msgtype *gras_msgtype_t;
   void gras_cb_unregister(gras_msgtype_t msgtype, gras_msg_cb_t cb);
 
 /** @} */  
-/** @name 3. Message exchange */
+/** @defgroup GRAS_msg_exchange Message exchange 
+ *  @ingroup  GRAS_msg
+ *
+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_msg]
+ *                <tr><td><b>Prev</b>   <td> [\ref GRAS_msg_cb]
+ *                <tr><td>   Next       <td>                        </table></center>
+ */
 /** @{ */
 
-  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);
+  void gras_msg_send(gras_socket_t   sock,
+                    gras_msgtype_t  msgtype,
+                    void           *payload);
+  void gras_msg_wait(double          timeout,    
+                    gras_msgtype_t  msgt_want,
+                    gras_socket_t  *expeditor,
+                    void           *payload);
+  void gras_msg_wait_ext(double           timeout,    
+                        gras_msgtype_t   msgt_want,
+                        gras_socket_t    expe_want,
+                        int_f_pvoid_pvoid_t payl_filter,
+                        void               *filter_ctx, 
+                        gras_msgtype_t  *msgt_got,
+                        gras_socket_t   *expe_got,
+                        void            *payl_got);
+
+  void gras_msg_handle(double timeOut);
 
 /* @} */
 
-END_DECL()
+SG_END_DECL()
 
 #endif /* GRAS_MSG_H */