multicast-listener

multicast-listener

Used in: cluster-config.

Description

Specifies the configuration information for the Multicast listener. This element is used to specify the address and port that a cluster will use for cluster wide and point-to-multipoint communications. All nodes in a cluster must use the same multicast address and port, whereas distinct clusters on the same network should use different multicast addresses.

Multicast-Free Clustering

By default Coherence uses a multicast protocol to discover other nodes when forming a cluster. If multicast networking is undesirable, or unavailable in your environment, the well-known-addresses feature may be used to eliminate the need for multicast traffic. If you are having difficulties in establishing a cluster via multicast, see the Multicast Test.

Elements

The following table describes the elements you can define within the multicast-listener element.

Element Required/Optional Description
<address> Required Specifies the multicast IP address that a Socket will listen or publish on.

Legal values are from 224.0.0.0 to 239.255.255.255.

Default value depends on the release and build level and typically follows the convention of {build}.{major version}.{minor version}.{patch}. For example, for Coherence Release 2.2 build 255 it is 225.2.2.0.

Preconfigured override is tangosol.coherence.clusteraddress
<port> Required Specifies the port that the Socket will listen or publish on.

Legal values are from 1 to 65535.

Default value depends on the release and build level and typically follows the convention of {version}+{{{build}. For example, for Coherence Release 2.2 build 255 it is 22255.

Preconfigured override is tangosol.coherence.clusterport
<time-to-live> Required Specifies the time-to-live setting for the multicast. This determines the maximum number of "hops" a packet may traverse, where a hop is measured as a traversal from one network segment to another via a router.

Legal values are from from 0 to 255.
For production use, this value should be set to the lowest integer value that works. On a single server cluster, it should work at 0; on a simple switched backbone, it should work at 1; on an advanced backbone with intelligent switching, it may require a value of 2 or more. Setting the value too high can use unnecessary bandwidth on other LAN segments and can even cause the OS or network devices to disable multicast traffic. While a value of 0 is meant to keep packets from leaving the originating machine, some OSs do not implement this correctly, and the packets may in fact be transmitted on the network.

Default value is 4.

Preconfigured override is tangosol.coherence.ttl
<packet-buffer> Required Specifies how many incoming packets the OS will be requested to buffer.
<priority> Required Specifies a priority of the multicast listener execution thread.

Legal values are from 1 to 10.

Default value is 8.
<join-timeout-milliseconds> Required Specifies the number of milliseconds that a new member will wait without finding any evidence of a cluster before starting its own cluster and electing itself as the senior cluster member.

Legal values are from 1 to 1000000.

Note: For production use, the recommended value is 30000.

Default value is 6000.
<multicast-threshold-percent> Required Specifies the threshold percentage value used to determine whether a packet will be sent via unicast or multicast. It is a percentage value and is in the range of 1% to 100%. In a cluster of "n" nodes, a particular node sending a packet to a set of other (i.e. not counting self) destination nodes of size "d" (in the range of 0 to n-1), the packet will be sent multicast if and only if the following both hold true:

  1. The packet is being sent over the network to more than one other node, i.e. (d > 1).
  2. The number of nodes is greater than the threshold,i.e. (d > (n-1) * (threshold/100)).

    Setting this value to 1 will allow the implementation to use multicast for basically all multi-point traffic. Setting it to 100 will force the implementation to use unicast for all multi-point traffic except for explicit broadcast traffic (e.g. cluster heartbeat and discovery) because the 100% threshold will never be exceeded. With the setting of 25 the implementation will send the packet using unicast if it is destined for less than one-fourth of all nodes, and send it using multicast if it is destined for the one-fourth or more of all nodes.

    Note: This element is only used if the well-known-addresses element is empty.

    Legal values are from 1 to 100.

    Default value is 25.

The content override attribute xml-override can be optionally used to fully or partially override the contents of this element with XML document that is external to the base document.