cruft/doc/tmpl/DataDesc.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 DataDescriptor API
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Describing the data
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>In order to allow GRAS to send data over the network (or simply to
   9 dupplicate it in SG), you have to describe the structure of data attached
  10 with each message. This mecanism is stolen from NWS message passing
  11 interface.</para>
  12
  13 <para>For each message, you have to declare a structure representing the
  14 data to send as payload with the message.</para>
  15
  16 <refsect2>
  17   <title>Sending (or receiving) simple structures</title>
  18   <para>Let's imagin you want to declare a <command>STORE_STATE</command>
  19   message, which will send some data to the memory server for inclusion in
  20   the database. Here is the structure we want to send:</para>
  21
  22 <literallayout>
  23  struct state {
  24   char id[STATE_NAME_SIZE];
  25   int rec_size;
  26   int rec_count;
  27   double seq_no;
  28   double time_out;
  29  };
  30 </literallayout>
  31
  32   <para>And here is the structure description GRAS needs to be able to send
  33   this over the network:</para>
  34
  35 <literallayout>
  36  const static DataDescriptor stateDescriptor[] =
  37   {SIMPLE_MEMBER(CHAR_TYPE, STATE_NAME_SIZE, offsetof(struct state, id)),
  38    SIMPLE_MEMBER(INT_TYPE, 1, offsetof(struct state, rec_size)),
  39    SIMPLE_MEMBER(INT_TYPE, 1, offsetof(struct state, rec_count)),
  40    SIMPLE_MEMBER(DOUBLE_TYPE, 1, offsetof(struct state, seq_no)),
  41    SIMPLE_MEMBER(DOUBLE_TYPE, 1, offsetof(struct state, time_out))};
  42 </literallayout>
  43
  44   <para>Contrary to what one could think when you first see it, it's pretty
  45   easy. A structure descriptor is a list of descriptions, describing each
  46   field of the structure. For example, for the first field, you say that
  47   the base type is <command>CHAR_TYPE</command>, that there is
  48   <command>STATE_NAME_SIZE</command> element of this type and that it's
  49   position in the structure is computed by <command>offsetof(struct state,
  50   id)</command>. This leads to two remarks:</para>
  51
  52   <itemizedlist>
  53     <listitem>
  54       <para>it's impossible to send dynamic sized strings that way. It's a
  55       known limitation, but I think we can live with it.</para>
  56     </listitem>
  57     <listitem>
  58       <para>Yes, the <command>offsetof(struct state, id)</command>
  59       construction is C ANSI and is portable.</para>
  60     </listitem>
  61   </itemizedlist>
  62 </refsect2>
  63
  64 <refsect2>
  65   <title>Sending (or receiving) complex structure</title>
  66   <para>How to send non-flat structures, do you ask? It's not harder. Let's
  67   imagin you want to send the following structure:</para>
  68
  69 <literallayout>
  70  typedef struct {
  71    unsigned long address;
  72    unsigned long port;
  73  } CliqueMember;
  74
  75  typedef struct {
  76    char name[MAX_CLIQUE_NAME_SIZE];
  77    double whenGenerated;
  78    double instance;
  79    char skill[MAX_SKILL_SIZE];
  80    char options[MAX_OPTIONS_SIZE];
  81    double period;
  82    double timeOut;
  83    CliqueMember members[MAX_MEMBERS];
  84    unsigned int count;
  85    unsigned int leader;
  86  } Clique;
  87 </literallayout>
  88
  89   <para>As you can see, this structure contains an array of another user
  90   defined structure. To be able to send <command>struct Clique</command>,
  91   you have to describe each structures that way:</para>
  92
  93 <literallayout>
  94  static const DataDescriptor cliqueMemberDescriptor[] =
  95    {SIMPLE_MEMBER(UNSIGNED_LONG_TYPE, 1, offsetof(CliqueMember, address)),
  96     SIMPLE_MEMBER(UNSIGNED_LONG_TYPE, 1, offsetof(CliqueMember, port))};
  97
  98  static const DataDescriptor cliqueDescriptor[] =
  99    {SIMPLE_MEMBER(CHAR_TYPE, MAX_CLIQUE_NAME_SIZE, offsetof(Clique, name)),
 100     SIMPLE_MEMBER(DOUBLE_TYPE, 1, offsetof(Clique, whenGenerated)),
 101     SIMPLE_MEMBER(DOUBLE_TYPE, 1, offsetof(Clique, instance)),
 102     SIMPLE_MEMBER(CHAR_TYPE, MAX_SKILL_SIZE, offsetof(Clique, skill)),
 103     SIMPLE_MEMBER(CHAR_TYPE, MAX_OPTIONS_SIZE, offsetof(Clique, options)),
 104     SIMPLE_MEMBER(DOUBLE_TYPE, 1, offsetof(Clique, period)),
 105     SIMPLE_MEMBER(DOUBLE_TYPE, 1, offsetof(Clique, timeOut)),
 106     {STRUCT_TYPE, MAX_MEMBERS, offsetof(Clique, members),
 107      (DataDescriptor *)&amp;cliqueMemberDescriptor, cliqueMemberDescriptorLength,
 108      PAD_BYTES(CliqueMember, port, unsigned long, 1)},
 109     SIMPLE_MEMBER(UNSIGNED_INT_TYPE, 1, offsetof(Clique, count)),
 110     SIMPLE_MEMBER(UNSIGNED_INT_TYPE, 1, offsetof(Clique, leader))};
 111 </literallayout>
 112
 113   <para>So, even if less natural, it is possible to send structures
 114   containing structures with these tools.</para>
 115
 116   <para>You can see that it's not only impossible to send dynamic-sized
 117   strings, it impossible to send dynamic-sized arrays. Here,
 118   <command>MAX_MEMBERS</command> is the maximum of members a clique can
 119   contain. In NWS, this value is defined to 100.  <warning><para>I'm not
 120   sure, but I think that all the 100 values are sent each time, even if
 121   there is only 3 non-null members. Yes, that's
 122   bad.</para></warning></para>
 123
 124   <warning><para>The DataDescriptor_t MUST be const. Malloc'ing them and
 125   then casting them on argument passing IS NOT OK. This is because we get
 126   the number of elements in the array with the sizeof(dd)/sizeof(dd[0]).
 127   </para></warning>
 128 </refsect2>
 129
 130 <!-- ##### SECTION See_Also ##### -->
 131 <para>
 132
 133 </para>
 134
 135 <!-- ##### ENUM DataTypes ##### -->
 136 <para>
 137
 138 </para>
 139
 140 @CHAR_TYPE:
 141 @DOUBLE_TYPE:
 142 @FLOAT_TYPE:
 143 @INT_TYPE:
 144 @LONG_TYPE:
 145 @SHORT_TYPE:
 146 @UNSIGNED_INT_TYPE:
 147 @UNSIGNED_LONG_TYPE:
 148 @UNSIGNED_SHORT_TYPE:
 149 @STRUCT_TYPE:
 150
 151 <!-- ##### MACRO SIMPLE_DATA ##### -->
 152 <para>
 153
 154 </para>
 155
 156 @type:
 157 @repetitions:
 158
 159
 160 <!-- ##### MACRO SIMPLE_MEMBER ##### -->
 161 <para>
 162
 163 </para>
 164
 165 @type:
 166 @repetitions:
 167 @offset:
 168
 169
 170 <!-- ##### MACRO PAD_BYTES ##### -->
 171 <para>
 172
 173 </para>
 174
 175 @structType:
 176 @lastMember:
 177 @memberType:
 178 @repetitions:
 179
 180