org.jgroups.protocols.pbcast

Class GMS


public class GMS
extends Protocol

Group membership protocol. Handles joins/leaves/crashes (suspicions) and emits new views accordingly. Use VIEW_ENFORCER on top of this layer to make sure new members don't receive any messages until they are members.

Nested Class Summary

static class
GMS.GmsHeader

Field Summary

long
digest_timeout
String
group_addr
Object
impl_mutex
long
join_retry_timeout
long
join_timeout
Vector
joining
Members joined but for which no view has been received yet
long
leave_timeout
Vector
leaving
Members excluded from group, but for which no view has been received yet
Address
local_addr
long
ltime
Membership
members
long
merge_timeout
protected int
num_prev_mbrs
Max number of old members to keep in history
Membership
tmp_members
ViewId
view_id

Fields inherited from class org.jgroups.stack.Protocol

down_handler, down_prot, down_queue, down_thread, down_thread_prio, log, observer, props, stack, up_handler, up_prot, up_queue, up_thread, up_thread_prio

Constructor Summary

GMS()

Method Summary

void
becomeClient()
void
becomeCoordinator()
void
becomeParticipant()
View
castViewChange(Vector new_mbrs, Vector old_mbrs, Vector suspected_mbrs)
Compute a new view, given the current view, the new members and the suspected/left members.
void
castViewChange(View new_view)
void
castViewChange(View new_view, Digest digest)
protected boolean
checkSelfInclusion(Vector mbrs)
Returns true if local_addr is member of mbrs, else false
protected Address
determineCoordinator()
void
down(Event evt)
Digest
getDigest()
Sends down a GET_DIGEST event and waits for the GET_DIGEST_OK response, or timeout, whichever occurs first
GmsImpl
getImpl()
String
getName()
View
getNextView(Vector new_mbrs, Vector old_mbrs, Vector suspected_mbrs)
Computes the next view.
void
init()
void
installView(View new_view)
Sets the new view and sends a VIEW_CHANGE event up and down the stack.
void
installView(View new_view, Digest digest)
Sets the new view and sends a VIEW_CHANGE event up and down the stack.
View
makeView(Vector mbrs)
View
makeView(Vector mbrs, ViewId vid)
void
mergeDigest(Digest d)
Send down a MERGE_DIGEST event
void
receiveUpEvent(Event evt)
This method is overridden to avoid hanging on getDigest(): when a JOIN is received, the coordinator needs to retrieve the digest from the PBCAST layer.
Vector
requiredDownServices()
void
setDigest(Digest d)
Send down a SET_DIGEST event
void
setImpl(GmsImpl new_impl)
boolean
setProperties(Properties props)
Setup the Protocol instance according to the configuration string
void
start()
void
stop()
void
up(Event evt)
protected boolean
wouldBeNewCoordinator(Address potential_new_coord)
Checks whether the potential_new_coord would be the new coordinator (2nd in line)

Methods inherited from class org.jgroups.stack.Protocol

destroy, down, getDownProtocol, getDownQueue, getName, getProperties, getUpProtocol, getUpQueue, handleSpecialDownEvent, init, passDown, passUp, providedDownServices, providedUpServices, receiveDownEvent, receiveUpEvent, requiredDownServices, requiredUpServices, setDownProtocol, setObserver, setProperties, setPropertiesInternal, setProtocolStack, setUpProtocol, start, startDownHandler, startUpHandler, stop, stopInternal, up

Field Details

digest_timeout

public long digest_timeout

group_addr

public String group_addr

impl_mutex

public Object impl_mutex

join_retry_timeout

public long join_retry_timeout

join_timeout

public long join_timeout

joining

public Vector joining
Members joined but for which no view has been received yet

leave_timeout

public long leave_timeout

leaving

public Vector leaving
Members excluded from group, but for which no view has been received yet

local_addr

public Address local_addr

ltime

public long ltime

members

public Membership members

merge_timeout

public long merge_timeout

num_prev_mbrs

protected int num_prev_mbrs
Max number of old members to keep in history

tmp_members

public Membership tmp_members

view_id

public ViewId view_id

Constructor Details

GMS

public GMS()

Method Details

becomeClient

public void becomeClient()

becomeCoordinator

public void becomeCoordinator()

