com.twitter.common.net.loadbalancing
Interface LoadBalancer<K>

All Superinterfaces:
RequestTracker<K>
All Known Implementing Classes:
LoadBalancerImpl

public interface LoadBalancer<K>
extends RequestTracker<K>

A load balancer, which will be used to determine which of a set of backends should be connected to for service calls. It is expected that the backends themselves can be changed at any time, and the load balancer should immediately restrict itself to using only those backends. It is likely that the load balancer implementation will periodically receive information about backends that it technically should no longer know about. An example is calls to RequestTracker.requestResult(Object, RequestResult, long) and released(Object) for in-flight requests after backends were changed by offerBackends(Set, Closure).


Nested Class Summary
 
Nested classes/interfaces inherited from interface com.twitter.common.net.loadbalancing.RequestTracker
RequestTracker.RequestResult
 
Method Summary
 void connected(K backend, long connectTimeNanos)
          Signals the load balancer that a connection was made.
 void connectFailed(K backend, LoadBalancingStrategy.ConnectionResult result)
          Signals the load balancer that a connection was attempted, but failed.
 K nextBackend()
          Gets the next backend that a request should be sent to.
 void offerBackends(Set<K> offeredBackends, Closure<Collection<K>> onBackendsChosen)
          Offers a set of backends that the load balancer should choose from to distribute load amongst.
 void released(K connection)
          Signals the load balancer that a connection was released, and is idle.
 
Methods inherited from interface com.twitter.common.net.loadbalancing.RequestTracker
requestResult
 

Method Detail

offerBackends

void offerBackends(Set<K> offeredBackends,
                   Closure<Collection<K>> onBackendsChosen)
Offers a set of backends that the load balancer should choose from to distribute load amongst.

Parameters:
offeredBackends - Backends to choose from.
onBackendsChosen - A callback that should be notified when the offered backends have been (re)chosen from.

nextBackend

K nextBackend()
              throws ResourceExhaustedException
Gets the next backend that a request should be sent to.

Returns:
Next backend to send a request.
Throws:
ResourceExhaustedException - If there are no available backends.

connected

void connected(K backend,
               long connectTimeNanos)
Signals the load balancer that a connection was made.

Parameters:
backend - The backend that was connected to.
connectTimeNanos - The time spent waiting for the connection to be established.

connectFailed

void connectFailed(K backend,
                   LoadBalancingStrategy.ConnectionResult result)
Signals the load balancer that a connection was attempted, but failed.

Parameters:
backend - The backend to which connection attempt was made.
result - The result of the connection attempt (only FAILED and TIMEOUT are permitted).

released

void released(K connection)
Signals the load balancer that a connection was released, and is idle.

Parameters:
connection - Idle connection.