News
About us
People
Research
Grants
Publications
Download
Technology Transfer
Spread
Secure Spread
Spines
Backhand
Frugal
Share
Archipelago


SSP_RECEIVE

Section: User Manuals (3)
Updated: JULY 2001

 

NAME

SSP_receive, SSP_scat_receive - Receive message from spread  

SYNOPSIS

#include <ssp.h>

int SSP_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 *more_messes);

int SSP_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, scatter *scat_mess, int *more_messes);  

DESCRIPTION

SSP_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 SSP_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 meaning of many of the fields changes depending on whether the message is a data message or a membership message.

The SSP_receive function will block if no messages are available. If the function is called with the service set to DONT_BLOCK, then the call does not block if no message is 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 rest of the parameters differ in meaning depending on the service_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 connection(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 application 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 sending machine differs from that of this receiving machine.

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 message being received is larger then this buffer the extra data will be discarded by the system and the return value of SSP_receive will indicate an error. The number of messages still waiting for you in the queue is given by more_messes. If the SSP_scat_receive 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 transitional 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 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 explanations of this please see other documentation and research 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 membership 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 provides a list of all the private group names of those processes which came with your process from the old group membership into this new membership. The data buffer will include the following fixed length fields:

group_id;

int num_members;

char groups[][MAX_GROUP_NAME];

The groups array will have num_members group names, each of which is a fixed length string. The content of the groups array is dependent upon the type of the membership change:

CAUSED_BY_JOIN:
Groups contains the private group of the joining process.
CAUSED_BY_LEAVE:
Groups contains the private group of the leaving process.
CAUSED_BY_DISCONNECT:
Groups contains the private group of the disconnecting process.
CAUSED_BY_NETWORK:
Groups 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 SSP_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 message 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 SAVE 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 SSP_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 membership 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 knowledge of it.

The second set of information is stored in the message body and provides a the private group name of the member who just left, which should always be the private group name of the connection which received this message. The data buffer will include the following fixed length fields:

group_id;

int num_members;

char groups[][MAX_GROUP_NAME];

The groups array will have num_members group names, each of which is a fixed length string. The content of the groups array will be the private group of the leaving process, since this case only occurs with a CAUSED_BY_LEAVE membership change.

 

RETURN VALUES

Returns the size of the message received on success or one of the following 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 errors occured and the receive could not be completed.
BUFFER_TOO_SHORT
If the message body buffer mess is too short to hold the message being received, this is returned.
WOULD_BLOCK
A receive call with DONT_BLOCK set would have blocked.
ILLEGAL_PARAM
A call was made with an illegal size (negative).
ILLEGAL_MESSAGE
The message had an illegal structure, like a scatter not filled out correctly, plus a receive call with an illegal scatter (num_elements was illegal (size < 0 || size > FL_MAX_SCATTER_ELEMENTS) or a scatter buffer size was negative.
 

BUGS

None.  

AUTHOR

Cristina Nita-Rotaru <crisn@cnds.jhu.edu>


 

Index

NAME
SYNOPSIS
DESCRIPTION
RETURN VALUES
BUGS
AUTHOR
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 21:52:31 GMT, July 06, 2001
Questions or comments to:
webmaster (at) dsn.jhu.edu
TEL: (410) 516-5562
FAX: (410) 516-6134
Distributed Systems and Networks Lab
Computer Science Department
Johns Hopkins University
3400 N. Charles Street Baltimore, MD 21218-2686