Chapter 7. List of Protocols

This section is work in progress; we strive to update the documentation as we make changes to the code.

The most important properties are described on the wiki. The idea is that users take one of the predefined configurations (shipped with JGroups) and make only minor changes to it.

For each protocol define:

7.1. Transport

7.1.1. UDP

Table 7.1. Properties

NameDescription
bind_addrThe bind address which should be used by this transport. The following special values are also recognized: GLOBAL, SITE_LOCAL, LINK_LOCAL and NON_LOOPBACK
bind_interface_strThe interface (NIC) which should be used by this transport
bind_portThe port to which the transport binds. Default of 0 binds to any (ephemeral) port
bundler_capacityThe max number of elements in a bundler if the bundler supports size limitations
bundler_typeThe type of bundler used. Has to be "old" (default) or "new"
diagnostics_addrAddress for diagnostic probing. Default is 224.0.75.75
diagnostics_portPort for diagnostic probing. Default is 7500
disable_loopback 
discard_incompatible_packetsDiscard packets with a different version if true. Default is false
enable_bundlingEnable bundling of smaller messages into bigger ones. Default is true
enable_diagnosticsSwitch to enable diagnostic probing. Default is true
enable_unicast_bundlingEnable bundling of smaller messages into bigger ones for unicast messages. Default is false
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
ip_mcastMulticast toggle. If false multiple unicast datagrams are sent instead of one multicast. Default is true
ip_ttlThe time-to-live (TTL) for multicast datagram packets. Default is 8
levelSets the logger level (see javadocs)
log_discard_msgswhether or not warnings about messages from different groups are logged
logical_addr_cache_expirationTime (in ms) after which entries in the logical address cache marked as removable are removed
logical_addr_cache_max_sizeMax number of elements in the logical address cache before eviction starts
loopbackMessages to self are looped back immediately if true
marshaller_pool_size 
max_bundle_sizeMaximum number of bytes for messages to be queued until they are sent
max_bundle_timeoutMax number of milliseconds until queued messages are sent
mcast_group_addrThe multicast address used for sending and receiving packets. Default is 228.8.8.8
mcast_portThe multicast port used for sending and receiving packets. Default is 7600
mcast_recv_buf_sizeReceive buffer size of the multicast datagram socket. Default is 500'000 bytes
mcast_send_buf_sizeSend buffer size of the multicast datagram socket. Default is 100'000 bytes
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
num_timer_threadsNumber of threads to be used by the timer thread pool. Default is 4
oob_thread_pool.keep_alive_timeTimeout in ms to remove idle threads from the OOB pool
oob_thread_pool.max_threadsMax thread pool size for the OOB thread pool
oob_thread_pool.min_threadsMinimum thread pool size for the OOB thread pool
oob_thread_pool_enabledSwitch for enabling thread pool for OOB messages. Default=true
oob_thread_pool_queue_enabledUse queue to enqueue incoming OOB messages
oob_thread_pool_queue_max_sizeMaximum queue size for incoming OOB messages. Default is 500
oob_thread_pool_rejection_policyThread rejection policy. Possible values are Abort, Discard, DiscardOldest and Run. Default is Discard
port_rangeThe range of valid ports, from bind_port to end_port. Infinite if 0
receive_interfacesComma delimited list of interfaces (IP addresses or interface names) to receive multicasts on
receive_on_all_interfacesIf true, the transport should use all available interfaces to receive multicast messages
singleton_nameIf assigned enable this transport to be a singleton (shared) transport
statsDetermines whether to collect statistics (and expose them via JMX). Default is true
thread_naming_patternThread naming pattern for threads in this channel. Default is cl
thread_pool.keep_alive_timeTimeout in milliseconds to remove idle thread from regular pool
thread_pool.max_threadsMaximum thread pool size for the regular thread pool
thread_pool.min_threadsMinimum thread pool size for the regular thread pool
thread_pool_enabledSwitch for enabling thread pool for regular messages. Default true
thread_pool_queue_enabledUse queue to enqueue incoming regular messages. Default is true
thread_pool_queue_max_sizeMaximum queue size for incoming OOB messages. Default is 500
thread_pool_rejection_policyThread rejection policy. Possible values are Abort, Discard, DiscardOldest and Run. Default is Discard
tosTraffic class for sending unicast and multicast datagrams. Default is 8
ucast_recv_buf_sizeReceive buffer size of the unicast datagram socket. Default is 64'000 bytes
ucast_send_buf_sizeSend buffer size of the unicast datagram socket. Default is 100'000 bytes

7.1.2. TCP

Table 7.2. Properties

