voldemort.utils.pool
Class KeyedResourcePool<K,V>

java.lang.Object
  voldemort.utils.pool.KeyedResourcePool<K,V>

Direct Known Subclasses:

QueuedKeyedResourcePool

public class KeyedResourcePool<K,V>
extends java.lang.Object

A simple implementation of a per-key resource pool.

• blocks if resource is not available.
• allocates resources in FIFO order
• Pools are per key and there is no global maximum pool limit.

Invariants that this implementation does not guarantee:

• A checked in resource was previously checked out. (I.e., user can use ResourceFactory and then check in a resource that this pool did not create.)
• A checked out resource is checked in at most once. (I.e., a user does not call check in on a checked out resource more than once.)
• User no longer has a reference to a checked in resource. (I.e., user can keep using the resource after it invokes check in.)
• A resource that is checked out is eventually either checked in or destroyed via objectFactory.destroy(). (I.e., a user can squat on a resource or let its reference to the resource lapse without checking the resource in or destroying the resource.)

Phrased differently, the following is expected of the user of this class:

• A checked out resource is checked in exactly once.
• A resource that is checked in was previously checked out.
• A resource that is checked in is never used again. / No reference is retained to a checked in resource.
• Also, checkout is never called after close.

Nested Class Summary

protected static class

KeyedResourcePool.Pool<V> A fixed size pool that uses an ArrayBlockingQueue.

Constructor Summary

KeyedResourcePool(ResourceFactory<K,V> objectFactory, ResourcePoolConfig resourcePoolConfig)

Method Summary

protected V	attemptNonBlockingCheckout(K key, KeyedResourcePool.Pool<V> pool) Get a free resource if one exists.
void	checkin(K key, V resource) Check the given resource back into the pool
protected void	checkNotClosed() Check that the pool is not closed, and throw an IllegalStateException if it is.
V	checkout(K key) Checkout a resource if one is immediately available.
void	close() Close the pool.
static <K,V> KeyedResourcePool<K,V>	create(ResourceFactory<K,V> factory) Create a new pool using the defaults
static <K,V> KeyedResourcePool<K,V>	create(ResourceFactory<K,V> factory, ResourcePoolConfig config) Create a new pool
protected void	destroyResource(K key, KeyedResourcePool.Pool<V> resourcePool, V resource)
int	getBlockingGetsCount() Count the total number of blocking gets across all pools.
int	getBlockingGetsCount(K key) Count the number of blocking gets for a specific key.
int	getCheckedInResourceCount() Count the total number of checked in (idle) resources across all pools.
int	getCheckedInResourcesCount(K key) Count the number of checked in (idle) resources for a specific pool.
protected KeyedResourcePool.Pool<V>	getResourcePoolForExistingKey(K key) Get the pool for the given key.
protected KeyedResourcePool.Pool<V>	getResourcePoolForKey(K key) Get the pool for the given key.
int	getTotalResourceCount() Count the total number of existing resources for all pools.
int	getTotalResourceCount(K key) Count the number of existing resources for a specific pool.
protected boolean	internalClose()
protected boolean	isOpenAndValid(K key, V resource)
void	reset(K key) Reset a specific resource pool.

Methods inherited from class java.lang.Object

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

Constructor Detail

KeyedResourcePool

public KeyedResourcePool(ResourceFactory<K,V> objectFactory,
                         ResourcePoolConfig resourcePoolConfig)

Method Detail

create

public static <K,V> KeyedResourcePool<K,V> create(ResourceFactory<K,V> factory,
                                                  ResourcePoolConfig config)

Create a new pool

Type Parameters:

K - The type of the keys

V - The type of the values

Parameters:

factory - The factory that creates objects

config - The pool config

Returns:

The created pool

create

public static <K,V> KeyedResourcePool<K,V> create(ResourceFactory<K,V> factory)

Create a new pool using the defaults

Type Parameters:

K - The type of the keys

V - The type of the values

Parameters:

factory - The factory that creates objects

