[Spread-cvs] commit: r294 - trunk/docs
jonathan at spread.org
jonathan at spread.org
Thu Feb 16 14:21:53 EST 2006
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
More information about the Spread-cvs
mailing list