NameDescription
bind_addrThe bind address which should be used by this transport. The following special values are also recognized: GLOBAL, SITE_LOCAL, LINK_LOCAL and NON_LOOPBACK
bind_interface_strThe interface (NIC) which should be used by this transport
bind_portThe port to which the transport binds. Default of 0 binds to any (ephemeral) port
bundler_capacityThe max number of elements in a bundler if the bundler supports size limitations
bundler_typeThe type of bundler used. Has to be "old" (default) or "new"
conn_expire_timeMax time connection can be idle before being reaped (in ms)
diagnostics_addrAddress for diagnostic probing. Default is 224.0.75.75
diagnostics_portPort for diagnostic probing. Default is 7500
discard_incompatible_packetsDiscard packets with a different version if true. Default is false
enable_bundlingEnable bundling of smaller messages into bigger ones. Default is true
enable_diagnosticsSwitch to enable diagnostic probing. Default is true
enable_unicast_bundlingEnable bundling of smaller messages into bigger ones for unicast messages. Default is false
external_addrUse "external_addr" if you have hosts on different networks, behind firewalls. On each firewall, set up a port forwarding rule (sometimes called "virtual server") to the local IP (e.g. 192.168.1.100) of the host then on each host, set "external_addr" TCP transport parameter to the external (public IP) address of the firewall.
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
levelSets the logger level (see javadocs)
lingerSO_LINGER in msec. Default of -1 disables it
log_discard_msgswhether or not warnings about messages from different groups are logged
logical_addr_cache_expirationTime (in ms) after which entries in the logical address cache marked as removable are removed
logical_addr_cache_max_sizeMax number of elements in the logical address cache before eviction starts
loopbackMessages to self are looped back immediately if true
marshaller_pool_size 
max_bundle_sizeMaximum number of bytes for messages to be queued until they are sent
max_bundle_timeoutMax number of milliseconds until queued messages are sent
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
num_timer_threadsNumber of threads to be used by the timer thread pool. Default is 4
oob_thread_pool.keep_alive_timeTimeout in ms to remove idle threads from the OOB pool
oob_thread_pool.max_threadsMax thread pool size for the OOB thread pool
oob_thread_pool.min_threadsMinimum thread pool size for the OOB thread pool
oob_thread_pool_enabledSwitch for enabling thread pool for OOB messages. Default=true
oob_thread_pool_queue_enabledUse queue to enqueue incoming OOB messages
oob_thread_pool_queue_max_sizeMaximum queue size for incoming OOB messages. Default is 500
oob_thread_pool_rejection_policyThread rejection policy. Possible values are Abort, Discard, DiscardOldest and Run. Default is Discard
peer_addr_read_timeoutMax time to block on reading of peer address
port_rangeThe range of valid ports, from bind_port to end_port. Infinite if 0
reaper_intervalReaper interval in msec. Default is 0 (no reaping)
receive_interfacesComma delimited list of interfaces (IP addresses or interface names) to receive multicasts on
receive_on_all_interfacesIf true, the transport should use all available interfaces to receive multicast messages
recv_buf_sizeReceiver buffer size in bytes
send_buf_sizeSend buffer size in bytes
send_queue_sizeMax number of messages in a send queue
singleton_nameIf assigned enable this transport to be a singleton (shared) transport
sock_conn_timeoutMax time allowed for a socket creation in ConnectionTable
statsDetermines whether to collect statistics (and expose them via JMX). Default is true
tcp_nodelayShould TCP no delay flag be turned on
thread_naming_patternThread naming pattern for threads in this channel. Default is cl
thread_pool.keep_alive_timeTimeout in milliseconds to remove idle thread from regular pool
thread_pool.max_threadsMaximum thread pool size for the regular thread pool
thread_pool.min_threadsMinimum thread pool size for the regular thread pool
thread_pool_enabledSwitch for enabling thread pool for regular messages. Default true
thread_pool_queue_enabledUse queue to enqueue incoming regular messages. Default is true
thread_pool_queue_max_sizeMaximum queue size for incoming OOB messages. Default is 500
thread_pool_rejection_policyThread rejection policy. Possible values are Abort, Discard, DiscardOldest and Run. Default is Discard
use_send_queuesShould separate send queues be used for each connection

7.1.3. TUNNEL

Table 7.3. Properties (experimental)

NameDescription
bind_addrThe bind address which should be used by this transport. The following special values are also recognized: GLOBAL, SITE_LOCAL, LINK_LOCAL and NON_LOOPBACK
bind_interface_strThe interface (NIC) which should be used by this transport
bind_portThe port to which the transport binds. Default of 0 binds to any (ephemeral) port
bundler_capacityThe max number of elements in a bundler if the bundler supports size limitations
bundler_typeThe type of bundler used. Has to be "old" (default) or "new"
diagnostics_addrAddress for diagnostic probing. Default is 224.0.75.75
diagnostics_portPort for diagnostic probing. Default is 7500
discard_incompatible_packetsDiscard packets with a different version if true. Default is false
enable_bundlingEnable bundling of smaller messages into bigger ones. Default is true
enable_diagnosticsSwitch to enable diagnostic probing. Default is true
enable_unicast_bundlingEnable bundling of smaller messages into bigger ones for unicast messages. Default is false
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
levelSets the logger level (see javadocs)
log_discard_msgswhether or not warnings about messages from different groups are logged
logical_addr_cache_expirationTime (in ms) after which entries in the logical address cache marked as removable are removed
logical_addr_cache_max_sizeMax number of elements in the logical address cache before eviction starts
loopbackMessages to self are looped back immediately if true
marshaller_pool_size 
max_bundle_sizeMaximum number of bytes for messages to be queued until they are sent
max_bundle_timeoutMax number of milliseconds until queued messages are sent
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
num_timer_threadsNumber of threads to be used by the timer thread pool. Default is 4
oob_thread_pool.keep_alive_timeTimeout in ms to remove idle threads from the OOB pool
oob_thread_pool.max_threadsMax thread pool size for the OOB thread pool
oob_thread_pool.min_threadsMinimum thread pool size for the OOB thread pool
oob_thread_pool_enabledSwitch for enabling thread pool for OOB messages. Default=true
oob_thread_pool_queue_enabledUse queue to enqueue incoming OOB messages
oob_thread_pool_queue_max_sizeMaximum queue size for incoming OOB messages. Default is 500
oob_thread_pool_rejection_policyThread rejection policy. Possible values are Abort, Discard, DiscardOldest and Run. Default is Discard
port_rangeThe range of valid ports, from bind_port to end_port. Infinite if 0
receive_interfacesComma delimited list of interfaces (IP addresses or interface names) to receive multicasts on
receive_on_all_interfacesIf true, the transport should use all available interfaces to receive multicast messages
reconnect_intervalInterval in msec to attempt connecting back to router in case of torn connection. Default is 5000 msec
router_hostRouter host address
router_portRouter port
singleton_nameIf assigned enable this transport to be a singleton (shared) transport
statsDetermines whether to collect statistics (and expose them via JMX). Default is true
tcp_nodelayShould TCP no delay flag be turned on
thread_naming_patternThread naming pattern for threads in this channel. Default is cl
thread_pool.keep_alive_timeTimeout in milliseconds to remove idle thread from regular pool
thread_pool.max_threadsMaximum thread pool size for the regular thread pool
thread_pool.min_threadsMinimum thread pool size for the regular thread pool
thread_pool_enabledSwitch for enabling thread pool for regular messages. Default true
thread_pool_queue_enabledUse queue to enqueue incoming regular messages. Default is true
thread_pool_queue_max_sizeMaximum queue size for incoming OOB messages. Default is 500
thread_pool_rejection_policyThread rejection policy. Possible values are Abort, Discard, DiscardOldest and Run. Default is Discard

7.2. Initial membership discovery

