com.datastax.driver.core.policies

Class LatencyAwarePolicy

java.lang.Object

com.datastax.driver.core.policies.LatencyAwarePolicy

All Implemented Interfaces:

Host.StateListener, LoadBalancingPolicy

public class LatencyAwarePolicy
extends Object
implements LoadBalancingPolicy

A wrapper load balancing policy that adds latency awareness to a child policy.

When used, this policy will collect the latencies of the queries to each Cassandra node and maintain a per-node latency score (an average). Based on these scores, the policy will penalize (technically, it will ignore them unless no other nodes are up) the nodes that are slower than the best performing node by more than some configurable amount (the exclusion threshold).

The latency score for a given node is a based on a form of exponential moving average. In other words, the latency score of a node is the average of its previously measured latencies, but where older measurements gets an exponentially decreasing weight. The exact weight applied to a newly received latency is based on the time elapsed since the previous measure (to account for the fact that latencies are not necessarily reported with equal regularity, neither over time nor between different nodes).

Once a node is excluded from query plans (because its averaged latency grew over the exclusion threshold), its latency score will not be updated anymore (since it is not queried). To give a chance to this node to recover, the policy has a configurable retry period. The policy will not penalize a host for which no measurement has been collected for more than this retry period.

Please see the LatencyAwarePolicy.Builder class and methods for more details on the possible parameters of this policy.

Since:

1.0.4

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	LatencyAwarePolicy.Builder Helper builder object to create a latency aware policy.

Method Summary

Methods

Modifier and Type	Method and Description
static LatencyAwarePolicy.Builder	builder(LoadBalancingPolicy childPolicy) Creates a new latency aware policy builder given the child policy that the resulting policy should wrap.
HostDistance	distance(Host host) Returns the HostDistance for the provided host.
void	init(Cluster cluster, Collection<Host> hosts) Initialize this load balancing policy.
Iterator<Host>	newQueryPlan(String loggedKeyspace, Statement statement) Returns the hosts to use for a new query.
void	onAdd(Host host) Called when a new node is added to the cluster.
void	onDown(Host host) Called when a node is determined to be down.
void	onRemove(Host host) Called when a node is removed from the cluster.
void	onUp(Host host) Called when a node is determined to be up.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

builder

public static LatencyAwarePolicy.Builder builder(LoadBalancingPolicy childPolicy)

Creates a new latency aware policy builder given the child policy that the resulting policy should wrap.

Parameters:

childPolicy - the load balancing policy to wrap with latency awareness.

Returns:

the created builder.

init

public void init(Cluster cluster,
        Collection<Host> hosts)

Description copied from interface: LoadBalancingPolicy

Initialize this load balancing policy.

Note that the driver guarantees that it will call this method exactly once per policy object and will do so before any call to another of the methods of the policy.

Specified by:

init in interface LoadBalancingPolicy

Parameters:

cluster - the Cluster instance for which the policy is created.

hosts - the initial hosts to use.

distance

public HostDistance distance(Host host)

Returns the HostDistance for the provided host.

Specified by:

distance in interface LoadBalancingPolicy

Parameters:

host - the host of which to return the distance of.

Returns:

the HostDistance to host as returned by the wrapped policy.

newQueryPlan

public Iterator<Host> newQueryPlan(String loggedKeyspace,
                          Statement statement)

Returns the hosts to use for a new query.

The returned plan will be the same as the plan generated by the child policy, but with the (initial) exclusion of hosts whose recent (averaged) latency is more than exclusionThreshold * minLatency (where minLatency is the (averaged) latency of the fastest host).

The hosts that are initially excluded due to their latency will be returned by this iterator, but only only after all non-excluded hosts of the child policy have been returned.

Specified by:

newQueryPlan in interface LoadBalancingPolicy

Parameters:

loggedKeyspace - the currently logged keyspace.

statement - the statement for which to build the plan.

Returns:

the new query plan.

onUp

public void onUp(Host host)

Description copied from interface: Host.StateListener

Called when a node is determined to be up.

Specified by:

onUp in interface Host.StateListener

Parameters:

host - the host that has been detected up.

onDown

public void onDown(Host host)

Description copied from interface: Host.StateListener

Called when a node is determined to be down.

Specified by:

onDown in interface Host.StateListener

Parameters:

host - the host that has been detected down.

onAdd

public void onAdd(Host host)

Description copied from interface: Host.StateListener

Called when a new node is added to the cluster.

The newly added node should be considered up.

Specified by:

onAdd in interface Host.StateListener

Parameters:

host - the host that has been newly added.

onRemove

public void onRemove(Host host)

Description copied from interface: Host.StateListener

Called when a node is removed from the cluster.

Specified by:

onRemove in interface Host.StateListener

Parameters:

host - the removed host.