Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Adapt to lastest changes in dict: Create dicts before use
[simgrid.git] / include / messages.h
1 /* $Id$ */
2
3 /* gras/messages.h - Public interface to GRAS messages                      */
4
5 /* Authors: Martin Quinson                                                  */
6 /* Copyright (C) 2003,2004 Martin Quinson.                                  */
7
8 /* This program is free software; you can redistribute it and/or modify it
9    under the terms of the license (GNU LGPL) which comes with this package. */
10
11
12 #ifndef GRAS_MSG_H
13 #define GRAS_MSG_H
14
15 #include <stddef.h>    /* offsetof() */
16 #include <sys/types.h>  /* size_t */
17 #include <stdarg.h>
18
19
20 /*! C++ users need love */
21 #ifndef BEGIN_DECL
22 # ifdef __cplusplus
23 #  define BEGIN_DECL extern "C" {
24 # else
25 #  define BEGIN_DECL 
26 # endif
27 #endif
28
29 /*! C++ users need love */
30 #ifndef END_DECL
31 # ifdef __cplusplus
32 #  define END_DECL }
33 # else
34 #  define END_DECL 
35 # endif
36 #endif
37 /* End of cruft for C++ */
38
39 BEGIN_DECL
40
41 typedef unsigned int gras_msgid_t;
42 typedef struct gras_msgheader_s gras_msgheader_t;
43 typedef struct gras_msgentry_s  gras_msgentry_t;
44
45 /**
46  * A message sent or received to/from the network
47  *
48  * Do not mess with the content of this structure. Only access it through the following functions:
49  * @gras_msg_new() or @gras_msg_copy() to create such struct.
50  * @gras_msg_free() to get ride of it.
51  * @gras_msg_ctn() to read its content.
52  *
53  */
54 typedef struct {
55   /* public */
56   gras_sock_t *sock; /** the socket on which the message was received (to answer) */
57
58   /* private */
59   gras_msgheader_t *header;
60   gras_msgentry_t *entry;
61   unsigned int *dataCount;
62   void **data; 
63   e_gras_free_directive_t freeDirective;
64 } gras_msg_t;
65
66 /**
67  * gras_msgtype_register:
68  * @msgId: identificator of such messages
69  * @name: name as it should be used for logging messages
70  * @sequence_count: number of groups in variadics
71  * @Varargs: List of (const DataDescriptor *, int DDcount), describing the 
72  *  elements in each sequence (DDlength is the length of the corresponding 
73  *  DataDescriptor).
74  * @Returns: the error code (or no_error).
75  *
76  * Registers a message to the GRAS mecanism.
77  */
78 gras_error_t
79 gras_msgtype_register(gras_msgid_t msgId,
80                       const char *name,
81                       int sequence_count,
82                       ...);
83
84 /**
85  * gras_msg_new_and_send:
86  * @sd: Socket on which the message should be sent
87  * @msgId: identificator this messages
88  * @Varargs: List of (void **data, int seqLen) forming the payload of the message.
89  *  The number of sequences is given by the registration of ht
90  * @Returns: the error code (or no_error).
91  *
92  * Create a new message, and send it on the network through the given socket.
93  */
94 gras_error_t
95 gras_msg_new_and_send(gras_sock_t *sd,
96                       gras_msgid_t msgId,
97                       int seqCount,
98                       ...);
99
100
101 /**
102  * gras_msg_new:
103  * @msgId: identificator this messages
104  * @free_data_on_free: boolean indicating wheater the data must be freed when the msg get freed.
105  * @seqCount: number of sequences in this message (must be the same than the value 
106  *  registered using gras_msgtype_register() for that msgId)
107  * @Varargs: List of (void **data, int seqLen) forming the payload of the message.
108  *  The number of sequences is given by the registration of ht
109  * @Returns: the message built or NULL on error
110  *
111  * Build a message to be sent
112  */
113
114 gras_msg_t *gras_msg_new(gras_msgid_t msgId,
115                          e_gras_free_directive_t free_data_on_free,
116                          int seqCount,
117                          ...);
118
119 /**
120  * gras_msg_new_va:
121  *
122  * Build a new message in the exact same way than gras_msg_new(), but taking its arguments as 
123  * variadic ones.
124  */
125 gras_msg_t *gras_msg_new_va(gras_msgid_t msgId,
126                         e_gras_free_directive_t free_data,
127                         int seqCount,
128                         va_list ap);
129
130 /**
131  * gras_msg_copy:
132  * @msg: original to copy. 
133  *
134  * Copy a message.
135  */
136
137 gras_msg_t *gras_msg_copy(gras_msg_t *msg);
138
139 /**
140  * gras_msg_free:
141  * @msg: poor guy going to diediedie.
142  *
143  * Free a msg built with gras_msg_new().
144  */
145 void gras_msg_free(gras_msg_t *msg);
146
147 /**
148  * gras_msg_ctn:
149  * @msg: the carrier of the data
150  * @sequence: Sequence in which you want to see the data.
151  * @num: Number in this sequence of the element to access.
152  * @type: type of the element to access.
153  *
154  * Access to the content of a message.
155  */
156 #define gras_msg_ctn(msg,sequence,num,type) \
157   ((type *)msg->data[sequence])[num]
158
159 /**
160  * gras_cb_t:
161  * @msg: The message itself
162  * @Returns: true if the message was accepted by the callback and false if it should be passed to the next one.
163  *
164  * Type of message callback functions. Once a such a function is registered to 
165  * handle messages of a given type with RegisterCallback(), it will be called 
166  * each time such a message incomes.
167  *
168  * If the callback accepts the message, it should free it after use.
169  */
170
171 typedef int (*gras_cb_t)(gras_msg_t *msg);
172
173 /**
174  * gras_cb_register:
175  * @message: id of the concerned messages
176  * @TTL: How many time should this callback be used
177  * @cb: The callback.
178  * @Returns: the error code (or no_error).
179  *
180  * Indicates a desire that the function #cb# be called whenever a
181  * #message# message comes in.  
182  * #TTL# is how many time this callback should be used. After that, this 
183  * callback will be unregistred. If <0, the callback will never be unregistered.
184  * (ie, it will be permanent)
185  */
186 gras_error_t
187 gras_cb_register(gras_msgid_t message,
188                  int TTL,
189                  gras_cb_t cb);
190
191 /**
192  * gras_msg_handle:
193  * @timeOut: How long to wait for incoming messages
194  * @Returns: the error code (or no_error).
195  *
196  * Waits up to #timeOut# seconds to see if a message comes in; if so, calls the
197  * registered listener for that message (see RegisterCallback()).
198  */
199 gras_error_t gras_msg_handle(double timeOut);
200
201
202 /**
203  * gras_msg_send:
204  * @sd: Socket to write on
205  * @msg: to send (build it with @gras_msg_new())
206  * @freeDirective: if the msg passed as argument should be gras_msg_free'ed after sending.
207  * @Returns: the error code (or no_error).
208  *
209  * Sends the message on the socket sd using an automatic and adaptative timeout.
210  */
211
212 gras_error_t
213 gras_msg_send(gras_sock_t *sd,
214               gras_msg_t *msg,
215               e_gras_free_directive_t freeDirective);
216
217 /**
218  * gras_msg_wait:
219  * @timeout: How long should we wait for this message.
220  * @id: id of awaited msg
221  * @message: where to store the message when it comes.
222  * @Returns: the error code (or no_error).
223  *
224  * Waits for a message to come in over a given socket.
225  *
226  * Every message of another type received before the one waited will be queued
227  * and used by subsequent call to this function or MsgHandle().
228  */
229 gras_error_t
230 gras_msg_wait(double timeout,
231               gras_msgid_t id,
232               gras_msg_t **message);
233
234
235 END_DECL
236
237 #endif /* GRAS_MSG_H */
238