The task of the discovery is to find an initial membership, which is used to determine the current coordinator. Once a coordinator is found, the joiner sends a JOIN request to the coord.

7.2.1. PING

Table 7.4. Properties

NameDescription
break_on_coord_rspReturn from the discovery phase as soon as we have 1 coordinator response
discovery_timeoutTime (in ms) to wait for our own discovery message to be received. 0 means don't wait. If the discovery message is not received within discovery_timeout ms, a warning will be logged
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
levelSets the logger level (see javadocs)
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
num_initial_membersMinimum number of initial members to get a response from. Default is 2
num_initial_srv_membersMinimum number of server responses (PingData.isServer()=true). If this value is greater than 0, we'll ignore num_initial_members
num_ping_requestsNumber of discovery requests to be sent distributed over timeout. Default is 2
return_entire_cacheWhether or not to return the entire logical-physical address cache mappings on a discovery request, or not. Default is false, except for TCPPING
statsDetermines whether to collect statistics (and expose them via JMX). Default is true
timeoutTimeout to wait for the initial members. Default is 3000 msec

7.2.2. FILE_PING

This uses a shared directory into which all members write their addresses. New joiners read all addresses from this directory (which needs to be shared, e.g. via NFS or SMB) and ping each of the elements of the resulting set of members. When a member leaves, it deletes its corresponding file.

FILE_PING can be used instead of GossipRouter in cases where no external process is desired.

Table 7.5. Properties

NameDescription
break_on_coord_rspReturn from the discovery phase as soon as we have 1 coordinator response
discovery_timeoutTime (in ms) to wait for our own discovery message to be received. 0 means don't wait. If the discovery message is not received within discovery_timeout ms, a warning will be logged
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
levelSets the logger level (see javadocs)
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
num_initial_membersMinimum number of initial members to get a response from. Default is 2
num_initial_srv_membersMinimum number of server responses (PingData.isServer()=true). If this value is greater than 0, we'll ignore num_initial_members
num_ping_requestsNumber of discovery requests to be sent distributed over timeout. Default is 2
return_entire_cacheWhether or not to return the entire logical-physical address cache mappings on a discovery request, or not. Default is false, except for TCPPING
statsDetermines whether to collect statistics (and expose them via JMX). Default is true
timeoutTimeout to wait for the initial members. Default is 3000 msec

7.2.3. TCPPING

Table 7.6. Properties

NameDescription
break_on_coord_rspReturn from the discovery phase as soon as we have 1 coordinator response
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
initial_hostsComma delimited list of hosts to be contacted for initial membership
levelSets the logger level (see javadocs)
max_dynamic_hostsmax number of hosts to keep beyond the ones in initial_hosts
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
num_initial_membersMinimum number of initial members to get a response from. Default is 2
num_initial_srv_membersMinimum number of server responses (PingData.isServer()=true). If this value is greater than 0, we'll ignore num_initial_members
num_ping_requestsNumber of discovery requests to be sent distributed over timeout. Default is 2
port_rangeNumber of ports to be probed for initial membership. Default is 1
return_entire_cacheWhether or not to return the entire logical-physical address cache mappings on a discovery request, or not. Default is false, except for TCPPING
statsDetermines whether to collect statistics (and expose them via JMX). Default is true
timeoutTimeout to wait for the initial members. Default is 3000 msec

7.2.4. TCPGOSSIP

Table 7.7. Properties

NameDescription
break_on_coord_rspReturn from the discovery phase as soon as we have 1 coordinator response
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
initial_hostsComma delimited list of hosts to be contacted for initial membership
levelSets the logger level (see javadocs)
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
num_initial_membersMinimum number of initial members to get a response from. Default is 2
num_initial_srv_membersMinimum number of server responses (PingData.isServer()=true). If this value is greater than 0, we'll ignore num_initial_members
num_ping_requestsNumber of discovery requests to be sent distributed over timeout. Default is 2
reconnect_intervalInterval (ms) by which a disconnected stub attempts to reconnect to the GossipRouter
return_entire_cacheWhether or not to return the entire logical-physical address cache mappings on a discovery request, or not. Default is false, except for TCPPING
sock_conn_timeoutMax time for socket creation. Default is 1000 msec
sock_read_timeoutMax time in milliseconds to block on a read. 0 blocks forever
statsDetermines whether to collect statistics (and expose them via JMX). Default is true
timeoutTimeout to wait for the initial members. Default is 3000 msec

7.2.5. MPING

Table 7.8. Properties

NameDescription
bind_addrBind address for multicast socket. The following special values are also recognized: GLOBAL, SITE_LOCAL, LINK_LOCAL and NON_LOOPBACK
bind_interface_strThe interface (NIC) which should be used by this transport
break_on_coord_rspReturn from the discovery phase as soon as we have 1 coordinator response
discovery_timeoutTime (in ms) to wait for our own discovery message to be received. 0 means don't wait. If the discovery message is not received within discovery_timeout ms, a warning will be logged
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
ip_ttlTime to live for discovery packets. Default is 8
levelSets the logger level (see javadocs)
mcast_addr 
mcast_portMulticast port for discovery packets. Default is 7555
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
num_initial_membersMinimum number of initial members to get a response from. Default is 2
num_initial_srv_membersMinimum number of server responses (PingData.isServer()=true). If this value is greater than 0, we'll ignore num_initial_members
num_ping_requestsNumber of discovery requests to be sent distributed over timeout. Default is 2
receive_interfacesList of interfaces to receive multicasts on
receive_on_all_interfacesIf true, the transport should use all available interfaces to receive multicast messages. Default is false
return_entire_cacheWhether or not to return the entire logical-physical address cache mappings on a discovery request, or not. Default is false, except for TCPPING
send_interfacesList of interfaces to send multicasts on
send_on_all_interfacesWhether send messages are sent on all interfaces. Default is false
statsDetermines whether to collect statistics (and expose them via JMX). Default is true
timeoutTimeout to wait for the initial members. Default is 3000 msec

7.3. Merging after a network partition

7.3.1. MERGE2

Table 7.9. Properties

