2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
5 <!ENTITY comm-socks SYSTEM "xml/comm_socks.xml">
6 <!ENTITY comm-datadesc SYSTEM "xml/comm_datadesc.xml">
7 <!ENTITY comm-messages SYSTEM "xml/comm_messages.xml">
9 <!ENTITY virtu-globals SYSTEM "xml/virtu_globals.xml">
10 <!ENTITY virtu-syscall SYSTEM "xml/virtu_syscall.xml">
11 <!ENTITY virtu-fs SYSTEM "xml/virtu_fs.xml">
14 <!ENTITY xbt-error SYSTEM "xml/xbt_error.xml">
15 <!ENTITY xbt-log SYSTEM "xml/xbt_log.xml">
16 <!ENTITY xbt-dynar SYSTEM "xml/xbt_dynar.xml">
17 <!ENTITY xbt-dict SYSTEM "xml/xbt_dict.xml">
18 <!ENTITY xbt-set SYSTEM "xml/xbt_set.xml">
19 <!ENTITY xbt-swag SYSTEM "xml/xbt_swag.xml">
20 <!ENTITY xbt-heap SYSTEM "xml/xbt_heap.xml">
21 <!ENTITY xbt-config SYSTEM "xml/xbt_config.xml">
23 <!ENTITY surf-maxmin SYSTEM "xml/surf_maxmin.xml">
25 <!ENTITY gras-gras SYSTEM "xml/gras.xml">
26 <!ENTITY gras-gras-private SYSTEM "xml/gras_private.xml">
27 <!ENTITY gras-gras-rl SYSTEM "xml/gras_rl.xml">
28 <!ENTITY gras-gras-sg SYSTEM "xml/gras_sg.xml">
30 <!ENTITY overview SYSTEM "overview.xml">
31 <!ENTITY faq SYSTEM "faq.xml">
35 <title>Grid Reality And Simulation Reference Manual</title>
39 <title>GRAS overview</title>
45 <title>Communication facilities</title>
52 <title>Virtualization</title>
59 =head2 Sending (or receiving) dynamic sized arrays
61 To overcome the impossibility to send structure having dynamic-sized array,
62 it is possible to send several times the same structures, the number of time
63 being given in the header. The idea here is to say that we want to send a
64 C<STORE_STATE> message containing not one C<struct state> to store, but for
65 example three different C<state>s. We will come back on this in the next
68 =head1 Describing hosts
70 Before any GRAS communication, you have to do some initialization work. For
71 that, use the GRAS_EstablishHost() function.
73 GRAS_EstablishHost(char **addresses,
74 unsigned int addressesCount,
76 void (*initFunction)(void),
77 int (*exitFunction)(void),
78 unsigned int serveEvery,
79 GRAS_host_t *hostdescriptor);
81 It takes as argument the name (or IP) of the host on which you want to
82 establish this host (in RL, you may want to pass a list of all IP addresses
83 served by this host), the port on which it will listen by default, the init
84 and exit functions, how often (in millisecond) it will try to handle the
85 incoming requests and returns a descriptor to the newly created host
88 The init function is supposed to return to a userdata, which will be passed
89 to all functions, and which should contain the I<state> of your server, if
92 =head1 Preparing to accept incomming messages
94 To be able to accept any incomming messages, you have first to open a socket
95 in listening mode. For that, simply use the GRAS_IncomingSocket(). In RL,
96 GRAS try to bind() to the socket, and then accept(). In SG, it tries to lock
97 the given channel. Here is the prototype of this function.
100 GRAS_IncomingSocket(unsigned short startingPort,
101 unsigned short endingPort,
103 unsigned short *socketPort);
105 It tries to open an incoming socket on a port between C<startingPort> and
106 C<endingPort>, returns the created C<socket> and the C<socketPort> on which we
107 managed to create this socket. The return value of the function is true if we
108 managed to create it, and false if not.
110 =head1 Sending messages
112 Sending data is pretty simple. First, you have to create a outgoing socket,
113 and then use it as argument to the GRAS_SendMessage*() function.
115 GRAS_OutgoingSocket() can be used to build a new outgoing socket.
116 Alternatively, you can pass a reference to a Socket you know using
117 C<socketDescriptor> and C<socketDescriptorLength> in messages.
119 In fact, an outgoing socket is nothing more than an address to remote socket
120 openned in listing mode.
123 GRAS_OutgoingSocket(char *host,
127 Once you have a reference to the peer with which you want to communicate,
128 sending messages is as easy as using the GRAS_SendMessage() function.
131 GRAS_SendMessage(GRAS_Socket_t *sd,
138 C<GRAS_SendMessage> allows you to send a message with several sequence of
139 structures as payload. For each sequence, you have to pass three extra
140 arguments to the function. The prototype of those arguments would be:
143 const DataDescriptor *description,
146 This allows you to specify that the given sequence is a C<howMany>-long
147 array of structure described by C<description>, and stored at the memory
148 location pointed by C<data>.
150 This function is blocking until the message is actually sent, and you must
151 free the data when you're done with it.
153 =head1 Receiving messages
155 GRAS_IncomingSocket() prepared the host to receive messages, but did not
156 explain how to handle incoming messages. There is 3 kinds of handling to
161 =item default callback
163 you can register default callbacks to well known messages which will always
164 be handled the same way. This is for example used in the NWS memory server
165 to handle C<STORE_STATE> messages by actually writing the state on disk. For
166 that, use the function GRAS_RegisterListener() to register the function
167 C<listener> as listener to message type C<message> (which name to use in
168 debugging messages is C<name>).
170 typedef void (*GRAS_ListenerFunction)(GRAS_Socket_t *from,
176 GRAS_RegisterListener (int message,const char *name,
177 GRAS_ListenFunction listener);
179 The C<va> argument passed to the listener function is the pending of the
180 extra args passed to the GRAS_SendMessage function. That is to say that it
181 will contain C<sequence_count> sequence of data, each of them being
182 described by three arguments:
185 const DataDescriptor *description,
188 The data are allocated by GRAS for you when the message incomes, but must be
189 freed by you after use in the listener function.
191 =item Actually waiting for data
193 You can also ask to receive the next message of a given type. For example,
194 the sensor sending data to the memory using the C<STORE_STATE> message will
195 wait for an answer of the memory (which will use a C<STORED_STATE> to
196 indicate if the operation was successfull or not). For that, use the
197 GRAS_RecvMessage() function. If the next message to be received is not of
198 the waited type, this message is queued until we get the message we expect,
199 and handled afterward.
202 GRAS_RecvMessage(GRAS_Socket_t *sd,
208 Like always, sequence count is set to the number of sequences in the
209 message's payload, and the extra arguments should describe each sequence.
210 Their prototype will be:
213 const DataDescriptor **description,
216 Note that there is a level of indirection more than in previous functions,
217 since their values will be set by the GRAS_RecvMessage() function.
219 The C<data> fields are allocated by the GRAS_RecvMessage, and must be freed
222 =item one-way callback
224 As you can see, calling GRAS_RecvMessage() is blocking for that host in that
225 sense that no other messages can be server until the expected message is
226 received. To avoid that problem, it is possible to declare I<one-way
227 callback>. As GRAS_RecvMessage(), this is to be used when you wait for the
228 answer of a peer, but when you don't want to block on this. The handling of
229 the message (or of the associated timeout) have to be moved to another
230 function, which will be passed as callback to the expected message. This
231 allows GRAS to handle other incoming messages before the answer to the
232 request comes and improve the reactivity of code. Sadly, this makes the code
233 quite difficult to read and maintain...
236 GRAS_RegisterOneWayListener (int message,const char *name,
237 GRAS_ListenerFunction listener);
239 If you do several calls to this function for the same message, callbacks are
240 stacked, and their use will pop this stack. It is possible to use this
241 function to interceipt messages having a default callback.
245 =head1 Handling computation
247 SG is a simulator, and you when you simulate a computationnal server, you
248 don't want to see him actually doing the computation, rather, you want to
249 see this work I<simulated>.
251 For that, use the GRAS_computation() macro. If running in RL, the provided
252 code will actually be done, and if running SG, a task of the provided
253 C<size> will be scheduled on the host (and the computation done will be the
254 one passed in the else branch).
256 GRAS_computation_if_RL(size) {
257 code to execute when running in RL;
259 code to execute when running in SG;
262 If running RL, this macro will be rewritten to
266 and if running SG, this macro will be rewritten to
268 if (<code to simulate the task>, 0)
272 We belive that the sort of raw RPC we presented here permits to run the same
273 code both in RL and SG because GRAS will do the unpleasant job of moving
274 data from one namespace to another if needed, sending it over the network if
277 GRAS Agents never really define the main function. The main function you
278 write in your code does only call to GRAS_EstablishHost(), which is in
279 charge of initializing the GRAS mecanism on the right hosts.
287 Make sure this proposal is more or less flawless. That's a RFC ;)
289 We could go one step further on the main() problem, by using the SG scenario
290 files, and a way to actuate it in RL.
296 In RL, it should pretty straightforward, since GRAS functions are more or
297 less wrappers to the NWS communication library.
299 In SG, it shouldn't be that difficult either ;)
308 <title>GRAS toolbox</title>
326 <title>GRAS implementation</title>