[Spread-cvs] commit: r293 - trunk/docs

[jonathan at spread.org]

Author: jonathan
Date: 2006-02-16 09:07:13 -0500 (Thu, 16 Feb 2006)
New Revision: 293

Modified:
   trunk/docs/SP_receive.3
Log:
Update man page with new vs set strucures delivered with membership messages.


Modified: trunk/docs/SP_receive.3
===================================================================
--- trunk/docs/SP_receive.3	2006-02-15 01:28:26 UTC (rev 292)
+++ trunk/docs/SP_receive.3	2006-02-16 14:07:13 UTC (rev 293)
@@ -145,11 +145,21 @@
 .I endian_mismatch
 field will be zero since the transitional does not have any endian issues. The
 .I mess
-field will be left empty.
-So in essence the only information you get is the 
+field contains only the group id of the group for which the transitional
+message applies. So the layout of the message body is
+
+.RS
+.TP
+.B group_id;
+.RE
+
+
+So in essence the only information you get is about what group the signal applies to which 
+is provided by the 
 .I sender
-field is 
-set to the group name which received a transitional membership change. The importance
+field and the group_id value.
+
+The importance
 of the TRANS_MEMB_MESS is that it tells the application that all messages received
 after it and before the REG_MEMB_MESS for the same group are 'clean up' messages to
 put the messages in a consistant state before actually changing memberships.  For more
@@ -188,10 +198,13 @@
 .B new
 membership.  This list of names is always in the same order at all receipients
 and thus can be used to deterministically pick a group representative if
-one is needed by the application.
+one is needed by the application. The actual ordering has changed with different
+versions of Spread, but is currently ordered first by the daemon the member is
+connected to and then by their private name. The ordering of the daemons is the
+same as the order they are listed in the spread.conf file. 
 
 The second set of information is stored in the message body and provides a list
-of all the private group names of those processes which came with your process
+of all the private group names of those processes which came together 
 from the old group membership into this new membership. The data buffer will include
 the following fields:
 
@@ -200,21 +213,44 @@
 .B group_id;
 .br
 .TP
-.B int num_vs_members;
+.B int32u num_vs_sets
 .br
 .TP
-.B char vs_set[][MAX_GROUP_NAME];
+.B int32u local_vs_set_offset 
+.br
+.TP
+.B list of vs_sets
 .RE
 
 The location of the beginning of each field is provided by the accessor functions
 .B SP_get_gid_offset_memb_mess,
-.B SP_get_num_vs_offset_memb_mess, and
-.B SP_get_vs_set_offset_memb_mess.
+.B SP_get_num_vs_sets_offset_memb_mess,
+.B SP_get_offset_to_local_vs_set_offset, and
+.B SP_get_first_vs_set_offset_memb_mess.
 Each accessor function gives the byte offset in the message body of the corresponding
 field. 
 
-The vs_set array will have num_vs_members group names, each of which is
-a fixed length string.  The content of the vs_set array is dependent 
+Each vs_set is defined as:
+
+.RS
+.TP
+.B int32u num_vs_members
+.br
+.TP
+.B char members[][MAX_GROUP_NAME];
+.RE
+
+For each vs_set the locations of the num_vs_members field and the members array can be found
+by using the accessor functions
+.B SP_get_vs_set_size_offset_vs_set
+and 
+.B SP_get_vs_set_members_offset_vs_set
+
+The offsets returned by these functions are relative to the beginning of the vs_set, not the beginning
+of the message data field. 
+
+The vs_set members array will have num_vs_members group names, each of which is
+a fixed length string.  The content of the vs_set members array is dependent 
 upon the type of the membership change:
 
 .RS