FLUSH, as it name implies, forces group members to flush their pending messages while blocking them to send any additional messages. The process of flushing acquiesces the group so that state transfer or a join can be done. It is also called stop-the-world model as nobody will be able to send messages while a flush is in process. FLUSH has been introduced in JGroups 2.4 release.
Flush is needed for:
State transfer. When a member requests state transfer, the coordinator tells everyone to stop sending messages and waits for everyone's ack. Then it asks the application for its state and ships it back to the requester. After the requester has received and set the state successfully, the coordinator tells everyone to resume sending messages.
View changes (e.g.a join). Before installing a new view V2, flushing would ensure that all messages sent in the current view V1 are indeed delivered in V1, rather than in V2 (in all non-faulty members). This is essentially Virtual Synchrony.
|enable_reconciliation||Reconciliation phase toggle. Default is true|
|end_flush_timeout||Timeout to wait for UNBLOCK after STOP_FLUSH is issued. Default is 2000 msec|
|id||Give the protocol a different ID if needed so we can have multiple instances of it in the same stack|
|level||Sets the logger level (see javadocs)|
|name||Give the protocol a different name if needed so we can have multiple instances of it in the same stack|
|retry_timeout||Retry timeout after an unsuccessful attempt to quiet the cluster (first flush phase). Default is 3000 msec|
|start_flush_timeout||Timeout (per atttempt) to quiet the cluster during the first flush phase. Default is 2000 msec|
|stats||Determines whether to collect statistics (and expose them via JMX). Default is true|
|timeout||Max time to keep channel blocked in flush. Default is 8000 msec|
FLUSH goes through two phases: first to quiet the cluster and second to resume message sending. First phase consists of START_FLUSH, FLUSH_OK and FLUSH_COMPLETED message exchange. START_FLUSH is mcast from a member called FLUSH coordinator. Upon reception of START_FLUSH, each member receives BLOCK event notification and responds with mcast FLUSH_OK. BLOCK event thus indicates, at application level, that FLUSH has been initiated. Once each member receives FLUSH_OK from every other member FLUSH protocol latch is activated at each member and no application messages can pass down through FLUSH. Messages can still go up through FLUSH protocol and stack itself. Upon turning the latch on each member sends back the FLUSH_COMPLETED message back to FLUSH coordinator. After the first phase is completed flush blocks message from application down the channel and it blocks only multicast messages.
In second FLUSH phase FLUSH coordinator resumes cluster wide message sending by mcasting STOP_FLUSH message. Upon reception of STOP_FLUSH message each member mcasts STOP_FLUSH_OK message. When each member receives STOP_FLUSH_OK from every other member - FLUSH latch is turned off and application messages can once again be sent from each cluster member. As soon as FLUSH latch is turned off each member is notified by receiveing UNBLOCK event. Thus FLUSH is completed.