com.twitter.common.net.pool
Class MetaPool<T,E>

java.lang.Object
  extended by com.twitter.common.net.pool.MetaPool<T,E>
All Implemented Interfaces:
ObjectPool<Connection<T,E>>

public class MetaPool<T,E>
extends Object
implements ObjectPool<Connection<T,E>>

A connection pool that picks connections from a set of backend pools. Backend pools are selected from randomly initially but then as they are used they are ranked according to how many connections they have available and whether or not the last used connection had an error or not. In this way, backends that are responsive should get selected in preference to those that are not.

Non-responsive backends are monitored after a configurable period in a background thread and if a connection can be obtained they start to float back up in the rankings. In this way, backends that are initially non-responsive but later become responsive should end up getting selected.

TODO(John Sirois): take a ShutdownRegistry and register a close command


Field Summary
 
Fields inherited from interface com.twitter.common.net.pool.ObjectPool
NO_TIMEOUT
 
Constructor Summary
MetaPool(ImmutableMap<E,ObjectPool<Connection<T,E>>> backends, LoadBalancer<E> loadBalancer, Closure<Collection<E>> onBackendsChosen, Amount<Long,Time> restoreInterval)
          Creates a connection pool that balances connections across multiple backend pools.
MetaPool(LoadBalancer<E> loadBalancer, Closure<Collection<E>> onBackendsChosen, Amount<Long,Time> restoreInterval)
          Creates a connection pool with no backends.
 
Method Summary
 void close()
          Disallows further gets from this pool, "closes" all idle objects and any outstanding objects when they are released.
 Connection<T,E> get()
          Gets a resource potentially blocking for as long as it takes to either create a new one or wait for one to be released.
 Connection<T,E> get(Amount<Long,Time> timeout)
          Gets a resource; timing out if there are none available and it takes longer than specified to create a new one or wait for one to be released.
 void release(Connection<T,E> connection)
          Releases a resource obtained from this pool back into the pool of available resources.
 void remove(Connection<T,E> connection)
          Equivalent to releasing a Connection with isValid() == false.
 void setBackends(Map<E,ObjectPool<Connection<T,E>>> pools)
          Assigns the backend pools that this pool should draw from.
protected  void stop()
          Stops dead backend restoration attempts.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MetaPool

public MetaPool(LoadBalancer<E> loadBalancer,
                Closure<Collection<E>> onBackendsChosen,
                Amount<Long,Time> restoreInterval)
Creates a connection pool with no backends. Backends may be added post-creation by calling #setBackends();

Parameters:
loadBalancer - the load balancer to distribute requests among backends.
onBackendsChosen - a callback to notify whenever the loadBalancer chooses a new set of backends to restrict its call distribution to
restoreInterval - the interval after a backend goes dead to begin checking the backend to see if it has come back to a healthy state

MetaPool

public MetaPool(ImmutableMap<E,ObjectPool<Connection<T,E>>> backends,
                LoadBalancer<E> loadBalancer,
                Closure<Collection<E>> onBackendsChosen,
                Amount<Long,Time> restoreInterval)
Creates a connection pool that balances connections across multiple backend pools.

Parameters:
backends - the connection pools for the backends
onBackendsChosen - a callback to notify whenever the loadBalancer chooses a new set of backends to restrict its call distribution to
loadBalancer - the load balancer to distribute requests among backends.
restoreInterval - the interval after a backend goes dead to begin checking the backend to see if it has come back to a healthy state
Method Detail

setBackends

public void setBackends(Map<E,ObjectPool<Connection<T,E>>> pools)
Assigns the backend pools that this pool should draw from.

Parameters:
pools - New pools to use.

get

public Connection<T,E> get()
                    throws ResourceExhaustedException,
                           TimeoutException
Description copied from interface: ObjectPool
Gets a resource potentially blocking for as long as it takes to either create a new one or wait for one to be released. Callers must release the connection when they are done with it.

Specified by:
get in interface ObjectPool<Connection<T,E>>
Returns:
a resource for exclusive use by the caller
Throws:
ResourceExhaustedException - if no resource could be obtained because this pool was exhausted
TimeoutException - if we timed out while trying to fetch a resource

get

public Connection<T,E> get(Amount<Long,Time> timeout)
                    throws ResourceExhaustedException,
                           TimeoutException
Description copied from interface: ObjectPool
Gets a resource; timing out if there are none available and it takes longer than specified to create a new one or wait for one to be released. Callers must (Object) release the connection when they are done with it.

Specified by:
get in interface ObjectPool<Connection<T,E>>
Parameters:
timeout - the maximum amount of time to wait
Returns:
a resource for exclusive use by the caller
Throws:
ResourceExhaustedException - if no resource could be obtained because this pool was exhausted
TimeoutException - if the specified timeout was reached before a resource became available

release

public void release(Connection<T,E> connection)
Description copied from interface: ObjectPool
Releases a resource obtained from this pool back into the pool of available resources. It is an error to release a resource not obtained from this pool.

Specified by:
release in interface ObjectPool<Connection<T,E>>
Parameters:
connection - Resource to release.

remove

public void remove(Connection<T,E> connection)
Equivalent to releasing a Connection with isValid() == false.

Specified by:
remove in interface ObjectPool<Connection<T,E>>
Parameters:
connection - Resource to remove.
See Also:
ObjectPool#remove(Object)}

close

public void close()
Description copied from interface: ObjectPool
Disallows further gets from this pool, "closes" all idle objects and any outstanding objects when they are released.

Specified by:
close in interface ObjectPool<Connection<T,E>>

stop

protected final void stop()
Stops dead backend restoration attempts.

TODO(John Sirois): stop functionality is needed to properly implement a close that frees all pool resources; however having to expose it for subclasses is a hack that solely supports ServerSetConnectionPool - this might be made cleaner by injecting the dead pool restorer instead.