co.cask.tephra.distributed

Class ElasticPool<T,E extends Exception>

java.lang.Object

co.cask.tephra.distributed.ElasticPool<T,E>

Type Parameters:

T - the type of the elements

E - the type of exception thrown by create()

public abstract class ElasticPool<T,E extends Exception>
extends Object

An Elastic Pool is an object pool that can dynamically shrink and grow. Normally, an element is obtained by a client and then returned to the pool after use. However, if the element gets into a bad state, the client can also discard the element. This will cause the element to be removed from the pool, and for a subsequent request, a new element can be created on the fly to replace the discarded one. The pool starts with zero (active) elements. Every time a client attempts to obtain an element, an element from the pool is returned if available. Otherwise, if the number of active elements is less than the pool's limit, a new element is created (using abstract method create(), this must be overridden by all implementations), and the number of active elements is increased by one. If the limit is reached, then obtain() blocks until either an element is returned to the pool, or an element is discarded, allowing for the creation of a new element. Every time an element is discarded, it is "destroyed" in order to properly release all it resources before discarding. Every time an element is returned to the pool, it is "recycled" to restore its fresh state for the next use.

Constructor Summary

Constructors

Constructor and Description
ElasticPool(int sizeLimit)

Method Summary

Methods

Modifier and Type	Method and Description
protected abstract T	create() A method to create a new element.
protected void	destroy(T element) A method to destroy an element.
void	discard(T element) Discard an element from the pool.
T	obtain() Get a element from the pool.
protected void	recycle(T element) A method to recycle an existing element when it is returned to the pool.
void	release(T element) Returns an element to the pool of available elements.

Methods inherited from class java.lang.Object

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

Constructor Detail

ElasticPool

public ElasticPool(int sizeLimit)

Method Detail

create

protected abstract T create()
                     throws E extends Exception

A method to create a new element. Will be called every time the pool of available elements is empty but the limit of active elements is not exceeded.

Returns:

a new element

Throws:

E extends Exception

destroy

protected void destroy(T element)

A method to destroy an element. This gets called every time an element is discarded, to properly release all resources that the element might hold.

Parameters:

element - the element to destroy

recycle

protected void recycle(T element)

A method to recycle an existing element when it is returned to the pool. This methods ensures that the element is in a fresh state before it can be reused by the next agent.

Parameters:

element - the element to recycle

obtain

public T obtain()
         throws E extends Exception

Get a element from the pool. If there is an available element in the pool, it will be returned. Otherwise, if the number of active elements does ot exceed the limit, a new element is created with create() and returned. Otherwise, blocks until an element is either released and returned to the pool, or an element is discarded, allowing for the creation of a new element.

Returns:

an element

Throws:

E extends Exception

release

public void release(T element)

Returns an element to the pool of available elements. The element must have been obtained from this pool through obtain(). The recycle() method is called before the element is available for obtain().

Parameters:

element - the element to be returned

discard

public void discard(T element)

Discard an element from the pool. The element must have been obtained from this pool. The destroy() method will be called. This decreases the number of active elements, allowing for subsequent creation of a new one.

Parameters:

element -