From: mquinson <mquinson@48e7efb5-ca39-0410-a469-dd3cf9ba447f>
Date: Tue, 6 Apr 2004 22:00:22 +0000 (+0000)
Subject: ignorable changes (?)
X-Git-Tag: v3.3~5280
X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/60c3ee0101748158fb267e81969d322f54e36ee5

ignorable changes (?)


git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@66 48e7efb5-ca39-0410-a469-dd3cf9ba447f
---

diff --git a/cruft/doc/tmpl/gras-unused.sgml b/cruft/doc/tmpl/gras-unused.sgml
index 870fad03a8..0fa4acbfbc 100644
--- a/cruft/doc/tmpl/gras-unused.sgml
+++ b/cruft/doc/tmpl/gras-unused.sgml
@@ -1,3 +1,141 @@
+<!-- ##### SECTION ./tmpl/DataDesc.sgml:Long_Description ##### -->
+<para>In order to allow GRAS to send data over the network (or simply to
+dupplicate it in SG), you have to describe the structure of data attached
+with each message. This mecanism is stolen from NWS message passing
+interface.</para>
+
+<para>For each message, you have to declare a structure representing the
+data to send as payload with the message.</para>
+
+<refsect2>
+  <title>Sending (or receiving) simple structures</title>
+  <para>Let's imagin you want to declare a <command>STORE_STATE</command>
+  message, which will send some data to the memory server for inclusion in
+  the database. Here is the structure we want to send:</para>
+
+<literallayout>
+ struct state {
+  char id[STATE_NAME_SIZE];
+  int rec_size;
+  int rec_count;
+  double seq_no;
+  double time_out;
+ };
+</literallayout>
+
+  <para>And here is the structure description GRAS needs to be able to send
+  this over the network:</para>
+
+<literallayout>
+ const static DataDescriptor stateDescriptor[] =
+  {SIMPLE_MEMBER(CHAR_TYPE, STATE_NAME_SIZE, offsetof(struct state, id)),
+   SIMPLE_MEMBER(INT_TYPE, 1, offsetof(struct state, rec_size)),
+   SIMPLE_MEMBER(INT_TYPE, 1, offsetof(struct state, rec_count)),
+   SIMPLE_MEMBER(DOUBLE_TYPE, 1, offsetof(struct state, seq_no)),
+   SIMPLE_MEMBER(DOUBLE_TYPE, 1, offsetof(struct state, time_out))};
+</literallayout>
+
+  <para>Contrary to what one could think when you first see it, it's pretty
+  easy. A structure descriptor is a list of descriptions, describing each
+  field of the structure. For example, for the first field, you say that
+  the base type is <command>CHAR_TYPE</command>, that there is
+  <command>STATE_NAME_SIZE</command> element of this type and that it's
+  position in the structure is computed by <command>offsetof(struct state,
+  id)</command>. This leads to two remarks:</para> 
+
+  <itemizedlist>
+    <listitem>
+      <para>it's impossible to send dynamic sized strings that way. It's a
+      known limitation, but I think we can live with it.</para>
+    </listitem>
+    <listitem>
+      <para>Yes, the <command>offsetof(struct state, id)</command>
+      construction is C ANSI and is portable.</para>
+    </listitem>
+  </itemizedlist>
+</refsect2>
+
+<refsect2>
+  <title>Sending (or receiving) complex structure</title>
+  <para>How to send non-flat structures, do you ask? It's not harder. Let's
+  imagin you want to send the following structure:</para>
+
+<literallayout>
+ typedef struct {
+   unsigned long address;
+   unsigned long port;
+ } CliqueMember;
+
+ typedef struct {
+   char name[MAX_CLIQUE_NAME_SIZE];
+   double whenGenerated;
+   double instance;
+   char skill[MAX_SKILL_SIZE];
+   char options[MAX_OPTIONS_SIZE];
+   double period;
+   double timeOut;
+   CliqueMember members[MAX_MEMBERS];
+   unsigned int count;
+   unsigned int leader;
+ } Clique;
+</literallayout>
+
+  <para>As you can see, this structure contains an array of another user
+  defined structure. To be able to send <command>struct Clique</command>,
+  you have to describe each structures that way:</para>
+
+<literallayout>
+ static const DataDescriptor cliqueMemberDescriptor[] =
+   {SIMPLE_MEMBER(UNSIGNED_LONG_TYPE, 1, offsetof(CliqueMember, address)),
+    SIMPLE_MEMBER(UNSIGNED_LONG_TYPE, 1, offsetof(CliqueMember, port))};
+
+ static const DataDescriptor cliqueDescriptor[] =
+   {SIMPLE_MEMBER(CHAR_TYPE, MAX_CLIQUE_NAME_SIZE, offsetof(Clique, name)),
+    SIMPLE_MEMBER(DOUBLE_TYPE, 1, offsetof(Clique, whenGenerated)),
+    SIMPLE_MEMBER(DOUBLE_TYPE, 1, offsetof(Clique, instance)),
+    SIMPLE_MEMBER(CHAR_TYPE, MAX_SKILL_SIZE, offsetof(Clique, skill)),
+    SIMPLE_MEMBER(CHAR_TYPE, MAX_OPTIONS_SIZE, offsetof(Clique, options)),
+    SIMPLE_MEMBER(DOUBLE_TYPE, 1, offsetof(Clique, period)),
+    SIMPLE_MEMBER(DOUBLE_TYPE, 1, offsetof(Clique, timeOut)),
+    {STRUCT_TYPE, MAX_MEMBERS, offsetof(Clique, members),
+     (DataDescriptor *)&amp;cliqueMemberDescriptor, cliqueMemberDescriptorLength,
+     PAD_BYTES(CliqueMember, port, unsigned long, 1)},
+    SIMPLE_MEMBER(UNSIGNED_INT_TYPE, 1, offsetof(Clique, count)),
+    SIMPLE_MEMBER(UNSIGNED_INT_TYPE, 1, offsetof(Clique, leader))};
+</literallayout>
+
+  <para>So, even if less natural, it is possible to send structures 
+  containing structures with these tools.</para>
+
+  <para>You can see that it's not only impossible to send dynamic-sized
+  strings, it impossible to send dynamic-sized arrays. Here,
+  <command>MAX_MEMBERS</command> is the maximum of members a clique can
+  contain. In NWS, this value is defined to 100.  <warning><para>I'm not
+  sure, but I think that all the 100 values are sent each time, even if
+  there is only 3 non-null members. Yes, that's
+  bad.</para></warning></para>
+
+  <warning><para>The DataDescriptor_t MUST be const. Malloc'ing them and
+  then casting them on argument passing IS NOT OK. This is because we get
+  the number of elements in the array with the sizeof(dd)/sizeof(dd[0]).
+  </para></warning>
+</refsect2>
+
+
+<!-- ##### SECTION ./tmpl/DataDesc.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/DataDesc.sgml:Short_Description ##### -->
+Describing the data
+
+
+<!-- ##### SECTION ./tmpl/DataDesc.sgml:Title ##### -->
+DataDescriptor API
+
+
 <!-- ##### SECTION ./tmpl/ErrLog.sgml:Long_Description ##### -->
 <para>
 