NameDescription
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
inconsistent_view_thresholdNumber of inconsistent views with only 1 coord after a MERGE event is sent up
levelSets the logger level (see javadocs)
max_intervalMaximum time in ms between runs to discover other clusters
merge_fastWhen receiving a multicast message, checks if the sender is member of the cluster. If not, initiates a merge
merge_fast_delayThe delay (in milliseconds) after which a merge fast execution is started
min_intervalMinimum time in msbetween runs to discover other clusters
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
statsDetermines whether to collect statistics (and expose them via JMX). Default is true

7.4. Failure Detection

The task of failure detection is to probe members of a group and see whether they are alive. When a member is suspected (= deemed dead), then a SUSPECT message is sent to all nodes of the cluster. It is not the task of the failure detection layer to exclude a crashed member (this is done by the group membership protocol, GMS), but simply to notify everyone that a node in the cluster is suspected of having crashed.

7.4.1. FD

Failure detection based on heartbeat messages. If reply is not received without timeout ms, max_tries times, a member is declared suspected, and will be excluded by GMS

Each member send a message containing a "FD" - HEARTBEAT header to its neighbor to the right (identified by the ping_dest address). The heartbeats are sent by the inner class Monitor. When the neighbor receives the HEARTBEAT, it replies with a message containing a "FD" - HEARTBEAT_ACK header. The first member watches for "FD" - HEARTBEAT_ACK replies from its neigbor. For each received reply, it resets the last_ack timestamp (sets it to current time) and num_tries counter (sets it to 0). The same Monitor instance that sends heartbeats whatches the difference between current time and last_ack. If this difference grows over timeout, the Monitor cycles several more times (until max_tries) is reached) and then sends a SUSPECT message for the neighbor's address. The SUSPECT message is sent down the stack, is addressed to all members, and is as a regular message with a FdHeader.SUSPECT header.

Table 7.10. Properties

NameDescription
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
levelSets the logger level (see javadocs)
max_triesNumber of times to send an are-you-alive message
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
statsDetermines whether to collect statistics (and expose them via JMX). Default is true
timeoutTimeout to suspect a node P if neither a heartbeat nor data were received from P. Default is 3000 msec

7.4.2. FD_ALL

Failure detection based on simple heartbeat protocol. Every member periodically multicasts a heartbeat. Every member also maintains a table of all members (minus itself). When data or a heartbeat from P are received, we reset the timestamp for P to the current time. Periodically, we check for expired members, and suspect those.

Example: <FD_ALL interval="3000" timeout="10000"/>

In the exampe above, we send a heartbeat every 3 seconds and suspect members if we haven't received a heartbeat (or traffic) for more than 10 seconds. Note that since we check the timestamps every 'interval' milliseconds, we will suspect a member after roughly 4 * 3s == 12 seconds. If we set the timeout to 8500, then we would suspect a member after 3 * 3 secs == 9 seconds.

Table 7.11. Properties

NameDescription
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
intervalInterval in which a HEARTBEAT is sent to the cluster
levelSets the logger level (see javadocs)
msg_counts_as_heartbeatTreat messages received from members as heartbeats. Note that this means we're updating a value in a hashmap every time a message is passing up the stack through FD_ALL, which is costly. Default is false
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
statsDetermines whether to collect statistics (and expose them via JMX). Default is true
timeoutTimeout after which a node P is suspected if neither a heartbeat nor data were received from P

7.4.3. FD_SIMPLE

7.4.4. FD_PING

FD_PING uses a script or command that is run with 1 argument (the host to be pinged) and needs to return 0 (success) or 1 (failure). The default command is /sbin/ping (ping.exe on Windows), but this is user configurable and can be replaced with any user-provided script or executable.

7.4.5. FD_ICMP

Uses InetAddress.isReachable() to determine whether a host is up or not. Note that this is only available in JDK 5, so reflection is used to determine whether InetAddress provides such a method. If not, an exception will be thrown at protocol initialization time.

The problem with InetAddress.isReachable() is that it may or may not use ICMP in its implementation ! For example, an implementation might try to establish a TCP connection to port 9 (echo service), and - if the echo service is not running - the host would be suspected, although a real ICMP packet would not have suspected the host ! Please check your JDK/OS combo before running this protocol.

Table 7.12. Properties

NameDescription
bind_addrThe network interface to be used for sending ICMP packets, e.g. bind_addr="192.16.8.0.2"

7.4.6. FD_SOCK

Failure detection protocol based on a ring of TCP sockets created between group members. Each member in a group connects to its neighbor (last member connects to first) thus forming a ring. Member B is suspected when its neighbor A detects abnormally closed TCP socket (presumably due to a node B crash). However, if a member B is about to leave gracefully, it lets its neighbor A know, so that it does not become suspected.

If you are using a multi NIC machine note that JGroups versions prior to 2.2.8 have FD_SOCK implementation that does not assume this possibility. Therefore JVM can possibly select NIC unreachable to its neighbor and setup FD_SOCK server socket on it. Neighbor would be unable to connect to that server socket thus resulting in immediate suspecting of a member. Suspected member is kicked out of the group, tries to rejoin, and thus goes into join/leave loop. JGroups version 2.2.8 introduces srv_sock_bind_addr property so you can specify network interface where FD_SOCK TCP server socket should be bound. This network interface is most likely the same interface used for other JGroups traffic. JGroups versions 2.2.9 and newer consult bind.address system property or you can specify network interface directly as FD_SOCK bind_addr property.

Table 7.13. Properties

NameDescription
bind_addrThe NIC on which the ServerSocket should listen on. The following special values are also recognized: GLOBAL, SITE_LOCAL, LINK_LOCAL and NON_LOOPBACK
bind_interface_strThe interface (NIC) which should be used by this transport
get_cache_timeoutTimeout for getting socket cache from coordinator. Default is 1000 msec
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
keep_aliveWhether to use KEEP_ALIVE on the ping socket or not. Default is true
levelSets the logger level (see javadocs)
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
num_triesNumber of attempts coordinator is solicited for socket cache until we give up. Default is 3
sock_conn_timeoutMax time in millis to wait for ping Socket.connect() to return
start_portStart port for server socket. Default value of 0 picks a random port
statsDetermines whether to collect statistics (and expose them via JMX). Default is true
suspect_msg_intervalInterval for broadcasting suspect messages. Default is 5000 msec

