Spread C API | Message Types

www.spread.org

Spread 3.17.3 C API

Message Types for Data and Membership Messages

#define UNRELIABLE_MESS	0x00000001
#define RELIABLE_MESS	0x00000002
#define FIFO_MESS	0x00000004
#define CAUSAL_MESS	0x00000008
#define AGREED_MESS	0x00000010
#define SAFE_MESS	0x00000020

The above define the different types of messages that can be sent by Spread. The first six define the ordering and reliability properties of the message.

UNRELIABLE_MESS
The message is sent unreliably and might be dropped or duplicated, so the application must be ready to deal with that. Duplications should be very rare. Some, all or none of the recipients may receive the message.
RELIABLE_MESS
The message will arrive once at all members of its destination group, it may be arbitrarily, but finitely delayed before arriving, and may arrive out of order with regards to other reliable messages.
FIFO_MESS:
The message will be reliably delivered once to all members of its destination groups, and it will be ordered with all other FIFO messages from the same source. Nothing is guaranteed about the ordering of FIFO messages from different sources.
CAUSAL_MESS:
These messages have all the properties of FIFO messages and in addition are causally ordered (as defined by Lamport) with regards to all sources.
AGREED_MESS:
These messages have all the properties of FIFO messages but will be delivered in a causal ordering which will be the same at all recipients, i.e. all the recipients will 'agree' on the order of delivery.
SAFE_MESS:
These messages have all the properties of AGREED messages, but are not delivered until all daemons have received it and are ready to deliver it to the application. This guarantees that if any one application receives a SAFE message then all the applications in that group will also receive it unless the machine or program crashes.

The REGULAR_MESS (0x0000003f) is used to identify a data/application message, in contrast to a membership message.

If the SELF_DISCARD (0x00000040) flag is passed to SP_mulitcast, then the message will not be delivered to the application connection which sent it. If the application has multiple connections open which have joined the same group then other connections will receive it.

#define REG_MEMB_MESS	0x00001000
#define TRANSITION_MESS	0x00002000
#define CAUSED_BY_JOIN	0x00000100
#define CAUSED_BY_LEAVE	0x00000200
#define CAUSED_BY_DISCONNECT	0x00000400
#define CAUSED_BY_NETWORK	0x00000800
#define MEMBERSHIP_MESS	0x00003f00

The above defines specify the types of membership messages as opposed to data messages. The MEMBERSHIP_MESS can be used to select all membership messages. When a membership change occurs each application will receive two membership messages for each group whose membership changed. The first message will be a TRANSITION_MESS which acts as a signal indicating that all messages that arrive after this one and before the REG_MEMB_MESS are 'clean up' from the partition or join such as SAFE messages that need to be delivered before the new membership exists because they come from the old membership. Then the application will receive a REG_MEMB_MESS which will contain all the group membership information and will indicate that the new membership has been established.

The types of membership messages an application can receive are:

CAUSED_BY_JOIN	This indicates a new process or multiple processes joined the group.
CAUSED_BY_LEAVE	This indicates a process or processes left the group.
CAUSED_BY_DISCONNECT	This indicates a membership change was caused by a process disconnecting from a Spread daemon (by calling SP_Disconnect() ) while still a member of groups, or the application exiting before calling SP_disconnect or SP_leave. This should not be considered an error, but rather an implicit LEAVE that indicates the application has completely severed that Spread connection.
CAUSED_BY_NETWORK	This indicates that the membership change was caused by a network partition and not by the application calling SP_Join()

Spread provides additional information about the members who caused this membership change in the mess field of SP_receive.

#define MAX_GROUP_NAME 32

The name of a group is limited to this constant number of characters. Thus a name like: "abracadabra_shalamazoom_woosh_and_whirl" is not legal since it is more then 32 characters. Group names can contain any upper or lower case character, any numerals, and most common filename symbols. The name cannot start with a number, and cannot contain the '#' symbol.