@@ -18,6 +156,46 @@
 ErrLog
 
 
+<!-- ##### SECTION ./tmpl/Socks.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/Socks.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/Socks.sgml:Short_Description ##### -->
+Handling sockets
+
+
+<!-- ##### SECTION ./tmpl/Socks.sgml:Title ##### -->
+Sockets API
+
+
+<!-- ##### SECTION ./tmpl/comm_dd_cbps.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/comm_dd_cbps.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/comm_dd_cbps.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/comm_dd_cbps.sgml:Title ##### -->
+Data description callbacks persistant state
+
+
 <!-- ##### SECTION ./tmpl/config.sgml:Long_Description ##### -->
 <para>
 
@@ -38,6 +216,26 @@ ErrLog
 config
 
 
+<!-- ##### SECTION ./tmpl/dd_cbps.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/dd_cbps.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/dd_cbps.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/dd_cbps.sgml:Title ##### -->
+Data description callbacks persistant state
+
+
 <!-- ##### SECTION ./tmpl/dico.sgml:Long_Description ##### -->
 <para>
 
@@ -190,6 +388,26 @@ gras
 nws_comm
 
 
+<!-- ##### SECTION ./tmpl/trp_socks.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/trp_socks.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/trp_socks.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/trp_socks.sgml:Title ##### -->
+Sockets
+
+
 <!-- ##### MACRO BEGIN_DECL ##### -->
 <para>
 
@@ -600,6 +818,15 @@ nws_comm
 @timeOut: 
 @Returns: 
 
+<!-- ##### FUNCTION CloseSocket ##### -->
+<para>
+
+</para>
+
+@sock: 
+@waitForPeer: 
+@Returns: 
+
 <!-- ##### FUNCTION CreateLocalChild ##### -->
 <para>
 
@@ -618,6 +845,33 @@ nws_comm
 @sock: 
 @Returns: 
 
+<!-- ##### FUNCTION DataSize ##### -->
+<para>
+
+</para>
+
+@description: 
+@length: 
+@format: 
+@Returns: 
+
+<!-- ##### ENUM DataTypes ##### -->
+<para>
+
+</para>
+
+@CHAR_TYPE: 
+@DOUBLE_TYPE: 
+@FLOAT_TYPE: 
+@INT_TYPE: 
+@LONG_TYPE: 
+@SHORT_TYPE: 
+@UNSIGNED_INT_TYPE: 
+@UNSIGNED_LONG_TYPE: 
+@UNSIGNED_SHORT_TYPE: 
+@STRUCT_TYPE: 
+@LAST_TYPE: 
+
 <!-- ##### MACRO END_DECL ##### -->
 <para>
 
@@ -641,6 +895,14 @@ nws_comm
 @earPort: 
 @Returns: 
 
+<!-- ##### ENUM FormatTypes ##### -->
+<para>
+
+</para>
+
+@HOST_FORMAT: 
+@NETWORK_FORMAT: 
+
 <!-- ##### MACRO GRAS_LOG_MAYDAY ##### -->
 <para>
 
