com.jthreadkit.pool
Interface ResourcePool

All Superinterfaces:

AccessibleLock

All Known Implementing Classes:

AbstractResourcePool

public interface ResourcePool

extends AccessibleLock

This interface specifies the general contract for pools of precious resources. The pool maintains a collection of idle resources and they are temporarily checked out of the pool for use and then returned. This recycling of resources can improve performance and can allow for the sharing of limited resources.

All implementations have the concept of a "low water mark", a "high water mark", and a "maximum allocation count" --and these values don't change often. There is also an "idle resource count" and a "currently allocated resource count" --and these values do fluctuate often. Each of the following three statements must always be true:

0 <= lowWaterMark <= highWaterMark <= maxCount 0 <= idleCount <= allocatedCount <= maxCount maxCount >= 1

You specify lowWaterMark, highWaterMark, and maxCount through methods on this interface or during construction of a pool. You do not specify the idleCount or the allocatedCount. The number of idle resources is determined by the activity on the pool. The number of allocated resources is also determined by the activity on the pool.

Allocation and Deallocation of Resources

Generally (within limits specified more precisely below):

• when the idle count is between the low and high water marks, no resources are allocated or deallocated.
• when the idle count is below the low water mark, new resources are allocated to bring the level back up to the low water mark.
• when the idle count is above the high water mark, existing idle resources are deallocated to bring the level back down to the high water mark.

More precisely, while this is true:

lowWaterMark <= idleCount <= highWaterMark

no new resources are allocated and no existing resources are destroyed.

While this is true:

idleCount > highWaterMark

existing idle resources deallocated to bring the idle level down to the high water level. Usually there is an initial delay before this deallocation process starts (see getDestroyResourceDelay()). Once deallocation starts, there is a interval of time that must elapse between each deallocation (see getDestroyResourceInterval()).

While these two statements are true:

0 <= idleCount < lowWaterMark allocatedCount < maxCount

new resources allocated to bring the idle level up to the low water level. Usually there is an initial delay before this allocation process starts (see getCreateResourceDelay()). Once allocation starts, there is a interval of time that must elapse between each new resource allocation (see getCreateResourceInterval()).

If a thread comes along tries to check a resource out of the pool and these two statements are true:

idleCount == 0 allocatedCount < maxCount

the pool is currently empty and the thread trying to do the checkout might have to wait. There is an option to specify the a delay before a resource is created "on demand" - see setCreateResourceOnDemandDelay(long). This "on demand" delay is typically a short time or potentially NO_DELAY.

If a thread comes along tries to check a resource out of the pool and these two statements are true:

idleCount == 0 allocatedCount == maxCount

the pool is currently empty and no more resources can be allocated. The thread trying to do the checkout must wait until another thread checks-in an idle resource.

A "bottomless" resource pool always allows a resource to be checked out without any delay (if the pool is empty, a new resource is created on demand). To make a pool "bottomless", specify:

pool.setMaxCount(Integer.MAX_VALUE); pool.setCreateResourceOnDemandDelay(ResourcePool.NO_DELAY);

This of course requires that the underlying implementation can support an maxCount that high (virtually infinite).

Field Summary

static long	INFINITE_DELAY
static long	NO_DELAY

Method Summary

boolean	addConfigChangeListener(ConfigChangeListener listener)
int	getAllocatedCount()
SizeMonitored	getAllocatedSizeMonitored()
long	getCreateResourceDelay()
long	getCreateResourceInterval()
long	getCreateResourceOnDemandDelay()
long	getDestroyResourceDelay()
long	getDestroyResourceInterval()
int	getHighWaterMark()
int	getIdleCount()
SizeMonitored	getIdleSizeMonitored()
int	getLowWaterMark()
int	getMaxCount()
void	initiateShutdown(long msDelayBeforeHardball)
boolean	removeConfigChangeListener(ConfigChangeListener listener)
void	setCreateResourceDelay(long msDelay)
void	setCreateResourceInterval(long msDelay)
void	setCreateResourceOnDemandDelay(long msDelay)
void	setDestroyResourceDelay(long msDelay)
void	setDestroyResourceInterval(long msDelay)
int	setHighWaterMark(int newLevel)
void	setLowHighMax(int newLowWaterMark, int newHighWaterMark, int newMaxCount)
int	setLowWaterMark(int newLevel)
int	setMaxCount(int requestedNewMax)
boolean	waitUntilShutdown(long msTimeout)

Methods inherited from interface com.jthreadkit.AccessibleLock

getLockObject

Field Detail

INFINITE_DELAY

public static final long INFINITE_DELAY

NO_DELAY

public static final long NO_DELAY

Method Detail

getIdleCount

public int getIdleCount()

getIdleSizeMonitored

public SizeMonitored getIdleSizeMonitored()

getAllocatedCount

public int getAllocatedCount()

getAllocatedSizeMonitored

public SizeMonitored getAllocatedSizeMonitored()

getMaxCount

public int getMaxCount()

setMaxCount

public int setMaxCount(int requestedNewMax)

getLowWaterMark

public int getLowWaterMark()

setLowWaterMark

public int setLowWaterMark(int newLevel)

getHighWaterMark

public int getHighWaterMark()

setHighWaterMark

public int setHighWaterMark(int newLevel)

setLowHighMax

public void setLowHighMax(int newLowWaterMark,
                          int newHighWaterMark,
                          int newMaxCount)
                   throws IllegalArgumentException

getCreateResourceDelay

public long getCreateResourceDelay()

setCreateResourceDelay

public void setCreateResourceDelay(long msDelay)

getCreateResourceInterval

public long getCreateResourceInterval()

setCreateResourceInterval

public void setCreateResourceInterval(long msDelay)

getCreateResourceOnDemandDelay

public long getCreateResourceOnDemandDelay()

setCreateResourceOnDemandDelay

public void setCreateResourceOnDemandDelay(long msDelay)

getDestroyResourceDelay

public long getDestroyResourceDelay()

setDestroyResourceDelay

public void setDestroyResourceDelay(long msDelay)

getDestroyResourceInterval

public long getDestroyResourceInterval()

setDestroyResourceInterval

public void setDestroyResourceInterval(long msDelay)

addConfigChangeListener

public boolean addConfigChangeListener(ConfigChangeListener listener)

removeConfigChangeListener

public boolean removeConfigChangeListener(ConfigChangeListener listener)

initiateShutdown

public void initiateShutdown(long msDelayBeforeHardball)

waitUntilShutdown

public boolean waitUntilShutdown(long msTimeout)
                          throws InterruptedException