commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pste...@apache.org
Subject svn commit: r776676 - in /commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl: GenericKeyedObjectPool.java GenericObjectPool.java
Date Wed, 20 May 2009 12:24:25 GMT
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;



Mime
View raw message