[Spread-cvs] commit: r319 - trunk/docs
jonathan at spread.org
jonathan at spread.org
Thu Mar 2 00:16:31 EST 2006
Author: jonathan
Date: 2006-03-02 00:16:31 -0500 (Thu, 02 Mar 2006)
New Revision: 319
Added:
trunk/docs/SP_get_memb_info.3
trunk/docs/SP_get_vs_set_members.3
trunk/docs/SP_get_vs_sets_info.3
trunk/docs/SP_scat_get_memb_info.3
trunk/docs/SP_scat_get_vs_set_members.3
trunk/docs/SP_scat_get_vs_sets_info.3
Removed:
trunk/docs/SP_get_first_vs_set_offset_memb_mess.3
trunk/docs/SP_get_gid_offset_memb_mess.3
trunk/docs/SP_get_local_vs_set_offset_memb_mess.3
trunk/docs/SP_get_local_vs_set_offset_memb_scat.3
trunk/docs/SP_get_num_vs_sets_offset_memb_mess.3
trunk/docs/SP_get_vs_set_members_offset_vs_set.3
trunk/docs/SP_get_vs_set_size_offset_vs_set.3
Modified:
trunk/docs/SP_receive.3
Log:
Update docs to describe new SP_get_memb_info, SP_get_vs_sets_info, and SP_get_vs_set_members
and their scatter varients. Remove docs for old functions that provided fixed offsets into the
membership body.
Deleted: trunk/docs/SP_get_first_vs_set_offset_memb_mess.3
===================================================================
--- trunk/docs/SP_get_first_vs_set_offset_memb_mess.3 2006-03-02 00:15:59 UTC (rev 318)
+++ trunk/docs/SP_get_first_vs_set_offset_memb_mess.3 2006-03-02 05:16:31 UTC (rev 319)
@@ -1,26 +0,0 @@
-.\" Process this file with
-.\" groff -man -Tascii foo.1
-.\"
-.TH SP_ERROR 3 "JULY 2005" SPREAD "User Manuals"
-.SH NAME
-SP_get_first_vs_set_offset_memb_mess \- Offset to first VS Set in Membership message
-.SH SYNOPSIS
-.B #include <sp.h>
-.br
-.BI "int SP_get_first_vs_set_offset_memb_mess( void );"
-.SH DESCRIPTION
-.B SP_get_first_vs_set_offset_memb_mess
-returns the byte offset of the beginning of the first VS set stored in the membership mesage.
-.SH "RETURN VALUES"
-Returns value.
-.SH BUGS
-None.
-.SH AUTHOR
-Yair Amir <yairamir at cnds.jhu.edu>
-.br
-Jonathan Stanton <jonathan at cnds.jhu.edu>
-.br
-
-.SH "SEE ALSO"
-.BR libspread(3)
-
Deleted: trunk/docs/SP_get_gid_offset_memb_mess.3
===================================================================
--- trunk/docs/SP_get_gid_offset_memb_mess.3 2006-03-02 00:15:59 UTC (rev 318)
+++ trunk/docs/SP_get_gid_offset_memb_mess.3 2006-03-02 05:16:31 UTC (rev 319)
@@ -1,26 +0,0 @@
-.\" Process this file with
-.\" groff -man -Tascii foo.1
-.\"
-.TH SP_ERROR 3 "JULY 2005" SPREAD "User Manuals"
-.SH NAME
-SP_get_gid_offset_memb_mess \- Group ID offset in Membership message
-.SH SYNOPSIS
-.B #include <sp.h>
-.br
-.BI "int SP_get_gid_offset_memb_mess( void );"
-.SH DESCRIPTION
-.B SP_get_gid_offset_memb_mess
-returns the byte offset of the group ID field in the body of a membership message.
-.SH "RETURN VALUES"
-Returns value.
-.SH BUGS
-None.
-.SH AUTHOR
-Yair Amir <yairamir at cnds.jhu.edu>
-.br
-Jonathan Stanton <jonathan at cnds.jhu.edu>
-.br
-
-.SH "SEE ALSO"
-.BR libspread(3)
-
Deleted: trunk/docs/SP_get_local_vs_set_offset_memb_mess.3
===================================================================
--- trunk/docs/SP_get_local_vs_set_offset_memb_mess.3 2006-03-02 00:15:59 UTC (rev 318)
+++ trunk/docs/SP_get_local_vs_set_offset_memb_mess.3 2006-03-02 05:16:31 UTC (rev 319)
@@ -1,30 +0,0 @@
-.\" Process this file with
-.\" groff -man -Tascii foo.1
-.\"
-.TH SP_ERROR 3 "JULY 2005" SPREAD "User Manuals"
-.SH NAME
-SP_get_local_vs_set_offset_memb_mess \- Offset to beginning of local VS Set in Membership message
-.SH SYNOPSIS
-.B #include <sp.h>
-.br
-.BI "int SP_get_local_vs_set_offset_memb_mess( char *" reg_memb_mess );
-.SH DESCRIPTION
-.B SP_get_local_vs_set_offset_memb_mess
-returns the byte offset of the beginning of the local client's VS Set in the body of a membership message.
-Unlike other SP_get_* functions, the value returned can be different for every receiver.
-The
-.I reg_memb_mess
-should be the body of a received membership message.
-.SH "RETURN VALUES"
-Returns value.
-.SH BUGS
-None.
-.SH AUTHOR
-Yair Amir <yairamir at cnds.jhu.edu>
-.br
-Jonathan Stanton <jonathan at cnds.jhu.edu>
-.br
-
-.SH "SEE ALSO"
-.BR libspread(3)
-
Deleted: trunk/docs/SP_get_local_vs_set_offset_memb_scat.3
===================================================================
--- trunk/docs/SP_get_local_vs_set_offset_memb_scat.3 2006-03-02 00:15:59 UTC (rev 318)
+++ trunk/docs/SP_get_local_vs_set_offset_memb_scat.3 2006-03-02 05:16:31 UTC (rev 319)
@@ -1,30 +0,0 @@
-.\" Process this file with
-.\" groff -man -Tascii foo.1
-.\"
-.TH SP_ERROR 3 "JULY 2005" SPREAD "User Manuals"
-.SH NAME
-SP_get_local_vs_set_offset_memb_mess \- Offset to beginning of local VS Set in Membership message
-.SH SYNOPSIS
-.B #include <sp.h>
-.br
-.BI "int SP_get_local_vs_set_offset_memb_scat( const scatter *" reg_memb_scat );
-.SH DESCRIPTION
-.B SP_get_local_vs_set_offset_memb_scat
-returns the byte offset of the beginning of the local client's VS Set in the body of a membership message.
-Unlike other SP_get_* functions, the value returned can be different for every receiver.
-The
-.I reg_memb_scat
-should be the scatter storing the body of a received membership message.
-.SH "RETURN VALUES"
-Returns value.
-.SH BUGS
-None.
-.SH AUTHOR
-Yair Amir <yairamir at cnds.jhu.edu>
-.br
-Jonathan Stanton <jonathan at cnds.jhu.edu>
-.br
-
-.SH "SEE ALSO"
-.BR libspread(3)
-
Added: trunk/docs/SP_get_memb_info.3
===================================================================
--- trunk/docs/SP_get_memb_info.3 (rev 0)
+++ trunk/docs/SP_get_memb_info.3 2006-03-02 05:16:31 UTC (rev 319)
@@ -0,0 +1,78 @@
+.\" Process this file with
+.\" groff -man -Tascii foo.1
+.\"
+.TH SP_GET_MEMB_INFO 3 "February 2006" SPREAD "User Manuals"
+.SH NAME
+SP_get_memb_info, SP_scat_get_memb_info \- Extract membership information from message
+.SH SYNOPSIS
+.B #include <sp.h>
+.sp
+.BI "int SP_get_memb_info( const char * " memb_mess ", const service " service_type ", membership_info *" memb_info );
+.br
+.BI "int SP_scat_get_memb_info( const scatter * " memb_mess_scat ", const service " service_type ", membership_info *" memb_info );
+.sp
+.SH DESCRIPTION
+.B SP_get_memb_info
+and its scatter variant all parse the contents of a message body that is received as part of a membership message and fill in the
+.I membership_info
+struct that is passed in as a parameter.
+
+The
+.I service_type
+and the
+.I memb_mess
+fields should be the same as the values returned in a previous
+.B SP_receive
+call for a membership message. The caller should allocate a new
+.I membership_info
+structure and pass that into this function. When the function returns the structure will be filled in.
+
+The fields of a membership_info struct include
+.RS
+.TP
+.I group_id gid
+.br
+.TP
+.I char changed_member[MAX_GROUP_NAME]
+.br
+.TP
+.I unsigned int num_vs_set
+.br
+.TP
+.I vs_set_info my_vs_set
+.RE
+
+The
+.I changed_member
+field is filled in with the name of the new or leaving member if the
+membership is a Join, Leave or Disconnect. If it is a Network
+membership event then the changed_member field is blank and
+multiple vs_sets will be available with all of the subsets of daemons
+coming together into the new membership.
+
+The
+.I my_vs_set
+field stores the number of members of my local vs set, i.e. those processes who came together with me
+and the location of the list of members. See
+.B SP_get_vs_set_members
+for how to extract the full list of members. The
+.B SP_get_vs_sets_info
+function will return the full list of all VS sets that arrived with this membership message.
+
+.SH "RETURN VALUES"
+Returns a postivive value on success or one of the following errors ( < 0 ):
+.TP 0.8i
+.B ILLEGAL_MESSAGE
+The message had an illegal structure, like a scatter not filled out correctly. Or it is not
+a membership message.
+.SH BUGS
+None.
+.SH AUTHOR
+Yair Amir <yairamir at cnds.jhu.edu>
+.br
+Jonathan Stanton <jonathan at cnds.jhu.edu>
+.br
+
+.SH "SEE ALSO"
+.BR libspread (3)
+
Deleted: trunk/docs/SP_get_num_vs_sets_offset_memb_mess.3
===================================================================
--- trunk/docs/SP_get_num_vs_sets_offset_memb_mess.3 2006-03-02 00:15:59 UTC (rev 318)
+++ trunk/docs/SP_get_num_vs_sets_offset_memb_mess.3 2006-03-02 05:16:31 UTC (rev 319)
@@ -1,27 +0,0 @@
-.\" Process this file with
-.\" groff -man -Tascii foo.1
-.\"
-.TH SP_ERROR 3 "JULY 2005" SPREAD "User Manuals"
-.SH NAME
-SP_get_offset_to_local_vs_set_offset \- Offset to integer storing the offset to the local VS Set in Membership message
-.SH SYNOPSIS
-.B #include <sp.h>
-.br
-.BI "int SP_get_offset_to_local_vs_set_offset( void );"
-.SH DESCRIPTION
-.B SP_get_offset_to_local_vs_set_offset
-returns the byte offset of the integer storing the offset that locates the local VS Set belonging to the client who
-received the membership message. This value could be different for each receiver.
-.SH "RETURN VALUES"
-Returns value.
-.SH BUGS
-None.
-.SH AUTHOR
-Yair Amir <yairamir at cnds.jhu.edu>
-.br
-Jonathan Stanton <jonathan at cnds.jhu.edu>
-.br
-
-.SH "SEE ALSO"
-.BR libspread(3)
-
Added: trunk/docs/SP_get_vs_set_members.3
===================================================================
--- trunk/docs/SP_get_vs_set_members.3 (rev 0)
+++ trunk/docs/SP_get_vs_set_members.3 2006-03-02 05:16:31 UTC (rev 319)
@@ -0,0 +1,46 @@
+.\" Process this file with
+.\" groff -man -Tascii foo.1
+.\"
+.TH SP_GET_VS_SET_MEMBERS 3 "February 2006" SPREAD "User Manuals"
+.SH NAME
+SP_get_vs_set_members, SP_scat_get_vs_set_members \- Extract list of members of a particular VS set from membership message
+.SH SYNOPSIS
+.B #include <sp.h>
+.sp
+.BI "int SP_get_vs_set_members( const char * " memb_mess ", const vs_set_info *" vs_set ", char " member_names[][MAX_GROUP_NAME] ", int " member_names_count );
+.br
+.BI "int SP_scat_get_vs_set_members( const scatter * " memb_mess_scat ", const vs_set_info *" vs_set ", char " member_names[][MAX_GROUP_NAME] ", int " member_names_count );
+.sp
+.SH DESCRIPTION
+.B SP_get_vs_set_members
+and its scatter variant extract the list of members of a particular VS set.
+The members are stored into an array of strings, each of which is MAX_GROUP_NAME characters in length.
+The number of strings (names) in the array should be provided in the
+.I member_names_count
+parameter.
+
+The
+.I memb_mess
+field or scatter field should be the body of a message that was returned in a previous
+.B SP_receive
+call for a membership message.
+
+.SH "RETURN VALUES"
+Returns a postivive value on success or one of the following errors ( < 0 ):
+.TP 0.8i
+.B BUFFER_TOO_SHORT
+The allocated array of member names can not hold the number of
+members in this VS set. No data is parsed. Reallocate
+a larger array of member names (the required number is available
+in the corresponding vs_set_info struct) and call this function again.
+.SH BUGS
+None.
+.SH AUTHOR
+Yair Amir <yairamir at cnds.jhu.edu>
+.br
+Jonathan Stanton <jonathan at cnds.jhu.edu>
+.br
+
+.SH "SEE ALSO"
+.BR libspread (3)
+
Deleted: trunk/docs/SP_get_vs_set_members_offset_vs_set.3
===================================================================
--- trunk/docs/SP_get_vs_set_members_offset_vs_set.3 2006-03-02 00:15:59 UTC (rev 318)
+++ trunk/docs/SP_get_vs_set_members_offset_vs_set.3 2006-03-02 05:16:31 UTC (rev 319)
@@ -1,27 +0,0 @@
-.\" Process this file with
-.\" groff -man -Tascii foo.1
-.\"
-.TH SP_ERROR 3 "JULY 2005" SPREAD "User Manuals"
-.SH NAME
-SP_get_vs_set_members_offset_vs_set \- Offset to member list of current VS Set in Membership message
-.SH SYNOPSIS
-.B #include <sp.h>
-.br
-.BI "int SP_get_vs_set_members_offset_vs_set( void );"
-.SH DESCRIPTION
-.B SP_get_vs_set_members_offset_vs_set
-returns the byte offset to the member list of a VS set stored in the membership mesage. The
-offset is relative to the beginning of the specific VS set entry.
-.SH "RETURN VALUES"
-Returns value.
-.SH BUGS
-None.
-.SH AUTHOR
-Yair Amir <yairamir at cnds.jhu.edu>
-.br
-Jonathan Stanton <jonathan at cnds.jhu.edu>
-.br
-
-.SH "SEE ALSO"
-.BR libspread(3)
-
Deleted: trunk/docs/SP_get_vs_set_size_offset_vs_set.3
===================================================================
--- trunk/docs/SP_get_vs_set_size_offset_vs_set.3 2006-03-02 00:15:59 UTC (rev 318)
+++ trunk/docs/SP_get_vs_set_size_offset_vs_set.3 2006-03-02 05:16:31 UTC (rev 319)
@@ -1,27 +0,0 @@
-.\" Process this file with
-.\" groff -man -Tascii foo.1
-.\"
-.TH SP_ERROR 3 "JULY 2005" SPREAD "User Manuals"
-.SH NAME
-SP_get_vs_set_size_offset_vs_set \- Offset to size of current VS Set in Membership message
-.SH SYNOPSIS
-.B #include <sp.h>
-.br
-.BI "int SP_get_vs_set_size_offset_vs_set( void );"
-.SH DESCRIPTION
-.B SP_get_vs_set_size_offset_vs_set
-returns the byte offset to the size field of a VS set stored in the membership mesage. The
-offset is relative to the beginning of the specific VS set entry.
-.SH "RETURN VALUES"
-Returns value.
-.SH BUGS
-None.
-.SH AUTHOR
-Yair Amir <yairamir at cnds.jhu.edu>
-.br
-Jonathan Stanton <jonathan at cnds.jhu.edu>
-.br
-
-.SH "SEE ALSO"
-.BR libspread(3)
-
Added: trunk/docs/SP_get_vs_sets_info.3
===================================================================
--- trunk/docs/SP_get_vs_sets_info.3 (rev 0)
+++ trunk/docs/SP_get_vs_sets_info.3 2006-03-02 05:16:31 UTC (rev 319)
@@ -0,0 +1,65 @@
+.\" Process this file with
+.\" groff -man -Tascii foo.1
+.\"
+.TH SP_GET_VS_SETS_INFO 3 "February 2006" SPREAD "User Manuals"
+.SH NAME
+SP_get_vs_sets_info, SP_scat_get_vs_sets_info \- Extract list of VS sets from membership message
+.SH SYNOPSIS
+.B #include <sp.h>
+.sp
+.BI "int SP_get_vs_sets_info( const char * " memb_mess ", vs_set_info *" vs_sets ", int " num_vs_sets ", unsigned int *" my_vs_set_index );
+.br
+.BI "int SP_scat_get_vs_sets_info( const scatter * " memb_mess_scat ", vs_set_info *" vs_sets ", int " num_vs_sets ", unsigned int *" my_vs_set_index );
+.sp
+.SH DESCRIPTION
+.B SP_get_vs_sets_info
+and its scatter variant extract the list of VS sets provided in a Network membership message and store them into the
+.I vs_sets
+array of
+.B vs_set_info
+structs. The number of elements in the array should be provided in the
+.I num_vs_sets
+parameter.
+
+This function also returns an index of which VS set in the array corresponds to the current process's VS set. That index value is returned in the
+.I my_vs_set_index
+parameter.
+
+The
+.I memb_mess
+field or scatter field should be the body of a message that was returned in a previous
+.B SP_receive
+call for a membership message.
+
+The fields of a vs_set_info struct include
+.RS
+.TP
+.I unsigned int num_members
+.br
+.TP
+.I char members[][MAX_GROUP_NAME]
+.RE
+
+For each of the vs_set_info records in the array, the function
+.B SP_get_vs_set_members
+will grab the actual array of member names for the specified VS set.
+
+.SH "RETURN VALUES"
+Returns a postivive value on success or one of the following errors ( < 0 ):
+.TP 0.8i
+.B BUFFER_TOO_SHORT
+The allocated array of vs_set_info structs can not hold the number of
+VS sets contained in this membership message. No data is parsed. Reallocate
+a larger array of vs_set_info structs (the required number is available
+in the membership_info struct) and call this function again.
+.SH BUGS
+None.
+.SH AUTHOR
+Yair Amir <yairamir at cnds.jhu.edu>
+.br
+Jonathan Stanton <jonathan at cnds.jhu.edu>
+.br
+
+.SH "SEE ALSO"
+.BR libspread (3)
+
Modified: trunk/docs/SP_receive.3
===================================================================
--- trunk/docs/SP_receive.3 2006-03-02 00:15:59 UTC (rev 318)
+++ trunk/docs/SP_receive.3 2006-03-02 05:16:31 UTC (rev 319)
@@ -205,80 +205,88 @@
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
-.I group_id,
-.I num_vs_sets,
-.I local_vs_set_offset
-and a list of
-.I vs_sets.
+from the old group membership into this new membership.
-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.
+All fields are contiguous in the message buffer.
+Since
+the layout of the membership message can change between versions, the
+best way to process them is to use the functions we provide that translate the
+message body into well-defined structures of membership information. The parsing
+functions have two varients, one for regular message bodies that are one contiguous
+array of bytes, and one for message bodies set up as scatters.
+
.RS
.TP
-.B SP_get_gid_offset_memb_mess()
+.B SP_get_memb_info
.br
.TP
-.B SP_get_num_vs_sets_offset_memb_mess()
+.B SP_get_vs_sets_info
.br
.TP
-.B SP_get_first_vs_set_offset_memb_mess()
-.br
-.TP
-.B SP_get_offset_to_local_vs_set_offset()
+.B SP_get_vs_set_members
.RE
-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.
-
-To get the actual byte location of the specific local vs_set for the application who received the
-message, the functions
-
.RS
.TP
-.B SP_get_local_vs_set_offset_memb_mess( char *reg_memb_mess )
+.B SP_scat_get_memb_info
.br
.TP
-.B SP_get_local_vs_set_offset_memb_scat( const scatter *reg_memb_scat )
+.B SP_scat_get_vs_sets_info
+.br
+.TP
+.B SP_scat_get_vs_set_members
.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.
+These three functions fill in standard structures that the application provides with all of the gid and vs set
+information about the membership.
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.
+own vs_set (identical to the information Spread provided prior to version 4) then
+that can be achieved by two function calls. First to
+.B SP_get_memb_info
+and then to
+.B SP_get_vs_set_members.
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
+
+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.
+
+If you want to parse the contents of the membership message body yourself, the following paragraphs
+specify the current layout of the fields. This layout can definitely change (and has several times in
+the past) and we make not guarantees about future changes. So if you choose to parse it yourself you may
+have to update your code when new Spread releases are made.
+
+The membership message body includes the
+following fields in order. Each is either a defined structure or if it is an integer, then it is an unsigned 32 bit integer. The vs sets are defined below.
+
.RS
.TP
-.B SP_get_vs_set_size_offset_vs_set()
-.br
+.B group_id gid;
.TP
-.B SP_get_vs_set_members_offset_vs_set()
+.B unsigned int num_vs_sets;
+.TP
+.B unsigned int local_vs_set_offset;
+.TP
+and a list of
+.B vs_sets;
.RE
-The offsets returned by these functions are relative to the beginning of the specific vs_set,
-not the beginning of the message data field.
+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 integer num_vs_members value so that the application can determine the length of the members array to read.
-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.
+.RS
+.TP
+.B unsigned int num_vs_members;
+.TP
+.B char members[][MAX_GROUP_NAME]
+.RE
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
Added: trunk/docs/SP_scat_get_memb_info.3
===================================================================
--- trunk/docs/SP_scat_get_memb_info.3 (rev 0)
+++ trunk/docs/SP_scat_get_memb_info.3 2006-03-02 05:16:31 UTC (rev 319)
@@ -0,0 +1,4 @@
+.\" Process this file with
+.\" groff -man -Tascii foo.1
+.\"
+.so man3/SP_get_memb_info.3
Added: trunk/docs/SP_scat_get_vs_set_members.3
===================================================================
--- trunk/docs/SP_scat_get_vs_set_members.3 (rev 0)
+++ trunk/docs/SP_scat_get_vs_set_members.3 2006-03-02 05:16:31 UTC (rev 319)
@@ -0,0 +1,4 @@
+.\" Process this file with
+.\" groff -man -Tascii foo.1
+.\"
+.so man3/SP_get_vs_set_members.3
Added: trunk/docs/SP_scat_get_vs_sets_info.3
===================================================================
--- trunk/docs/SP_scat_get_vs_sets_info.3 (rev 0)
+++ trunk/docs/SP_scat_get_vs_sets_info.3 2006-03-02 05:16:31 UTC (rev 319)
@@ -0,0 +1,4 @@
+.\" Process this file with
+.\" groff -man -Tascii foo.1
+.\"
+.so man3/SP_get_vs_sets_info.3
More information about the Spread-cvs
mailing list