+++ /dev/null
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
-
-<!ENTITY comm-socks SYSTEM "sgml/comm_socks.sgml">
-<!ENTITY comm-datadesc SYSTEM "sgml/comm_datadesc.sgml">
-<!ENTITY comm-dd-expert SYSTEM "sgml/comm_datadesc_expert.sgml">
-<!ENTITY comm-messages SYSTEM "sgml/comm_messages.sgml">
-
-<!ENTITY virtu-globals SYSTEM "sgml/virtu_globals.sgml">
-<!ENTITY virtu-syscall SYSTEM "sgml/virtu_syscall.sgml">
-<!ENTITY virtu-fs SYSTEM "sgml/virtu_fs.sgml">
-
-
-<!ENTITY tbx-err SYSTEM "sgml/tbx_err.sgml">
-<!ENTITY tbx-log SYSTEM "sgml/tbx_log.sgml">
-<!ENTITY tbx-dynar SYSTEM "sgml/tbx_dynar.sgml">
-<!ENTITY tbx-dico SYSTEM "sgml/tbx_dico.sgml">
-<!ENTITY tbx-set SYSTEM "sgml/tbx_set.sgml">
-<!ENTITY tbx-cfg SYSTEM "sgml/tbx_cfg.sgml">
-
-<!ENTITY gras-gras SYSTEM "sgml/gras.sgml">
-<!ENTITY gras-gras-private SYSTEM "sgml/gras_private.sgml">
-<!ENTITY gras-gras-rl SYSTEM "sgml/gras_rl.sgml">
-<!ENTITY gras-gras-sg SYSTEM "sgml/gras_sg.sgml">
-
-<!ENTITY overview SYSTEM "overview.sgml">
-]>
-<book id="index">
- <bookinfo>
- <title>Grid Reality And Simulation Reference Manual</title>
- </bookinfo>
-
- <chapter>
- <title>GRAS overview</title>
- &overview;
- </chapter>
-
- <chapter>
- <title>Communication facilities</title>
- &comm-datadesc;
- &comm-dd-expert;
- &comm-socks;
- &comm-messages;
- </chapter>
-
- <chapter>
- <title>Virtualization</title>
- &virtu-globals;
- &virtu-syscall;
-<!-- &virtu-fs;-->
- </chapter>
-
-<!--
-=head2 Sending (or receiving) dynamic sized arrays
-
-To overcome the impossibility to send structure having dynamic-sized array,
-it is possible to send several times the same structures, the number of time
-being given in the header. The idea here is to say that we want to send a
-C<STORE_STATE> message containing not one C<struct state> to store, but for
-example three different C<state>s. We will come back on this in the next
-sections.
-
-=head1 Describing hosts
-
-Before any GRAS communication, you have to do some initialization work. For
-that, use the GRAS_EstablishHost() function.
-
- GRAS_EstablishHost(char **addresses,
- unsigned int addressesCount,
- unsigned short port,
- void (*initFunction)(void),
- int (*exitFunction)(void),
- unsigned int serveEvery,
- GRAS_host_t *hostdescriptor);
-
-It takes as argument the name (or IP) of the host on which you want to
-establish this host (in RL, you may want to pass a list of all IP addresses
-served by this host), the port on which it will listen by default, the init
-and exit functions, how often (in millisecond) it will try to handle the
-incoming requests and returns a descriptor to the newly created host
-descriptor.
-
-The init function is supposed to return to a userdata, which will be passed
-to all functions, and which should contain the I<state> of your server, if
-it's not state-less.
-
-=head1 Preparing to accept incomming messages
-
-To be able to accept any incomming messages, you have first to open a socket
-in listening mode. For that, simply use the GRAS_IncomingSocket(). In RL,
-GRAS try to bind() to the socket, and then accept(). In SG, it tries to lock
-the given channel. Here is the prototype of this function.
-
- int
- GRAS_IncomingSocket(unsigned short startingPort,
- unsigned short endingPort,
- GRAS_Socket_t *sd,
- unsigned short *socketPort);
-
-It tries to open an incoming socket on a port between C<startingPort> and
-C<endingPort>, returns the created C<socket> and the C<socketPort> on which we
-managed to create this socket. The return value of the function is true if we
-managed to create it, and false if not.
-
-=head1 Sending messages
-
-Sending data is pretty simple. First, you have to create a outgoing socket,
-and then use it as argument to the GRAS_SendMessage*() function.
-
-GRAS_OutgoingSocket() can be used to build a new outgoing socket.
-Alternatively, you can pass a reference to a Socket you know using
-C<socketDescriptor> and C<socketDescriptorLength> in messages.
-
-In fact, an outgoing socket is nothing more than an address to remote socket
-openned in listing mode.
-
- int
- GRAS_OutgoingSocket(char *host,
- unsigned short port,
- GRAS_Socket_t *sd);
-
-Once you have a reference to the peer with which you want to communicate,
-sending messages is as easy as using the GRAS_SendMessage() function.
-
- int
- GRAS_SendMessage(GRAS_Socket_t *sd,
- double timeOut,
- MessageType message,
- int sequence_count ,
- ...);
-
-
-C<GRAS_SendMessage> allows you to send a message with several sequence of
-structures as payload. For each sequence, you have to pass three extra
-arguments to the function. The prototype of those arguments would be:
-
- size_t howMany,
- const DataDescriptor *description,
- const void *data
-
-This allows you to specify that the given sequence is a C<howMany>-long
-array of structure described by C<description>, and stored at the memory
-location pointed by C<data>.
-
-This function is blocking until the message is actually sent, and you must
-free the data when you're done with it.
-
-=head1 Receiving messages
-
-GRAS_IncomingSocket() prepared the host to receive messages, but did not
-explain how to handle incoming messages. There is 3 kinds of handling to
-incoming messages :
-
-=over
-
-=item default callback
-
-you can register default callbacks to well known messages which will always
-be handled the same way. This is for example used in the NWS memory server
-to handle C<STORE_STATE> messages by actually writing the state on disk. For
-that, use the function GRAS_RegisterListener() to register the function
-C<listener> as listener to message type C<message> (which name to use in
-debugging messages is C<name>).
-
- typedef void (*GRAS_ListenerFunction)(GRAS_Socket_t *from,
- void *userdata,
- int sequence_count,
- va_args va);
-
- void
- GRAS_RegisterListener (int message,const char *name,
- GRAS_ListenFunction listener);
-
-The C<va> argument passed to the listener function is the pending of the
-extra args passed to the GRAS_SendMessage function. That is to say that it
-will contain C<sequence_count> sequence of data, each of them being
-described by three arguments:
-
- size_t howMany,
- const DataDescriptor *description,
- const void *data
-
-The data are allocated by GRAS for you when the message incomes, but must be
-freed by you after use in the listener function.
-
-=item Actually waiting for data
-
-You can also ask to receive the next message of a given type. For example,
-the sensor sending data to the memory using the C<STORE_STATE> message will
-wait for an answer of the memory (which will use a C<STORED_STATE> to
-indicate if the operation was successfull or not). For that, use the
-GRAS_RecvMessage() function. If the next message to be received is not of
-the waited type, this message is queued until we get the message we expect,
-and handled afterward.
-
- int
- GRAS_RecvMessage(GRAS_Socket_t *sd,
- double timeOut,
- MessageType message,
- int *sequence_count,
- ...);
-
-Like always, sequence count is set to the number of sequences in the
-message's payload, and the extra arguments should describe each sequence.
-Their prototype will be:
-
- size_t *howMany,
- const DataDescriptor **description,
- const void **data
-
-Note that there is a level of indirection more than in previous functions,
-since their values will be set by the GRAS_RecvMessage() function.
-
-The C<data> fields are allocated by the GRAS_RecvMessage, and must be freed
-by user after use.
-
-=item one-way callback
-
-As you can see, calling GRAS_RecvMessage() is blocking for that host in that
-sense that no other messages can be server until the expected message is
-received. To avoid that problem, it is possible to declare I<one-way
-callback>. As GRAS_RecvMessage(), this is to be used when you wait for the
-answer of a peer, but when you don't want to block on this. The handling of
-the message (or of the associated timeout) have to be moved to another
-function, which will be passed as callback to the expected message. This
-allows GRAS to handle other incoming messages before the answer to the
-request comes and improve the reactivity of code. Sadly, this makes the code
-quite difficult to read and maintain...
-
- void
- GRAS_RegisterOneWayListener (int message,const char *name,
- GRAS_ListenerFunction listener);
-
-If you do several calls to this function for the same message, callbacks are
-stacked, and their use will pop this stack. It is possible to use this
-function to interceipt messages having a default callback.
-
-=back
-
-=head1 Handling computation
-
-SG is a simulator, and you when you simulate a computationnal server, you
-don't want to see him actually doing the computation, rather, you want to
-see this work I<simulated>.
-
-For that, use the GRAS_computation() macro. If running in RL, the provided
-code will actually be done, and if running SG, a task of the provided
-C<size> will be scheduled on the host (and the computation done will be the
-one passed in the else branch).
-
- GRAS_computation_if_RL(size) {
- code to execute when running in RL;
- } else {
- code to execute when running in SG;
- }
-
-If running RL, this macro will be rewritten to
-
- if (1)
-
-and if running SG, this macro will be rewritten to
-
- if (<code to simulate the task>, 0)
-
-=head1 Conclusion
-
-We belive that the sort of raw RPC we presented here permits to run the same
-code both in RL and SG because GRAS will do the unpleasant job of moving
-data from one namespace to another if needed, sending it over the network if
-needed.
-
-GRAS Agents never really define the main function. The main function you
-write in your code does only call to GRAS_EstablishHost(), which is in
-charge of initializing the GRAS mecanism on the right hosts.
-
-=head1 TODO
-
-=over
-
-=item
-
-Make sure this proposal is more or less flawless. That's a RFC ;)
-
-We could go one step further on the main() problem, by using the SG scenario
-files, and a way to actuate it in RL.
-
-=item
-
-Implement this.
-
-In RL, it should pretty straightforward, since GRAS functions are more or
-less wrappers to the NWS communication library.
-
-In SG, it shouldn't be that difficult either ;)
-
-=item
-
-Write examples.
--->
- </chapter>
-
- <chapter>
- <title>GRAS toolbox</title>
- &tbx-err;
- &tbx-log;
- &tbx-dynar;
- &tbx-dico;
- &tbx-set;
- &tbx-cfg;
- </chapter>
-
-<!--
- <chapter>
- <title>GRAS implementation</title>
- &gras-gras-private;
- &gras-gras-rl;
- &gras-gras-sg;
- </chapter>
--->
-</book>
