You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ps...@apache.org on 2009/05/20 14:24:25 UTC
svn commit: r776676 - in
/commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl:
GenericKeyedObjectPool.java GenericObjectPool.java
Author: psteitz
Date: Wed May 20 12:24:25 2009
New Revision: 776676
URL: http://svn.apache.org/viewvc?rev=776676&view=rev
Log:
javadoc improvemeents.
Modified:
commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericKeyedObjectPool.java
commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericObjectPool.java
Modified: commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericKeyedObjectPool.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericKeyedObjectPool.java?rev=776676&r1=776675&r2=776676&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericKeyedObjectPool.java (original)
+++ commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericKeyedObjectPool.java Wed May 20 12:24:25 2009
@@ -50,10 +50,11 @@
* <ul>
* <li>
* {@link #setMaxActive maxActive} controls the maximum number of objects
- * (per key) that can be borrowed from the pool at one time. When
- * non-positive, there is no limit to the number of objects per key.
- * When {@link #setMaxActive maxActive} is exceeded, the keyed pool is said
- * to be exhausted. The default setting for this parameter is 8.
+ * (per key) that can allocated by the pool (checked out to client threads,
+ * or idle in the pool) at one time. When non-positive, there is no limit
+ * to the number of objects per key. When {@link #setMaxActive maxActive} is
+ * reached, the keyed pool is said to be exhausted. The default setting for
+ * this parameter is 8.
* </li>
* <li>
* {@link #setMaxTotal maxTotal} sets a global limit on the number of objects
@@ -546,8 +547,10 @@
//--- configuration methods --------------------------------------
/**
- * Returns the cap on the number of active instances per key.
+ * Returns the cap on the number of object instances allocated by the pool
+ * (checked out or idle), per key.
* A negative value indicates no limit.
+ *
* @return the cap on the number of active instances per key.
* @see #setMaxActive
*/
@@ -556,9 +559,10 @@
}
/**
- * Sets the cap on the number of active instances per key.
- * @param maxActive The cap on the number of active instances per key.
+ * Sets the cap on the number of object instances managed by the pool per key.
+ * @param maxActive The cap on the number of object instances per key.
* Use a negative value for no limit.
+ *
* @see #getMaxActive
*/
public synchronized void setMaxActive(int maxActive) {
@@ -957,6 +961,9 @@
// Add this request to the queue
_allocationQueue.add(latch);
+
+ // Work the allocation queue, allocating idle instances and
+ // instance creation permits in request arrival order
allocate();
}
@@ -1065,6 +1072,11 @@
}
}
+ /**
+ * Allocate available instances to latches in the allocation queue. Then
+ * set _mayCreate to true for as many additional latches remaining in queue
+ * as _maxActive allows for each key.
+ */
private synchronized void allocate() {
if (isClosed()) return;
Modified: commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericObjectPool.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericObjectPool.java?rev=776676&r1=776675&r2=776676&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericObjectPool.java (original)
+++ commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericObjectPool.java Wed May 20 12:24:25 2009
@@ -41,11 +41,11 @@
* <ul>
* <li>
* {@link #setMaxActive <i>maxActive</i>} controls the maximum number of
- * objects that can be borrowed from the pool at one time. When
- * non-positive, there is no limit to the number of objects that may be
- * active at one time. When {@link #setMaxActive <i>maxActive</i>} is
- * exceeded, the pool is said to be exhausted. The default setting for this
- * parameter is 8.
+ * objects that can be allocated by the pool (checked out to clients, or
+ * idle awaiting checkout) at a given time. When non-positive, there is no
+ * limit to the number of objects that can be managed by the pool at one time.
+ * When {@link #setMaxActive <i>maxActive</i>} is reached, the pool is said
+ * to be exhausted. The default setting for this parameter is 8.
* </li>
* <li>
* {@link #setMaxIdle <i>maxIdle</i>} controls the maximum number of objects
@@ -65,15 +65,15 @@
* <li>
* When {@link #setWhenExhaustedAction <i>whenExhaustedAction</i>} is
* {@link #WHEN_EXHAUSTED_GROW}, {@link #borrowObject} will create a new
- * object and return it(essentially making {@link #setMaxActive <i>maxActive</i>}
+ * object and return it (essentially making {@link #setMaxActive <i>maxActive</i>}
* meaningless.)
* </li>
* <li>
* When {@link #setWhenExhaustedAction <i>whenExhaustedAction</i>}
* is {@link #WHEN_EXHAUSTED_BLOCK}, {@link #borrowObject} will block
- * (invoke {@link Object#wait()} until a new or idle object is available.
+ * (invoke {@link Object#wait()}) until a new or idle object is available.
* If a positive {@link #setMaxWait <i>maxWait</i>}
- * value is supplied, the {@link #borrowObject} will block for at
+ * value is supplied, then {@link #borrowObject} will block for at
* most that many milliseconds, after which a {@link NoSuchElementException}
* will be thrown. If {@link #setMaxWait <i>maxWait</i>} is non-positive,
* the {@link #borrowObject} method will block indefinitely.
@@ -140,10 +140,13 @@
* {@link #setSoftMinEvictableIdleTimeMillis <i>softMinEvictableIdleTimeMillis</i>}
* specifies the minimum amount of time an object may sit idle in the pool
* before it is eligible for eviction by the idle object evictor
- * (if any), with the extra condition that at least "minIdle" amount of object
+ * (if any), with the extra condition that at least "minIdle" object instances
* remain in the pool. When non-positive, no objects will be evicted from the pool
* due to idle time alone. This setting has no effect unless
- * <code>timeBetweenEvictionRunsMillis > 0.</code> The default setting for
+ * <code>timeBetweenEvictionRunsMillis > 0.</code> and it is superceded by
+ * {@link #setMinEvictableIdleTimeMillis <i>minEvictableIdleTimeMillis</i>}
+ * (that is, if <code>minEvictableIdleTimeMillis</code> is positive, then
+ * <code>softMinEvictableIdleTimeMillis</code> is ignored). The default setting for
* this parameter is -1 (disabled).
* </li>
* <li>
@@ -524,8 +527,12 @@
//--- configuration methods --------------------------------------
/**
- * Returns the cap on the total number of active instances from the pool.
- * @return the cap on the total number of active instances from the pool.
+ * Returns the maximum number of objects that can be allocated by the pool
+ * (checked out to clients, or idle awaiting checkout) at a given time.
+ * When non-positive, there is no limit to the number of objects that can
+ * be managed by the pool at one time.
+ *
+ * @return the cap on the total number of object instances managed by the pool.
* @see #setMaxActive
*/
public synchronized int getMaxActive() {
@@ -533,9 +540,13 @@
}
/**
- * Sets the cap on the total number of active instances from the pool.
- * @param maxActive The cap on the total number of active instances from the pool.
- * Use a negative value for no limit.
+ * Sets the cap on the number of objects that can be allocated by the pool
+ * (checked out to clients, or idle awaiting checkout) at a given time. Use
+ * a negative value for no limit.
+ *
+ * @param maxActive The cap on the total number of object instances managed by the pool.
+ * Negative values mean that there is no limit to the number of objects allocated
+ * by the pool.
* @see #getMaxActive
*/
public synchronized void setMaxActive(int maxActive) {
@@ -830,7 +841,7 @@
* Sets the minimum amount of time an object may sit idle in the pool
* before it is eligible for eviction by the idle object evictor
* (if any), with the extra condition that at least
- * "minIdle" amount of object remain in the pool.
+ * "minIdle" object instances remain in the pool.
* When non-positive, no objects will be evicted from the pool
* due to idle time alone.
*
@@ -937,6 +948,9 @@
// Add this request to the queue
_allocationQueue.add(latch);
+
+ // Work the allocation queue, allocating idle instances and
+ // instance creation permits in request arrival order
allocate();
}
@@ -1044,6 +1058,11 @@
}
}
+ /**
+ * Allocate available instances to latches in the allocation queue. Then
+ * set _mayCreate to true for as many additional latches remaining in queue
+ * as _maxActive allows.
+ */
private synchronized void allocate() {
if (isClosed()) return;
@@ -1540,8 +1559,8 @@
/**
* Latch used to control allocation order of objects to threads to ensure
- * fairness. ie objects are allocated to threads in the order that threads
- * request objects.
+ * fairness. That is, objects are allocated to threads in the order that
+ * threads request objects.
*/
private static final class Latch {
ObjectTimestampPair _pair;