7.4.7. VERIFY_SUSPECT

Table 7.14. Properties

NameDescription
bind_addrInterface for ICMP pings. Used if use_icmp is true The following special values are also recognized: GLOBAL, SITE_LOCAL, LINK_LOCAL and NON_LOOPBACK
bind_interface_strThe interface (NIC) which should be used by this transport
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
levelSets the logger level (see javadocs)
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
num_msgsNumber of verify heartbeats sent to a suspected member
statsDetermines whether to collect statistics (and expose them via JMX). Default is true
timeoutNumber of millisecs to wait for a response from a suspected member
use_icmpUse InetAddress.isReachable() to verify suspected member instead of regular messages

7.5. Reliable message transmission

7.5.1. pbcast.NAKACK

NAKACK provides reliable delivery and FIFO (= First In First Out) properties for messages sent to all nodes in a cluster.

Reliable delivery means that no message sent by a sender will ever be lost, as all messages are numbered with sequence numbers (by sender) and retransmission requests are sent to the sender of a message[14] if that sequence number is not received.

FIFO order means that all messages from a given sender are received in exactly the order in which they were sent.

Table 7.15. Properties

NameDescription
discard_delivered_msgsShould messages delivered to application be discarded
enable_xmit_time_statsIf true, retransmissions stats will be captured. Default is false
exponential_backoffThe first value (in milliseconds) to use in the exponential backoff. Enabled if greater than 0. Default is 0
gc_lagGarbage collection lag
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
levelSets the logger level (see javadocs)
log_discard_msgsdiscards warnings about promiscuous traffic
log_not_found_msgsIf true, trashes warnings about retransmission messages not found in the xmit_table (used for testing)
max_msg_batch_sizeMax number of messages to be removed from a NakReceiverWindow. This property might get removed anytime, so don't use it !
max_rebroadcast_timeoutTimeout to rebroadcast messages. Default is 2000 msec
max_xmit_buf_sizeIf value is > 0, the retransmit buffer is bounded. If value <= 0 unbounded buffers are used. Default is 0
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
print_stability_history_on_failed_xmitShould stability history be printed if we fail in retransmission. Default is false
retransmit_timeoutsTimeout before requesting retransmissions. Default is 600, 1200, 2400, 4800
statsDetermines whether to collect statistics (and expose them via JMX). Default is true
use_mcast_xmitRetransmit messages using multicast rather than unicast
use_mcast_xmit_reqUse a multicast to request retransmission of missing messages. Default is false
use_range_based_retransmitterWhether to use the old retransmitter which retransmits individual messages or the new one which uses ranges of retransmitted messages. Default is true. Note that this property will be removed in 3.0; it is only used to switch back to the old (and proven) retransmitter mechanism if issues occur
use_stats_for_retransmissionUse statistics gathered from actual retransmission times to compute new retransmission times. Default is false
xmit_from_random_memberAsk a random member for retransmission of a missing message. Default is false
xmit_history_max_sizeSize of retransmission history. Default is 50 entries

7.5.2. UNICAST

UNICAST provides reliable delivery and FIFO (= First In First Out) properties for point-to-point messages between one sender and one receiver.

Reliable delivery means that no message sent by a sender will ever be lost, as all messages are numbered with sequence numbers (by sender) and retransmission requests are sent to the sender of a message[15] if that sequence number is not received.

FIFO order means that all messages from a given sender are received in exactly the order in which they were sent.

On top of a reliable transport, such as TCP, UNICAST is not really needed. However, concurrent delivery of messages from the same sender is prevented by UNICAST by acquiring a lock on the sender's retransmission table, so unless concurrent delivery is desired, UNICAST should not be removed from the stack even if TCP is used.

Table 7.16. Properties

NameDescription
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
levelSets the logger level (see javadocs)
loopbackWhether to loop back messages sent to self. Default is false
max_msg_batch_sizeMax number of messages to be removed from the AckReceiverWindow. This property might get removed anytime, so don't use it !
max_retransmit_timeMax number of milliseconds we try to retransmit a message to any given member. After that, the connection is removed. Any new connection to that member will start with seqno #1 again. 0 disables this
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
statsDetermines whether to collect statistics (and expose them via JMX). Default is true

7.6. Fragmentation

7.6.1. FRAG and FRAG2

Table 7.17. Properties

NameDescription
frag_sizeThe max number of bytes in a message. Larger messages will be fragmented. Default is 8192 bytes
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
levelSets the logger level (see javadocs)
max_retained_bufferThe max size in bytes for the byte array output buffer
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
statsDetermines whether to collect statistics (and expose them via JMX). Default is true

7.7. Ordering (FIFO covered by NAKACK)

7.7.1. Total Order (SEQUENCER)

7.8. Group Membership

Group membership takes care of joining new members, handling leave requests by existing members, and handling SUSPECT messages for crashed members, as emitted by failure detection protocols. The algorithm for joining a new member is essentially:

                - loop
                - find initial members (discovery)
                - if no responses:
                - become singleton group and break out of the loop
                - else:
                - determine the coordinator (oldest member) from the responses
                - send JOIN request to coordinator
                - wait for JOIN response
                - if JOIN response received:
                - install view and break out of the loop
                - else
                - sleep for 5 seconds and continue the loop
            

7.8.1. pbcast.GMS

Table 7.18. Properties