@@ -899,6 +1161,16 @@ nws_comm
 </para>
 
 
+<!-- ##### MACRO PAD_BYTES ##### -->
+<para>
+
+</para>
+
+@structType: 
+@lastMember: 
+@memberType: 
+@repetitions: 
+
 <!-- ##### FUNCTION PassSocket ##### -->
 <para>
 
@@ -932,6 +1204,23 @@ nws_comm
 @sd: 
 @Returns: 
 
+<!-- ##### MACRO SIMPLE_DATA ##### -->
+<para>
+
+</para>
+
+@type: 
+@repetitions: 
+
+<!-- ##### MACRO SIMPLE_MEMBER ##### -->
+<para>
+
+</para>
+
+@type: 
+@repetitions: 
+@offset: 
+
 <!-- ##### MACRO STDC_HEADERS ##### -->
 <para>
 
@@ -1274,6 +1563,15 @@ nws_comm
 
 @ud: 
 
+<!-- ##### FUNCTION gras_datadesc_copy_data ##### -->
+<para>
+
+</para>
+
+@dd: 
+@c: 
+@data: 
+
 <!-- ##### FUNCTION gras_dict_cursor_next ##### -->
 <para>
 
@@ -1301,6 +1599,13 @@ nws_comm
 @whereto: 
 @Returns: 
 
+<!-- ##### FUNCTION gras_lock ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
 <!-- ##### FUNCTION gras_log_parent_set ##### -->
 <para>
 
@@ -1317,3 +1622,54 @@ nws_comm
 @cat: 
 @thresholdPriority: 
 
+<!-- ##### FUNCTION gras_sock_client_open ##### -->
+<para>
+
+</para>
+
+@host: 
+@Param2: 
+@sock: 
+@Returns: 
+
+<!-- ##### FUNCTION gras_sock_close ##### -->
+<para>
+
+</para>
+
+@sock: 
+@Returns: 
+
+<!-- ##### FUNCTION gras_sock_get_peer_addr ##### -->
+<para>
+
+</para>
+
+@sd: 
+@Returns: 
+
+<!-- ##### FUNCTION gras_sock_get_peer_name ##### -->
+<para>
+
+</para>
+
+@sd: 
+@Returns: 
+
+<!-- ##### FUNCTION gras_sock_server_open ##### -->
+<para>
+
+</para>
+
+@Param1: 
+@Param2: 
+@sock: 
+@Returns: 
+
+<!-- ##### FUNCTION gras_unlock ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
diff --git a/cruft/doc/tmpl/gras_private.sgml b/cruft/doc/tmpl/gras_private.sgml
index 4803e61ef7..170da1192e 100644
--- a/cruft/doc/tmpl/gras_private.sgml
+++ b/cruft/doc/tmpl/gras_private.sgml
@@ -14,22 +14,6 @@ gras_private
 
 </para>
 
-<!-- ##### FUNCTION gras_lock ##### -->
-<para>
-
-</para>
-
-@Returns: 
-
-
-<!-- ##### FUNCTION gras_unlock ##### -->
-<para>
-
-</para>
-
-@Returns: 
-
-
 <!-- ##### FUNCTION gras_msg_discard ##### -->
 <para>
 
@@ -39,24 +23,19 @@ gras_private
 @size: 
 
 
-<!-- ##### ENUM FormatTypes ##### -->
-<para>
-
-</para>
-
-@HOST_FORMAT: 
-@NETWORK_FORMAT: 
-
 <!-- ##### FUNCTION gras_datadesc_cmp ##### -->
 <para>
 
 </para>
 
+@d1: 
+@d2: 
+@Returns: 
+<!-- # Unused Parameters # -->
 @dd1: 
 @c1: 
 @dd2: 
 @c2: 
-@Returns: 
 
 
 <!-- ##### MACRO SIMPLE_TYPE_COUNT ##### -->
diff --git a/cruft/doc/tmpl/gras_rl.sgml b/cruft/doc/tmpl/gras_rl.sgml
index b16aa9e989..65544a5c6c 100644
--- a/cruft/doc/tmpl/gras_rl.sgml
+++ b/cruft/doc/tmpl/gras_rl.sgml
@@ -38,17 +38,6 @@ Implementation of GRAS suited for real life.
 @sourceFormat: 
 
 
-<!-- ##### FUNCTION DataSize ##### -->
-<para>
-
-</para>
-
-@description: 
-@length: 
-@format: 
-@Returns: 
-
-
 <!-- ##### FUNCTION DifferentFormat ##### -->
 <para>
 
diff --git a/cruft/doc/tmpl/gras_sg.sgml b/cruft/doc/tmpl/gras_sg.sgml
index fe69bc5484..925dc0bd64 100644
--- a/cruft/doc/tmpl/gras_sg.sgml
+++ b/cruft/doc/tmpl/gras_sg.sgml
@@ -73,13 +73,3 @@ sgml-local-ecat-files:nil
 End:
 -->
 
-<!-- ##### FUNCTION CloseSocket ##### -->
-<para>
-
-</para>
-
-@sock: 
-@waitForPeer: 
-@Returns: 
-
-