cvs commit: jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/pool ResourceLimitingPool.java

[le...@apache.org]

leif        02/02/07 00:09:51

  Modified:    src/scratchpad/org/apache/avalon/excalibur/pool
                        ResourceLimitingPool.java
  Log:
  Added more descriptive JavaDocs
  
  Revision  Changes    Path
  1.3       +11 -8     jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/pool/ResourceLimitingPool.java
  
  Index: ResourceLimitingPool.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/pool/ResourceLimitingPool.java,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- ResourceLimitingPool.java	25 Jan 2002 01:24:27 -0000	1.2
  +++ ResourceLimitingPool.java	7 Feb 2002 08:09:50 -0000	1.3
  @@ -25,15 +25,15 @@
    * General Pool implementation which supports; weak and strong pool size limits,
    *  optional blocking gets when poolables are not available, and automatic pool
    *  trimming of unused poolables.
  - *
  + * <p>
    * Whenever get() is called, the pool tests to see whether it is time to trim old
    *  poolables from the pool.  If any old poolables exist then they are removed at
    *  this time.  This means that old poolables will not be removed if get() is never
    *  called.  Applications can optionally call trim() to force old objects to be
  - *  trimmed.  See the trim() method for details of how trimming works.
  + *  trimmed.  See the {@link #trim()} method for details of how trimming works.
    *
    * @author <a href="mailto:leif@silveregg.co.jp">Leif Mortenson</a>
  - * @version CVS $Revision: 1.2 $ $Date: 2002/01/25 01:24:27 $
  + * @version CVS $Revision: 1.3 $ $Date: 2002/02/07 08:09:50 $
    * @since 4.1
    */
   public class ResourceLimitingPool
  @@ -449,6 +449,7 @@
       /**
        * Permanently removes a poolable from the pool's active list and 
        *  destroys it so that it will not ever be reused.
  +     * <p>
        * This method is only called by threads that have m_semaphore locked.
        */
       protected void permanentlyRemovePoolable( Poolable poolable )
  @@ -479,8 +480,10 @@
       /**
        * Create a new poolable instance by by calling the newInstance method
        *  on the pool's ObjectFactory.
  +     * <p>
        * This is the method to override when you need to enforce creational
        *  policies.
  +     * <p>
        * This method is only called by threads that have m_semaphore locked.
        */
       protected Poolable newPoolable() throws Exception
  @@ -493,7 +496,7 @@
        * Called when an object is being removed permanently from the pool.
        * This is the method to override when you need to enforce destructional
        * policies.
  -     *
  +     * <p>
        * This method is only called by threads that have m_semaphore locked.
        *
        * @param poolable Poolable to be completely removed from the pool.
  @@ -519,22 +522,22 @@
        *  be called at that interval when get() is called.  If get() is not called
        *  for long periods of time then if may be necessary to call this method
        *  manually.
  -     *
  +     * <p>
        * Trimming is done by maintaing two lists of objects.  The first is a ready list
        *  of new poolables. The second is a list of old poolables.  Each time trim() is
        *  called, the contents of the old list are removed from the pool.  Then the
        *  contents of the new list is moved into the old list.
  -     *
  +     * <p>
        * Each time get() is called on the pool, the new list is checked first, then the
        *  old list is checked, finally a new poolable may be created if both lists are
        *  empty.  Then whenever put() is called, the poolables are always returned to
        *  the new list.  In this way, the need for maining time stamps for each poolable
        *  can be avoided while at the same time avoiding unnecessary removal and creation
        *  on poolables.
  -     *
  +     * <p>
        * This works out to a poolable having a maximum idle time of two calls to trim() or
        *  twice the value of trimInterval.
  -     *
  +     * <p>
        * NOTE - The trimming feature does not harm performance because pools with high
        *  load will not have old poolables to be trimmed, and the benefits to system
        *  resources from not keeping around unused poolables makes up for any hit.
  
  
  

--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>