commit: r294 - trunk/docs

Author: jonathan
Date: 2006-02-16 14:21:53 -0500 (Thu, 16 Feb 2006)
New Revision: 294

Modified:
   trunk/docs/SP_receive.3
Log:
Update SP_receive to correctly explain the contents of the message body during
a membership change.


Modified: trunk/docs/SP_receive.3
===================================================================
--- trunk/docs/SP_receive.3	2006-02-16 14:07:13 UTC (rev 293)
+++ trunk/docs/SP_receive.3	2006-02-16 19:21:53 UTC (rev 294)
@@ -206,49 +206,80 @@
 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 together 
 from the old group membership into this new membership. The data buffer will include
-the following fields:
+the 
+.I group_id, 
+.I num_vs_sets,
+.I local_vs_set_offset
+and a list of 
+.I vs_sets.
 
+The location of the beginning of each field is provided by the accessor functions. Since
+the layout of the membership message can change between versions, these functions should
+always be used to extract data from the message body. 
+Each accessor function gives the byte offset in the message body of the corresponding
+field. 
+
 .RS
 .TP
-.B group_id;
+.B SP_get_gid_offset_memb_mess()
 .br
 .TP
-.B int32u num_vs_sets
+.B SP_get_num_vs_sets_offset_memb_mess()
 .br
 .TP
-.B int32u local_vs_set_offset 
+.B SP_get_first_vs_set_offset_memb_mess()
 .br
 .TP
-.B list of vs_sets
+.B SP_get_offset_to_local_vs_set_offset()
 .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_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. 
+These four functions provide the location in the message body of the corresponding value. 
+These locations returned as offsets in bytes from the beginning of the body.
 
-Each vs_set is defined as:
+To get the actual byte location of the specific local vs_set for the application who received the
+message, the functions
 
 .RS
 .TP
-.B int32u num_vs_members
+.B SP_get_local_vs_set_offset_memb_mess( char *reg_memb_mess )
 .br
 .TP
-.B char members[][MAX_GROUP_NAME];
+.B SP_get_local_vs_set_offset_memb_scat( const scatter *reg_memb_scat )
 .RE
 
+are provided. They each 
+provide the byte offset to the beginning of the specific vs_set
+that the application receiving the message is in. The first function is used if the message was 
+received into a contigous message buffer, the second if a scatter structure was used to receive
+the message. 
+
+So if an application wants only to know about it's 
+own vs_set (identical to the information Spread provided prior to version 4) then this offset 
+can be used to find just that specific vs_set, which can then be accessed through the vs_set 
+functions below. 
+
+Each vs_set is defined as a number of members and a character array of the members names. The type
+for the array is
+.I char members[][MAX_GROUP_NAME].
+
 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
+.RS
+.TP
+.B SP_get_vs_set_size_offset_vs_set()
+.br
+.TP
+.B SP_get_vs_set_members_offset_vs_set()
+.RE
 
-The offsets returned by these functions are relative to the beginning of the vs_set, not the beginning
-of the message data field. 
+The offsets returned by these functions are relative to the beginning of the specific vs_set, 
+not the beginning of the message data field. 
 
+Each membership message may contain a number of vs_sets, as when a network merge occurs, several different
+partitions could be merging at the same time, with each partition having it's own set of members who came
+together between the old and new memberships. All of the vs_sets are stored continuously in the membership messages body, so after reading one vs_set, the next vs_set begins at the next byte. Each vs_set starts with
+the num_vs_members value so that the application can determine the length of the members array to read. 
+
 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:
@@ -256,22 +287,21 @@
 .RS
 .TP 0.8i
 .B CAUSED_BY_JOIN:
-Vs_set contains the private group of the joining process.
+vs_set contains the private group of the joining process.
 .TP
 .B CAUSED_BY_LEAVE:
-Vs_set contains the private group of the leaving process.
+vs_set contains the private group of the leaving process.
 .TP
 .B CAUSED_BY_DISCONNECT:
-Vs_set contains the private group of the disconnecting process.
+vs_set contains the private group of the disconnecting process.
 .TP
 .B CAUSED_BY_NETWORK:
-Vs_set contains the group names of the members of the new membership who came 
-with 
-.B me
-(the current process) to the new membership. Of course, all 
-.B new 
-members can be determined by comparing it with the groups parameter of
-the SP_receive call.
+vs_set contains the group names of the members of the new membership who came 
+together  
+to the new membership. For each set of members who came together an additional
+vs_set will exist. The vs_set containing the local application private group name
+will contain those members who came with 
+.B me.
 .RE
 
 If this is a MEMB_MESSAGE (i.e. membership message) and it is