NameDescription
disable_initial_coordIf true this member can never become coordinator. Default is false
flushInvokerClass 
handle_concurrent_startupTemporary switch. Default is true and should not be changed
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
join_timeoutJoin timeout. Default is 5000 msec
leave_timeoutLeave timeout. Default is 5000 msec
levelSets the logger level (see javadocs)
log_collect_msgsLogs failures for collecting all view acks if true
max_bundling_timeMax view bundling timeout if view bundling is turned on. Default is 50 msec
merge_timeoutTimeout to complete merge. Default is 10000 msec
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
num_prev_mbrsMax number of old members to keep in history. Default is 50
print_local_addrPrint local address of this member after connect. Default is true
print_physical_addrsPrint physical address(es) on startup
resume_task_timeoutTimeout to resume ViewHandler. Default is 10000 msec
statsDetermines whether to collect statistics (and expose them via JMX). Default is true
use_flush_if_presentUse flush for view changes. Default is true
view_ack_collection_timeoutTime in ms to wait for all VIEW acks (0 == wait forever. Default is 2000 msec
view_bundlingView bundling toggle

7.8.1.1. Disabling the initial coordinator

Consider the following situation: a new member wants to join a group. The prodedure to do so is:

  • Multicast an (unreliable) discovery request (ping)

  • Wait for n responses or m milliseconds (whichever is first)

  • Every member responds with the address of the coordinator

  • If the initial responses are > 0: determine the coordinator and start the JOIN protocolg

  • If the initial response are 0: become coordinator, assuming that no one else is out there

However, the problem is that the initial mcast discovery request might get lost, e.g. when multiple members start at the same time, the outgoing network buffer might overflow, and the mcast packet might get dropped. Nobody receives it and thus the sender will not receive any responses, resulting in an initial membership of 0. This could result in multiple coordinators, and multiple subgroups forming. How can we overcome this problem ? There are 3 solutions:

  1. Increase the timeout, or number of responses received. This will only help if the reason of the empty membership was a slow host. If the mcast packet was dropped, this solution won't help

  2. Add the MERGE(2) protocol. This doesn't actually prevent multiple initial cordinators, but rectifies the problem by merging different subgroups back into one. Note that this involves state merging which needs to be done by the application.

  3. (new) Prevent members from becoming coordinator on initial startup. This solution is applicable when we know which member is going to be the initial coordinator of a fresh group. We don't care about afterwards, then coordinatorship can migrate to another member. In this case, we configure the member that is always supposed to be started first with disable_initial_coord=false (the default) and all other members with disable_initial_coord=true.This works as described below.

When the initial membership is received, and is null, and the property disable_initial_coord is true, then we just continue in the loop and retry receving the initial membership (until it is non-null). If the property is false, we are allowed to become coordinator, and will do so. Note that - if a member is started as first member of a group - but its property is set to true, then it will loop until another member whose disable_initial_coord property is set to false, is started.

7.9. Security

7.9.1. ENCRYPT

Table 7.19. Properties

NameDescription
aliasAlias used for recovering the key. Change the default
asymAlgorithmCipher engine transformation for asymmetric algorithm. Default is RSA
asymInitInitial public/private key length. Default is 512
asymProviderCryptographic Service Provider. Default is Bouncy Castle Provider
encrypt_entire_message 
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
keyPasswordPassword for recovering the key. Change the default
keyStoreNameFile on classpath that contains keystore repository
levelSets the logger level (see javadocs)
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
statsDetermines whether to collect statistics (and expose them via JMX). Default is true
storePasswordPassword used to check the integrity/unlock the keystore. Change the default
symAlgorithmCipher engine transformation for symmetric algorithm. Default is AES
symInitInitial key length for matching symmetric algorithm. Default is 128

7.9.2. AUTH

7.10. State Transfer

7.10.1. pbcast.STATE_TRANSFER

7.10.2. pbcast.STREAMING_STATE_TRANSFER

7.10.2.1. Overview

In order to transfer application state to a joining member of a group pbcast.STATE_TRANSFER has to load entire state into memory and send it to a joining member. Major limitation of this approach is that the state transfer that is very large (>1Gb) would likely result in OutOfMemoryException. In order to alleviate this problem a new state transfer methodology, based on a streaming state transfer, was introduced in JGroups 2.4

Streaming state transfer supports both partial and full state transfer.

Streaming state transfer provides an InputStream to a state reader and an OutputStream to a state writer. OutputStream and InputStream abstractions enable state transfer in byte chunks thus resulting in smaller memory requirements. For example, if application state consists a huge DOM tree, whose aggregate size is 2GB (and which has partly been passivated to disk), then the state provider (ie. the coordinator) can simply iterate over the DOM tree (activating the parts which have been passivated out to disk), and write to the OutputStream as it traverses the tree. The state receiver will simply read from the InputStream and reconstruct the tree on its side, possibly again passivating parts to disk.

Rather than having to provide a 2GB byte[] buffer, streaming state transfer transfers the state in chunks of N bytes where N is user configurable.

Prior to 2.6.9 and 2.8 releases streaming state transfer relied exclusively on its own tcp sockets to transfer state between members. The downside of tcp socket approach is that it is not firewall friendly. If use_default_transport property of pbcast.STREAMING_STATE_TRANSFER is set to true streaming state transfer will use normal messages to transfer state. This approach besides being completely transparent to application is also firewall friendly. However, as expected, tcp sockets have better performance.

7.10.2.2. API

Streaming state transfer, just as regular byte based state transfer, can be used in both pull and push mode. Similarly to the current getState and setState methods of org.jgroups.MessageListener, application interested in streaming state transfer in a push mode would implement streaming getState method(s) by sending/writing state through a provided OutputStream reference and setState method(s) by receiving/reading state through a provided InputStream reference. In order to use streaming state transfer in a push mode, existing ExtendedMessageListener has been expanded to include additional four methods:

                        public interface ExtendedMessageListener
                        {

                        /*non-streaming callback methods ommitted for clarity*/


                        /**
                        * Allows an application to write a state through a provided OutputStream.
                        * An application is obligated to always close the given OutputStream reference.
                        *
                        * @param ostream the OutputStream
                        * @see OutputStream#close()
                        */
                        public void getState(OutputStream ostream);

                        /**
                        * Allows an application to write a partial state through a provided OutputStream.
                        * An application is obligated to always close the given OutputStream reference.
                        *
                        * @param state_id id of the partial state requested
                        * @param ostream the OutputStream
                        *
                        * @see OutputStream#close()
                        */
                        public void getState(String state_id, OutputStream ostream);


                        /**
                        * Allows an application to read a state through a provided InputStream.
                        * An application is obligated to always close the given InputStream reference.
                        *
                        * @param istream the InputStream
                        * @see InputStream#close()
                        */
                        public void setState(InputStream istream);

                        /**
                        * Allows an application to read a partial state through a provided InputStream.
                        * An application is obligated to always close the given InputStream reference.
                        *
                        * @param state_id id of the partial state requested
                        * @param istream the InputStream
                        *
                        * @see InputStream#close()
                        */
                        public void setState(String state_id, InputStream istream);

                        }
                    

For a pull mode (when application uses channel.receive() to fetch events) two new event classes will be introduced:

  • StreamingGetStateEvent

  • StreamingSetStateEvent

These two events/classes are very similar to existing GetStateEvent and SetStateEvent but introduce a new field; StreamingGetStateEvent has an OutputStream and StreamingSetStateEvent has an InputStream.

The following code snippet demonstrates how to pull events from a channel, processing StreamingGetStateEvent and sending hypothetical state through a provided OutputStream reference. Handling of StreamingSetStateEvent is analogous to this example:

...
                    Object obj=channel.receive(0);
                    if(obj instanceof StreamingGetStateEvent) {
                    StreamingGetStateEvent evt=(StreamingGetStateEvent)obj;
                    OutputStream oos = null;
                    try {
                    oos = new ObjectOutputStream(evt.getArg());
                    oos.writeObject(state);
                    oos.flush();
                    } catch (Exception e) {}
                    finally{
                    try {
                    oos.close();
                    } catch (IOException e) {
                    System.err.println(e);
                    }
                    }
                    }
                    ...
                

API that initiates state transfer on a JChannel level has the following methods:

public boolean getState(Address target,long timeout)throws
                        ChannelNotConnectedException,ChannelClosedException;
                        public boolean getState(Address target,String state_id,long timeout)throws
                        ChannelNotConnectedException,ChannelClosedException;
                    

Introduction of STREAMING_STATE_TRANSFER does not change the current API.

7.10.2.3. Configuration

State transfer type choice is static, implicit and mutually exclusive. JChannel cannot use both STREAMING_STATE_TRANSFER and STATE_TRANSFER in one JChannel configuration.

STREAMING_STATE_TRANSFER allows the following confguration parameters:

Table 7.20. Properties

NameDescription
bind_addrThe interface (NIC) used to accept state requests. The following special values are also recognized: GLOBAL, SITE_LOCAL, LINK_LOCAL and NON_LOOPBACK
bind_interface_strThe interface (NIC) which should be used by this transport
bind_portThe port listening for state requests. Default value of 0 binds to any (ephemeral) port
buffer_queue_sizeIf default transport is used the total state buffer size before state producer is blocked. Default is 81920 bytes
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
levelSets the logger level (see javadocs)
max_poolMaximum number of pool threads serving state requests. Default is 5
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
pool_thread_keep_aliveKeep alive for pool threads serving state requests. Default is 20000 msec
socket_buffer_sizeBuffer size for state transfer. Default is 8192 bytes
statsDetermines whether to collect statistics (and expose them via JMX). Default is true
use_default_transportIf true default transport is used for state transfer rather than seperate TCP sockets. Default is false

7.10.2.4. Other considerations

Threading model used for state writing in a member providing state and state reading in a member receiving a state is tunable. For state provider thread pool is used to spawn threads providing state. Thus member providing state, in a push mode, will be able to concurrently serve N state requests where N is max_threads configuration parameter of the thread pool. If there are no further state transfer requests pool threads will be automatically reaped after configurable "pool_thread_keep_alive" timeout expires. For a channel operating in the push mode state reader channel can read state by piggybacking on jgroups protocol stack thread or optionally use a separate thread. State reader should use a separate thread if state reading is expensive (eg. large state, serialization) thus potentially affecting liveness of jgroups protocol thread. Since most state transfers are very short (<2-3 sec) by default we do not use a separate thread.

7.11. Flow control

Flow control takes care of adjusting the rate of a message sender to the rate of the slowest receiver over time. If a sender continuously sends messages at a rate that is faster than the receiver(s), the receivers will either queue up messages, or the messages will get discarded by the receiver(s), triggering costly retransmissions. In addition, there is spurious traffic on the cluster, causing even more retransmissions.

Flow control throttles the sender so the receivers are not overrun with messages.

7.11.1. FC

FC uses a credit based system, where each sender has max_credits credits and decrements them whenever a message is sent. The sender blocks when the credits fall below 0, and only resumes sending messages when it receives a replenishment message from the receivers.

The receivers maintain a table of credits for all senders and decrement the given sender's credits as well, when a message is received.

When a sender's credits drops below a threshold, the receiver will send a replenishment message to the sender. The threshold is defined by min_bytes or min_threshold.

Table 7.21. Properties

NameDescription
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
ignore_synchronous_responseDoes not block a down message if it is a result of handling an up message in thesame thread. Fixes JGRP-928
levelSets the logger level (see javadocs)
max_block_timeMax time (in milliseconds) to block. Default is 5000 msec
max_block_timesMax times to block for the listed messages sizes (Message.getLength()). Example: "1000:10,5000:30,10000:500"
max_creditsMax number of bytes to send per receiver until an ack must be received to proceed. Default is 500000 bytes
min_creditsComputed as max_credits x min_theshold unless explicitly set
min_thresholdIf credits (bytes) used so far fall below this limit, we send more credits to the sender
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
statsDetermines whether to collect statistics (and expose them via JMX). Default is true

7.11.2. SFC

A simplified version of FC. FC can actually still overrun receivers when the transport's latency is very small. SFC is a simple flow control protocol for group (= multipoint) messages.

Every sender has max_credits bytes for sending multicast messages to the group.

Every multicast message (we don't consider unicast messages) decrements max_credits by its size. When max_credits falls below 0, the sender asks all receivers for new credits and blocks until *all* credits have been received from all members.

When the receiver receives a credit request, it checks whether it has received max_credits bytes from the requester since the last credit request. If yes, it sends new credits to the requester and resets the max_credits for the requester. Else, it takes a note of the credit request from P and - when max_credits bytes have finally been received from P - it sends the credits to P and resets max_credits for P.

The maximum amount of memory for received messages is therefore <number of senders> * max_credits.

The relationship with STABLE is as follows: when a member Q is slow, it will prevent STABLE from collecting messages above the ones seen by Q (everybody else has seen more messages). However, because Q will *not* send credits back to the senders until it has processed all messages worth max_credits bytes, the senders will block. This in turn allows STABLE to progress and eventually garbage collect most messages from all senders. Therefore, SFC and STABLE complement each other, with SFC blocking senders so that STABLE can catch up.

Table 7.22. Properties

NameDescription
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
levelSets the logger level (see javadocs)
max_block_timeMax time (in milliseconds) to block. Default is 5000 msec
max_creditsMax number of bytes to send per receiver until an ack must be received to proceed. Default is 2000000 bytes
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
statsDetermines whether to collect statistics (and expose them via JMX). Default is true

7.12. Message stability

To serve potential retransmission requests, a member has to store received messages until it is known that every member in the cluster has received them. Message stability for a given message M means that M has been seen by everyone in the cluster.

The stability protocol periodically (or when a certain number of bytes have been received) initiates a consensus protocol, which multicasts a stable message containing the highest message numbers for a given member. This is called a digest.

When everyone has received everybody else's stable messages, a digest is computed which consists of the minimum sequence numbers of all received digests so far. This is the stability vector, and contain only message sequence numbers that have been seen by everyone.

This stability vector is the broadcast to the group and everyone can remove messages from their retransmission tables whose sequence numbers are smaller than the ones received in the stability vector. These messages can then be garbage collected.

7.12.1. STABLE

Table 7.23. Properties

NameDescription
desired_avg_gossipAverage time to send a STABLE message. Default is 20000 msec
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
levelSets the logger level (see javadocs)
max_bytesMaximum number of bytes received in all messages before sending a STABLE message is triggered. Default is 0 (disabled)
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
stability_delayDelay before stability message is sent. Default is 6000 msec
statsDetermines whether to collect statistics (and expose them via JMX). Default is true

7.13. Misc

7.13.1. COMPRESS

Table 7.24. Properties

NameDescription
compression_levelCompression level 0-9 (0=no compression, 9=best compression). Default is 9
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
levelSets the logger level (see javadocs)
min_sizeMinimal payload size of a message (in bytes) for compression to kick in. Default is 500 bytes
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
pool_sizeNumber of inflaters/deflaters for concurrent processing. Default is 2
statsDetermines whether to collect statistics (and expose them via JMX). Default is true

7.13.2. pbcast.FLUSH

Flushing forces group members to send all their pending messages prior to a certain event. The process of flushing acquiesces the cluster so that state transfer or a join can be done. It is also called the stop-the-world model as nobody will be able to send messages while a flush is in process. Flush is used:

  • State transfer

    When a member requests state transfer it 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 requester 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.

FLUSH is designed as another protocol positioned just below the channel, e.g. above STATE_TRANSFER and FC. STATE_TRANSFER and GMS protocol request flush by sending a SUSPEND event up the stack, where it is handled by the FLUSH protcol. The SUSPEND_OK ack sent back by the FLUSH protocol let's the caller know that the flush has completed. When done (e.g. view was installed or state transferred), the protocol sends up a RESUME event, which will allow everyone in the cluster to resume sending.

Channel can be notified that FLUSH phase has been started by turning channel block option on. By default it is turned off. If channel blocking is turned on FLUSH notifies application layer that channel has been blocked by sending EVENT.BLOCK event. Channel responds by sending EVENT.BLOCK_OK event down to FLUSH protocol. We recommend turning on channel block notification only if channel is used in push mode. In push mode application that uses channel can perform block logic by implementing MembershipListener.block() callback method.

Table 7.25. Properties

NameDescription
enable_reconciliationReconciliation phase toggle. Default is true
end_flush_timeoutTimeout to wait for UNBLOCK after STOP_FLUSH is issued. Default is 2000 msec
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
levelSets the logger level (see javadocs)
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
retry_timeoutRetry timeout after an unsuccessful attempt to quiet the cluster (first flush phase). Default is 3000 msec
start_flush_timeoutTimeout (per atttempt) to quiet the cluster during the first flush phase. Default is 2000 msec
statsDetermines whether to collect statistics (and expose them via JMX). Default is true
timeoutMax time to keep channel blocked in flush. Default is 8000 msec

7.13.3. SCOPE

As discussed in Section 5.4.4, “Scopes: concurrent message delivery for messages from the same sender”, the SCOPE protocol is used to deliver updates to different scopes concurrently. It has to be placed somewhere above UNICAST and NAKACK.

SCOPE has a separate thread pool. The reason why the default thread pool from the transport wasn't used is that the default thread pool has a different purpose. For example, it can use a queue to which all incoming messages are added, which would defy the purpose of concurrent delivery in SCOPE. As a matter of fact, using a queue would most likely delay messages get sent up into SCOPE !

Also, the default pool's rejection policy might not be "run", so the SCOPE implementation would have to catch rejection exceptions and engage in a retry protocol, which is complex and wastes resources.

The configuration of the thread pool is shown below. If you expect concurrent messages to N different scopes, then the max pool size would ideally be set to N. However, in most cases, this is not necessary as (a) the messages might not be to different scopes or (b) not all N scopes might get messages at the same time. So even if the max pool size is a bit smaller, the cost of this is slight delays, in the sense that a message for scope Y might wait until the thread processing message for scope X is available.

To remove unused scopes, an expiry policy is provided: expiration_time is the number of milliseconds after which an idle scope is removed. An idle scope is a scope which hasn't seen any messages for expiration_time milliseconds. The expiration_interval value defines the number of milliseconds at which the expiry task runs. Setting both values to 0 disables expiration; it would then have to be done manually (see Section 5.4.4, “Scopes: concurrent message delivery for messages from the same sender” for details).

Table 7.26. Properties (experimental)

NameDescription
expiration_intervalInterval in milliseconds at which the expiry task tries to remove expired scopes
expiration_timeTime in milliseconds after which an expired scope will get removed. An expired scope is one to which no messages have been added in max_expiration_time milliseconds. 0 never expires scopes
idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
levelSets the logger level (see javadocs)
nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
statsDetermines whether to collect statistics (and expose them via JMX). Default is true
thread_naming_patternThread naming pattern for threads in this channel. Default is cl
thread_pool.keep_alive_timeTimeout in milliseconds to remove idle thread from regular pool
thread_pool.max_threadsMaximum thread pool size for the regular thread pool
thread_pool.min_threadsMinimum thread pool size for the regular thread pool


[14] Note that NAKACK can also be configured to send retransmission requests for M to anyone in the cluster, rather than only to the sender of M.