Returns:

The created pool

checkout

public V checkout(K key)
           throws java.lang.Exception

Checkout a resource if one is immediately available. If none is available and we have created fewer than the max size resources, then create a new one. If no resources are available and we are already at the max size then block for up to the maximum time specified. When we hit the maximum time, if we still have not retrieved a valid resource throw an exception. This method is guaranteed to either return a valid resource in the pool timeout + object creation time or throw an exception. If an exception is thrown, resource is guaranteed to be destroyed.

Parameters:

key - The key to checkout the resource for

Returns:

The resource

Throws:

java.lang.Exception

attemptNonBlockingCheckout

protected V attemptNonBlockingCheckout(K key,
                                       KeyedResourcePool.Pool<V> pool)
                                throws java.lang.Exception

Get a free resource if one exists. If there are no free resources, attempt to create a new resource (up to the max allowed for the pool). This method does not block per se. However, creating a resource may be (relatively) expensive. This method either returns null or a resource. This method is the only way in which new resources are created for the pool. So, non blocking checkouts must be attempted to populate the resource pool.

Throws:

java.lang.Exception

getResourcePoolForKey

protected KeyedResourcePool.Pool<V> getResourcePoolForKey(K key)

Get the pool for the given key. If no pool exists, create one.

getResourcePoolForExistingKey

protected KeyedResourcePool.Pool<V> getResourcePoolForExistingKey(K key)

Get the pool for the given key. If no pool exists, throw an exception.

destroyResource

protected void destroyResource(K key,
                               KeyedResourcePool.Pool<V> resourcePool,
                               V resource)

checkin

public void checkin(K key,
                    V resource)
             throws java.lang.Exception

Check the given resource back into the pool

Parameters:

key - The key for the resource

resource - The resource

Throws:

java.lang.Exception

isOpenAndValid

protected boolean isOpenAndValid(K key,
                                 V resource)
                          throws java.lang.Exception

Throws:

java.lang.Exception

internalClose

protected boolean internalClose()

close

public void close()

Close the pool. This will destroy all checked in resource immediately. Once closed all attempts to checkout a new resource will fail. All resources checked in after close is called will be immediately destroyed.

reset

public void reset(K key)

Reset a specific resource pool. Destroys all of the idle resources in the pool. This method does not affect whether the pool is "open" in the sense of permitting new resources to be added to it.

Parameters:

key - The key for the pool to reset.

getTotalResourceCount

public int getTotalResourceCount(K key)

Count the number of existing resources for a specific pool.

Parameters:

key - The key

Returns:

The count of existing resources. Returns 0 if no pool exists for given key.

getTotalResourceCount

public int getTotalResourceCount()

Count the total number of existing resources for all pools. The result is "approximate" in the face of concurrency since individual pools can change size during the aggregate count.

Returns:

The (approximate) aggregate count of existing resources.

getCheckedInResourcesCount

public int getCheckedInResourcesCount(K key)

Count the number of checked in (idle) resources for a specific pool.

Parameters:

key - The key

Returns:

The count of checked in resources. Returns 0 if no pool exists for given key.

getCheckedInResourceCount

public int getCheckedInResourceCount()

Count the total number of checked in (idle) resources across all pools. The result is "approximate" in the face of concurrency since individual pools can have resources checked in, or out, during the aggregate count.

Returns:

The (approximate) aggregate count of checked in resources.

getBlockingGetsCount

public int getBlockingGetsCount(K key)

Count the number of blocking gets for a specific key.

Parameters:

key - The key

Returns:

The count of blocking gets. Returns 0 if no pool exists for given key.

getBlockingGetsCount

public int getBlockingGetsCount()

Count the total number of blocking gets across all pools. The result is "approximate" in the face of concurrency since blocking gets for individual pools can be issued or serviced during the aggregate count.

Returns:

The (approximate) aggregate count of blocking gets.

checkNotClosed

protected void checkNotClosed()

Check that the pool is not closed, and throw an IllegalStateException if it is.