Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SP_RECEIVE(3)			 User Manuals			 SP_RECEIVE(3)

NAME
       SP_receive, SP_scat_receive - Receive message from Spread

SYNOPSIS
       #include	<sp.h>

       int    SP_receive(    mailbox   mbox,   service	 *service_type,	  char
       sender[MAX_GROUP_NAME],	 int   max_groups,   int   *num_groups,	  char
       groups[][MAX_GROUP_NAME],  int16	 *mess_type, int *endian_mismatch, int
       max_mess_len, char *mess);

       int  SP_scat_receive(  mailbox  mbox,   service	 *service_type,	  char
       sender[MAX_GROUP_NAME],	 int   max_groups,   int   *num_groups,	  char
       groups[][MAX_GROUP_NAME], int16 *mess_type, int *endian_mismatch, scat-
       ter *scat_mess);

DESCRIPTION
       SP_receive  is  the  general  purpose receive function for the toolkit.
       This receives not only data messages but	also membership	 messages  for
       the connection.	Messages for all groups	joined on this connection will
       arrive to the same mailbox so a call to SP_receive will	get  a	single
       'message'  from	any  one  of the groups. After the receive completes a
       number of fields	are set	to values indicating  meta  information	 about
       the message (such as groups, mess_type, endianness, type, etc).

       This function is	the most complex used in Spread	because	it is the only
       way for the system to return information	to the application. The	 mean-
       ing of many of the fields changes depending on whether the message is a
       data message or a membership message.

       The SP_receive function will block if no	messages are available.

       The mbox	gives which connection to receive a message on.	  Service_type
       is  a  pointer to a variable of type 'service' which will be set	to the
       message type of the message just	 received.   This  will	 be  either  a
       REG_MESSAGE  or	MEMBERSHIP_MESS,  and the specific type.  The variable
       that service_type points	to is also an input parameter  and  should  be
       set  to	either	0, for normal semantics,  or DROP_RECV (a defined con-
       stant) if you want to receive the 'non-reliable'	 semantics  that  will
       truncate	 messages  if  the provided buffers for	message	data and group
       lists are too small. More information  about  DROP_RECV	semantics  are
       provided	later in this man page.

       The  rest  of  the  parameters  differ in meaning depending on the ser-
       vice_type.  If the service_type is a REG_MESSAGE	 (i.e.	data  message)
       then:

       The  sender  is	a  pointer  to	an  array  of  characters  of at least
       MAX_GROUP_NAME size.  This will be set to the name of the sending  con-
       nection(its private group name).

       The max_groups is the maximum number of groups you have allocated space
       for in the 'groups' array passed	to the receive function.

       Num_groups is a pointer to an int which will be set to  the  number  of
       groups set in the 'groups' array.

       The  groups array holds upto max_groups group names, each of which is a
       string of at most MAX_GROUP_NAME	characters. All	of  the	 groups	 which
       are receiving this message will be listed here, unless the array	is too
       small and then as many as can fit will be  listed  and  the  num_groups
       value  will  be	set  to	be negative. For example, if your groups array
       could store 5 group names, but a	message	 for  7	 groups	 arrived,  the
       first  five group names would appear in the groups array	and num_groups
       would be	set to -7.

       The mess_type field will	be set to the message type field the  applica-
       tion sent with the original message, this is only a short int (16bits).
       This value is already endian corrected before the application  receives
       it.

       Endian_mismatch	will be	set to true (1)	if the endianness of the send-
       ing machine differs from	that of	this receiving machine.	 If  the  BUF-
       FER_TOO_SHORT  error is returned	then the endian_mismatch field will be
       set to the size of the incoming message as a negative value. So if  the
       message	requires 300 bytes of buffer space and only 200	bytes was pro-
       vided in	the mess buffer, endian_mismatch will be set to	-300.

       The actual message body being received will be passed into  the	buffer
       given by	mess which is at least max_mess_len bytes in size. If the mes-
       sage being received is larger then this	buffer	the  default  behaivor
       will  be	 to  return  a BUFFER_TOO_SHORT	error and provide the required
       length in the endian_mismatch field. If the DROP_RECV flag  was	passed
       in  the	service_type  field, then as much data as possible will	be re-
       turned and the extra data will be discarded by the system and  the  re-
       turn  value  of SP_receive will indictate an error.  If the SP_scat_re-
       ceive form is used then instead of the mess buffer and length fields, a
       single  scat_mess  scatter structure should be passed to	receive	filled
       in with whatever	buffers	you wish to receive into  and  their  lengths.
       These  buffers  must  be	valid memory areas.  They will be filled in by
       the receive call	in the order they are listed.

       If this is a MEMB_MESSAGE (i.e. membership message) and it specifically
       is a TRANS_MESS,	then:

       The  sender  char  array	will be	set to the name	of the group for which
       the membership change is	occuring.

       The max_groups and max_mess_len fields are not used and the  num_groups
       is  0  and  groups  since there are no normal groups for	a transitional
       membership, the sender field is used instead.  The mess_type  field  is
       set  to	-1.  The  endian_mismatch field	will be	zero since the transi-
       tional does not have any	endian issues. The mess	 field	will  be  left
       empty.	So in essence the only information you get is the sender field
       is set to the group  name  which	 received  a  transitional  membership
       change.	The importance of the TRANS_MEMB_MESS is that it tells the ap-
       plication  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  explanations	of this	please see other documentation and re-
       search papers.

       If This is a MEMB_MESSAGE (i.e. membership message) and it specifically
       is a REG_MEMB_MESS, then:

       The  sender  char  array	will be	set to the name	of the group for which
       the membership change is	occuring.

       The max_groups and max_mess_len fields have the same meaning as before,
       and the mess_type field will be set to the index	of this	process	in the
       array of	group members. The endian_mismatch field will again be set  to
       0 since there are no endian issues with regular memberships.

       The groups array	and mess body are used to provide two kinds of member-
       ship information	about the change that just occured in this group.  The
       num_groups  field  will be set to the number of members in the group in
       the new membership (i.e.	after the change occured). Correspondingly the
       groups  array  will be set to the private group names of	all members of
       this group in the 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.

       The second set of information is	stored in the message  body  and  pro-
       vides  a	 list  of all the private group	names of those processes which
       came with your process from the old group membership into this new mem-
       bership.	The data buffer	will include the following fields:

	      group_id;

	      int num_vs_members;

	      char vs_set[][MAX_GROUP_NAME];

       The location of the beginning of	each field is provided by the accessor
       functions SP_get_gid_offset_memb_mess,  SP_get_num_vs_offset_memb_mess,
       and  SP_get_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
       upon the	type of	the membership change:

	      CAUSED_BY_JOIN:
		      Vs_set  contains	the  private  group  of	 the   joining
		      process.

	      CAUSED_BY_LEAVE:
		      Vs_set   contains	 the  private  group  of  the  leaving
		      process.

	      CAUSED_BY_DISCONNECT:
		      Vs_set contains the private group	of  the	 disconnecting
		      process.

	      CAUSED_BY_NETWORK:
		      Vs_set  contains	the  group names of the	members	of the
		      new membership who came with me (the current process) to
		      the  new	membership.  Of	course,	all new	members	can be
		      determined by comparing it with the groups parameter  of
		      the SP_receive call.

       If this is a MEMB_MESSAGE (i.e. membership message) and it is neither a
       REG_MEMB_MESS or	a TRANS_MEMB_MESS,  then  it  represents  exactly  the
       situtation where	the member receiving this message has left a group and
       this is notification that the leave has occured,	thus it	 is  sometimes
       called  a  self-leave message.  The simplest test for this is if	a mes-
       sage is CAUSED_BY_LEAVE and REG_MEMB_MESS is FALSE then it is  a	 self-
       leave  message.	 TRANS_MEMB_MESS  never	have a CAUSED_BY_ type because
       they only serve to signal upto where SAFE delivery and AGREED  delivery
       (with no	holes) is guaranteed in	the complete old group membership.

       The  other  members  of	the group this member just left	will receive a
       normal TRANS_MEMB_MESS, REG_MEMB_MESS pair as described	above  showing
       the membership change.

       The fields of SP_receive	in this	case will be as	follows:

       The  sender  char  array	will be	set to the name	of the group for which
       the membership change is	occuring.

       The max_groups and max_mess_len fields have the same meaning as before,
       and the mess_type and endian_mismatch fields will again be set to 0.

       The groups array	and mess body are used to provide two kinds of member-
       ship information	about the change that just occured in this group.  The
       num_groups  field  will be set to 0 and the groups array	will be	empty,
       since this member is no longer part of the group	and thus has no	knowl-
       edge of it. The mess body will also be empty.

