FLUSH SPREAD

FL_flush

Section: User Manuals (3)
Updated: Dec 2000

NAME

FL_flush - flush a group in response to receiving a flush request message.

SYNOPSIS

#include <fl.h>

int FL_flush(mailbox mbox, const char *group_name);

DESCRIPTION

FL_flush flushes the group named group_name in which the connection represented by mbox has received a flush request message. A flush request message is delivered in a group when the underlying membership of that group changes; it is a signal to the application that the membership has changed and some of the original members may have "gone away" (meaning that they are no longer in the group with this connection). However, Flush Spread will not install a new membership in the group until each of the members of the new membership flush the group. Flushing a group gives Flush Spread the permission of this connection to go ahead and install a new view/membership for the group.

During the time after receiving a flush request message but before flushing the group the application must be _VERY_ careful about calling receive functions; if the application isn't careful enough it can permantently block the entire group. For example, say the underlying membership of a group of 10 members changed such that this connection is now alone in the group (there is no way an application can detect the make-up of a group after receiving a flush request). If the application simply calls receive before flushing the group and hasn't ensured that it will receive a message somehow (see below) it will permanently block itself in the receive and any other members that might later be added to that group.

There are a couple ways to avoid this problem, which isn't a bug by the way :P, (1) don't call receive functions after receiving a flush request message and before flushing the group, (2) call receive but set the DONT_BLOCK service flag; if there aren't any messages to receive it will break out with a WOULD_BLOCK error, (3) ensure that there will be a message to receive somehow. There are several ways to do this, but one 100% sure way to do this is if the application sends or has sent a message on this connection (with the SELF_DISCARD service _NOT_ set) that it has not yet received back. In this case, the application will eventually receive its own message (even if it was to another group) on the connection and can therefore be assured of not blocking permanently.

The application _IS_ allowed to send messages to a group after receiving a flush request for that group and before flushing the group. However, only a subset of the original members of the current view will receive these messages (note that I said a subset, not a strict subset). Technically, this is always the case in Spread: an application can determine which other members received certain messages for sure by (1) application level message receipt acknowledgement, (2) employing the safety properties of SAFE messages (although this doesn't guarantee that those members actually processed and handled the message), (3) employing the virtual synchrony property and the transitional set of the new membership when it is installed (although, again, this doesn't guarantee that those members actually processed and handled the messages). See FL_receive or read up on group communication for more in-depth discussions of this matter.

Anyways, when the application is ready it can flush the group. Once it flushes the group it is not allowed to send any messages to that group, until it receives the new membership for that group. If the application breaks this rule, it will receive an ILLEGAL_STATE error.

RETURN VALUES

Returns 0 on success or one of the following errors ( < 0 ):
ILLEGAL_SESSION
The connection represented by mbox is illegal, usually because it is not active.

ILLEGAL_GROUP
The group_name given to flush was illegal for some reason, usually because it was of length 0 or length > MAX_GROUP_NAME. This error can also be returned when a group is flushed for a connection that it has not yet joined or is already leaving.

ILLEGAL_STATE
A connection may flush a group only once in response to each flush request message delivered in that group. If you violate this rule you will get an ILLEGAL_STATE error.

CONNECTION_CLOSED
Errors occurred during communication and the flush could not be initiated.

AUTHOR

John Schultz <jschultz@cnds.jhu.edu>