becomeParticipant

public void becomeParticipant()

castViewChange

public View castViewChange(Vector new_mbrs,
                           Vector old_mbrs,
                           Vector suspected_mbrs)
Compute a new view, given the current view, the new members and the suspected/left members. Then simply mcast the view to all members. This is different to the VS GMS protocol, in which we run a FLUSH protocol which tries to achive consensus on the set of messages mcast in the current view before proceeding to install the next view. The members for the new view are computed as follows:
existing          leaving        suspected          joining
1. new_view      y                 n               n                 y
2. tmp_view      y                 y               n                 y
(view_dest)
  1. The new view to be installed includes the existing members plus the joining ones and excludes the leaving and suspected members.
  2. A temporary view is sent down the stack as an event. This allows the bottom layer (e.g. UDP or TCP) to determine the members to which to send a multicast message. Compared to the new view, leaving members are included since they have are waiting for a view in which they are not members any longer before they leave. So, if we did not set a temporary view, joining members would not receive the view (signalling that they have been joined successfully). The temporary view is essentially the current view plus the joining members (old members are still part of the current view).
Returns:
View The new view

castViewChange

public void castViewChange(View new_view)

castViewChange

public void castViewChange(View new_view,
                           Digest digest)

checkSelfInclusion

protected boolean checkSelfInclusion(Vector mbrs)
Returns true if local_addr is member of mbrs, else false

determineCoordinator

protected Address determineCoordinator()

down

public void down(Event evt)
Overrides:
down in interface Protocol

getDigest

public Digest getDigest()
Sends down a GET_DIGEST event and waits for the GET_DIGEST_OK response, or timeout, whichever occurs first

getImpl

public GmsImpl getImpl()

getName

public String getName()
Overrides:
getName in interface Protocol

getNextView

public View getNextView(Vector new_mbrs,
                        Vector old_mbrs,
                        Vector suspected_mbrs)
Computes the next view. Returns a copy that has old_mbrs and suspected_mbrs removed and new_mbrs added.

init

public void init()
            throws Exception
Overrides:
init in interface Protocol

installView

public void installView(View new_view)
Sets the new view and sends a VIEW_CHANGE event up and down the stack.

installView

public void installView(View new_view,
                        Digest digest)
Sets the new view and sends a VIEW_CHANGE event up and down the stack. If the view is a MergeView (subclass of View), then digest will be non-null and has to be set before installing the view.

makeView

public View makeView(Vector mbrs)

makeView

public View makeView(Vector mbrs,
                     ViewId vid)

mergeDigest

public void mergeDigest(Digest d)
Send down a MERGE_DIGEST event

receiveUpEvent

public void receiveUpEvent(Event evt)
This method is overridden to avoid hanging on getDigest(): when a JOIN is received, the coordinator needs to retrieve the digest from the PBCAST layer. It therefore sends down a GET_DIGEST event, to which the PBCAST layer responds with a GET_DIGEST_OK event.

However, the GET_DIGEST_OK event will not be processed because the thread handling the JOIN request won't process the GET_DIGEST_OK event until the JOIN event returns. The receiveUpEvent() method is executed by the up-handler thread of the lower protocol and therefore can handle the event. All we do here is unblock the mutex on which JOIN is waiting, allowing JOIN to return with a valid digest. The GET_DIGEST_OK event is then discarded, because it won't be processed twice.

Overrides:
receiveUpEvent in interface Protocol

requiredDownServices

public Vector requiredDownServices()
Overrides:
requiredDownServices in interface Protocol

setDigest

public void setDigest(Digest d)
Send down a SET_DIGEST event

setImpl

public void setImpl(GmsImpl new_impl)

setProperties

public boolean setProperties(Properties props)
Setup the Protocol instance according to the configuration string
Overrides:
setProperties in interface Protocol

start

public void start()
            throws Exception
Overrides:
start in interface Protocol

stop

public void stop()
Overrides:
stop in interface Protocol

up

public void up(Event evt)
Overrides:
up in interface Protocol

wouldBeNewCoordinator

protected boolean wouldBeNewCoordinator(Address potential_new_coord)
Checks whether the potential_new_coord would be the new coordinator (2nd in line)

Copyright B) 2001,2002 www.jgroups.com . All Rights Reserved.