Reorganization, additions

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

diff --git a/cruft/doc/tmpl/DataDesc.sgml b/cruft/doc/tmpl/DataDesc.sgml
deleted file mode 100644 (file)
index 1dd8f0f..0000000
--- a/cruft/doc/tmpl/DataDesc.sgml
+++ /dev/null
@@ -1,180 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-DataDescriptor API
-
-<!-- ##### SECTION Short_Description ##### -->
-Describing the data
-
-<!-- ##### SECTION 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 See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### 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: 
-
-<!-- ##### MACRO SIMPLE_DATA ##### -->
-<para>
-
-</para>
-
-@type: 
-@repetitions: 
-
-
-<!-- ##### MACRO SIMPLE_MEMBER ##### -->
-<para>
-
-</para>
-
-@type: 
-@repetitions: 
-@offset: 
-
-
-<!-- ##### MACRO PAD_BYTES ##### -->
-<para>
-
-</para>
-
-@structType: 
-@lastMember: 
-@memberType: 
-@repetitions: 
-
-

diff --git a/cruft/doc/tmpl/comm_datadesc.sgml b/cruft/doc/tmpl/comm_datadesc.sgml
new file mode 100644 (file)
index 0000000..cf9fb92
--- /dev/null
+++ b/cruft/doc/tmpl/comm_datadesc.sgml
@@ -0,0 +1,144 @@
+<!-- ##### SECTION Title ##### -->
+Data description
+
+<!-- ##### SECTION Short_Description ##### -->
+Simple ways to describe data to exchange
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### FUNCTION gras_datadesc_from_nws ##### -->
+<para>
+
+</para>
+
+@desc: 
+@howmany: 
+@dst: 
+@Returns: 
+<!-- # Unused Parameters # -->
+@name: 
+@code: 
+
+
+<!-- ##### FUNCTION gras_datadesc_parse ##### -->
+<para>
+
+</para>
+
+@def: 
+@dst: 
+@Returns: 
+<!-- # Unused Parameters # -->
+@name: 
+@Cdefinition: 
+@code: 
+
+
+<!-- ##### MACRO gras_datadesc_declare_array ##### -->
+<para>
+
+</para>
+
+@name: 
+@elm_type: 
+@size: 
+@code: 
+
+
+<!-- ##### MACRO gras_datadesc_declare_array_dyn ##### -->
+<para>
+
+</para>
+
+@name: 
+@elm_type: 
+@dynamic_size: 
+@code: 
+
+
+<!-- ##### MACRO gras_datadesc_declare_ref ##### -->
+<para>
+
+</para>
+
+@name: 
+@ref_type: 
+@code: 
+
+
+<!-- ##### MACRO gras_datadesc_declare_ref_disc ##### -->
+<para>
+
+</para>
+
+@name: 
+@discriminant: 
+@code: 
+
+
+<!-- ##### MACRO gras_datadesc_declare_struct ##### -->
+<para>
+
+</para>
+
+@name: 
+@code: 
+
+
+<!-- ##### MACRO gras_datadesc_declare_struct_add_code ##### -->
+<para>
+
+</para>
+
+@struct_code: 
+@field_name: 
+@field_type_code: 
+
+
+<!-- ##### MACRO gras_datadesc_declare_struct_add_name ##### -->
+<para>
+
+</para>
+
+@struct_code: 
+@field_name: 
+@field_type_name: 
+
+
+<!-- ##### MACRO gras_datadesc_declare_union ##### -->
+<para>
+
+</para>
+
+@name: 
+@code: 
+
+
+<!-- ##### MACRO gras_datadesc_declare_union_add_code ##### -->
+<para>
+
+</para>
+
+@union_code: 
+@field_name: 
+@field_type_code: 
+
+
+<!-- ##### MACRO gras_datadesc_declare_union_add_name ##### -->
+<para>
+
+</para>
+
+@union_code: 
+@field_name: 
+@field_type_name: 
+
+

