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 and maintain, for each node, a latency score (an average). Based on those 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 delay 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 grow over the exclusion threshold), its latency score will not evolve anymore (since it is not queried). To give a chance to those 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 paramters of this policy.

Since:

1.0.4

Nested Class Summary

static class

LatencyAwarePolicy.Builder Helper builder object to create a latency aware policy.

Method Summary

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) Return the HostDistance for the provided host.
void	init(Cluster cluster, Collection<Host> hosts) Initialize this load balancing policy.
Iterator<Host>	newQueryPlan(Query query) 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)

Return 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(Query query)

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 initally excluded due to their latency will be returned by the returned iterator, but only only after all non-excluded host of the child policy have been returned.

Specified by:

newQueryPlan in interface LoadBalancingPolicy

Parameters:

query - the query 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.