RETURN VALUES
       Returns	the size of the	message	received on success or one of the fol-
       lowing errors ( < 0 ):

       ILLEGAL_SESSION
	       The mbox	given to receive on was	illegal.

       ILLEGAL_MESSAGE
	       The message had an illegal structure, like a scatter not	filled
	       out correctly.

       CONNECTION_CLOSED
	       During  communication  to receive the message communication er-
	       rors occured and	the receive could not be completed.

       GROUPS_TOO_SHORT
	       If the groups array is too short	to hold	 the  entire  list  of
	       groups this message was sent to then this error is returned and
	       the num_groups field will be set	to the negative	of the	number
	       of groups needed.

       BUFFER_TOO_SHORT
	       If  the	message	body buffer mess is too	short to hold the mes-
	       sage being received then	this error is  returned	 and  the  en-
	       dian_mismatch  field  is	 set  to the negative value of the re-
	       quired buffer length.

BUGS
       None.

AUTHOR
       Yair Amir <yairamir@cnds.jhu.edu>
       Jonathan	Stanton	<jonathan@cnds.jhu.edu>
       Commedia	Project	<commedia@cnds.jhu.edu>

SEE ALSO
       libsp(3)

Spread				September 2002			 SP_RECEIVE(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | BUGS | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=SP_receive&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help