cruft/doc/gras-docs.sgml

   1 <?xml version="1.0"?>
   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" [
   4
   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">
   8
   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">
  12
  13
  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">
  22
  23 <!ENTITY surf-maxmin SYSTEM "xml/surf_maxmin.xml">
  24
  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">
  29
  30 <!ENTITY overview SYSTEM "overview.xml">
  31 <!ENTITY faq SYSTEM "faq.xml">
  32 ]>
  33 <book id="index">
  34   <bookinfo>
  35     <title>Grid Reality And Simulation Reference Manual</title>
  36   </bookinfo>
  37
  38   <chapter>
  39     <title>GRAS overview</title>
  40     &overview;
  41     &faq;
  42   </chapter>
  43
  44   <chapter>
  45    <title>Communication facilities</title>
  46     &comm-datadesc;
  47     &comm-socks;
  48     &comm-messages;
  49   </chapter>
  50
  51   <chapter>
  52    <title>Virtualization</title>
  53     &virtu-globals;
  54     &virtu-syscall;
  55 <!--    &virtu-fs;-->
  56   </chapter>
  57
  58 <!--
  59 =head2 Sending (or receiving) dynamic sized arrays
  60
  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
  66 sections.
  67
  68 =head1 Describing hosts
  69
  70 Before any GRAS communication, you have to do some initialization work. For
  71 that, use the GRAS_EstablishHost() function.
  72
  73  GRAS_EstablishHost(char **addresses,
  74                     unsigned int addressesCount,
  75                     unsigned short port,
  76                     void (*initFunction)(void),
  77                     int (*exitFunction)(void),
  78                     unsigned int serveEvery,
  79                     GRAS_host_t *hostdescriptor);
  80
  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
  86 descriptor.
  87
  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
  90 it's not state-less.
  91
  92 =head1 Preparing to accept incomming messages
  93
  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.
  98
  99  int
 100  GRAS_IncomingSocket(unsigned short startingPort,
 101                      unsigned short endingPort,
 102                      GRAS_Socket_t *sd,
 103                      unsigned short *socketPort);
 104
 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.
 109
 110 =head1 Sending messages
 111
 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.
 114
 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.
 118
 119 In fact, an outgoing socket is nothing more than an address to remote socket
 120 openned in listing mode.
 121
 122  int
 123  GRAS_OutgoingSocket(char *host,
 124                      unsigned short port,
 125                      GRAS_Socket_t *sd);
 126
 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.
 129
 130  int
 131  GRAS_SendMessage(GRAS_Socket_t *sd,
 132                   double timeOut,
 133                   MessageType message,
 134                   int sequence_count ,
 135                   ...);
 136
 137
 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:
 141
 142                   size_t howMany,
 143                   const DataDescriptor *description,
 144                   const void *data
 145
 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>.
 149
 150 This function is blocking until the message is actually sent, and you must
 151 free the data when you're done with it.
 152
 153 =head1 Receiving messages
 154
 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
 157 incoming messages :
 158
 159 =over
 160
 161 =item default callback
 162
 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>).
 169
 170  typedef void (*GRAS_ListenerFunction)(GRAS_Socket_t *from,
 171                                        void *userdata,
 172                                        int sequence_count,
 173                                        va_args va);
 174
 175  void
 176  GRAS_RegisterListener (int message,const char *name,
 177                         GRAS_ListenFunction listener);
 178
 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:
 183
 184                   size_t howMany,
 185                   const DataDescriptor *description,
 186                   const void *data
 187
 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.
 190
 191 =item Actually waiting for data
 192
 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.
 200
 201  int
 202  GRAS_RecvMessage(GRAS_Socket_t *sd,
 203                   double timeOut,
 204                   MessageType message,
 205                   int *sequence_count,
 206                   ...);
 207
 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:
 211
 212                   size_t *howMany,
 213                   const DataDescriptor **description,
 214                   const void **data
 215
 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.
 218
 219 The C<data> fields are allocated by the GRAS_RecvMessage, and must be freed
 220 by user after use.
 221
 222 =item one-way callback
 223
 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...
 234
 235  void
 236  GRAS_RegisterOneWayListener (int message,const char *name,
 237                               GRAS_ListenerFunction listener);
 238
 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.
 242
 243 =back
 244
 245 =head1 Handling computation
 246
 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>.
 250
 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).
 255
 256  GRAS_computation_if_RL(size) {
 257    code to execute when running in RL;
 258  } else {
 259    code to execute when running in SG;
 260  }
 261
 262 If running RL, this macro will be rewritten to
 263
 264   if (1)
 265
 266 and if running SG, this macro will be rewritten to
 267
 268   if (<code to simulate the task>, 0)
 269
 270 =head1 Conclusion
 271
 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
 275 needed.
 276
 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.
 280
 281 =head1 TODO
 282
 283 =over
 284
 285 =item
 286
 287 Make sure this proposal is more or less flawless. That's a RFC ;)
 288
 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.
 291
 292 =item
 293
 294 Implement this.
 295
 296 In RL, it should pretty straightforward, since GRAS functions are more or
 297 less wrappers to the NWS communication library.
 298
 299 In SG, it shouldn't be that difficult either ;)
 300
 301 =item
 302
 303 Write examples.
 304   </chapter>
 305 -->
 306
 307   <chapter>
 308    <title>GRAS toolbox</title>
 309    &xbt-error;
 310    &xbt-log;
 311    &xbt-dynar;
 312    &xbt-dict;
 313    &xbt-set;
 314    &xbt-swag;
 315    &xbt-heap;
 316    &xbt-config;
 317   </chapter>
 318
 319   <chapter>
 320    <title>SURF</title>
 321    &surf-maxmin;
 322   </chapter>
 323
 324 <!--
 325   <chapter>
 326     <title>GRAS implementation</title>
 327     &gras-gras-private;
 328     &gras-gras-rl;
 329     &gras-gras-sg;
 330   </chapter>
 331 -->
 332 </book>