diff --git a/cruft/doc/tmpl/comm_datadesc_expert.sgml b/cruft/doc/tmpl/comm_datadesc_expert.sgml
new file mode 100644 (file)
index 0000000..14e6a15
--- /dev/null
+++ b/cruft/doc/tmpl/comm_datadesc_expert.sgml
@@ -0,0 +1,177 @@
+<!-- ##### SECTION Title ##### -->
+Advanced Data description
+
+<!-- ##### SECTION Short_Description ##### -->
+Advanced ways to describe data (for experts)
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### FUNCTION gras_datadesc_declare_array_cb ##### -->
+<para>
+
+</para>
+
+@name: 
+@element_type: 
+@fixed_size: 
+@dynamic_size: 
+@post: 
+@code: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gras_datadesc_declare_ref_cb ##### -->
+<para>
+
+</para>
+
+@name: 
+@referenced_type: 
+@discriminant: 
+@post: 
+@code: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gras_datadesc_declare_struct_add_code_cb ##### -->
+<para>
+
+</para>
+
+@struct_code: 
+@field_name: 
+@field_code: 
+@pre_cb: 
+@post_cb: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gras_datadesc_declare_struct_add_name_cb ##### -->
+<para>
+
+</para>
+
+@struct_code: 
+@field_name: 
+@field_type_name: 
+@pre_cb: 
+@post_cb: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gras_datadesc_declare_struct_cb ##### -->
+<para>
+
+</para>
+
+@name: 
+@pre_cb: 
+@post_cb: 
+@code: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gras_datadesc_declare_union_add_code_cb ##### -->
+<para>
+
+</para>
+
+@union_code: 
+@field_name: 
+@field_code: 
+@pre_cb: 
+@post_cb: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gras_datadesc_declare_union_add_name_cb ##### -->
+<para>
+
+</para>
+
+@union_code: 
+@field_name: 
+@field_type_name: 
+@pre_cb: 
+@post_cb: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gras_datadesc_declare_union_cb ##### -->
+<para>
+
+</para>
+
+@name: 
+@field_count: 
+@post: 
+@code: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gras_dd_cbps_block_begin ##### -->
+<para>
+
+</para>
+
+@ps: 
+
+
+<!-- ##### FUNCTION gras_dd_cbps_block_end ##### -->
+<para>
+
+</para>
+
+@ps: 
+
+
+<!-- ##### FUNCTION gras_dd_cbps_get ##### -->
+<para>
+
+</para>
+
+@ps: 
+@name: 
+@ddt: 
+
+
+<!-- ##### FUNCTION gras_dd_cbps_pop ##### -->
+<para>
+
+</para>
+
+@ps: 
+@name: 
+@ddt: 
+
+
+<!-- ##### FUNCTION gras_dd_cbps_push ##### -->
+<para>
+
+</para>
+
+@ps: 
+@name: 
+@data: 
+@ddt: 
+
+
+<!-- ##### FUNCTION gras_dd_cbps_set ##### -->
+<para>
+
+</para>
+
+@ps: 
+@name: 
+@data: 
+@ddt: 
+
+

diff --git a/cruft/doc/tmpl/comm_dd_cbps.sgml b/cruft/doc/tmpl/comm_dd_cbps.sgml
new file mode 100644 (file)
index 0000000..7093c85
--- /dev/null
+++ b/cruft/doc/tmpl/comm_dd_cbps.sgml
@@ -0,0 +1,74 @@
+<!-- ##### SECTION Title ##### -->
+Data description callbacks persistant state
+
+<!-- ##### SECTION Short_Description ##### -->
+
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### FUNCTION gras_dd_cbps_block_begin ##### -->
+<para>
+
+</para>
+
+@ps: 
+
+
+<!-- ##### FUNCTION gras_dd_cbps_block_end ##### -->
+<para>
+
+</para>
+
+@ps: 
+
+
+<!-- ##### FUNCTION gras_dd_cbps_get ##### -->
+<para>
+
+</para>
+
+@ps: 
+@name: 
+@ddt: 
+
+
+<!-- ##### FUNCTION gras_dd_cbps_pop ##### -->
+<para>
+
+</para>
+
+@ps: 
+@name: 
+@ddt: 
+
+
+<!-- ##### FUNCTION gras_dd_cbps_push ##### -->
+<para>
+
+</para>
+
+@ps: 
+@name: 
+@data: 
+@ddt: 
+
+
+<!-- ##### FUNCTION gras_dd_cbps_set ##### -->
+<para>
+
+</para>
+
+@ps: 
+@name: 
+@data: 
+@ddt: 
+
+