从apache-common-pool看如何写一个通用池

public interface PooledObject<T> extends Comparable<PooledObject<T>> {
    // 获取池化对象容器的内部实例。
    T getObject();

    // 获取对象创建时间。
    long getCreateTime();

    // 最近一次处在活动状态时间。
    long getActiveTimeMillis();

    // 最近一次空闲状态时间。
    long getIdleTimeMillis();

    // 最近一次取出时间。
    long getLastBorrowTime();

    // 最近一次归还时间。
    long getLastReturnTime();

    /**
      * 最近一次使用时间,
      * 如果对象池实现了TrackedUse接口，返回 TrackedUse.getLastUsed() 和 getLastBorrowTime() 的最大值，
      * 否则 等同于 `getLastBorrowTime()`。
     */
    long getLastUsedTime();

    // PooledObject接口继承了comparable接口,\(compareTo 方法\),即池化对象是可以相互比较的，注意比较逻辑和 equals 方法不一致。
    @Override
    int compareTo(PooledObject<T> other);

    @Override
    boolean equals(Object obj);
    @Override
    int hashCode();
    @Override
    String toString();

    // 试图将池化对象的状态设置为EVICTION,设置成功返回true，反之返回false。
    boolean startEvictionTest();

    // 通知池化对象驱逐检查已经完成。
    boolean endEvictionTest(Deque<PooledObject<T>> idleQueue);

    // 分配对象,仅当当前状态是空闲\(IDLE\)时返回 true。
    boolean allocate();

    // 解除分配对象
    boolean deallocate();

    // 设置池化对象的状态为INVALIDs
    void invalidate();

    // 是否使用抛弃对象的调用堆栈
    void setLogAbandoned(boolean logAbandoned);

    // 通知对象被使用
    void use();

    // 输出堆栈调用记录
    void printStackTrace(PrintWriter writer);

    // 获取当前对象状态
    PooledObjectState getState();

    // 标记为抛弃状态
    void markAbandoned();

    // 标记为归还状态
    void markReturning();
}

public interface ObjectPool<T> extends Closeable {

    /**
     * Obtains an instance from this pool.
     */
    T borrowObject() throws Exception, NoSuchElementException, IllegalStateException;

    /**
     * Returns an instance to the pool. By contract, <code>obj</code>
     */
    void returnObject(T obj) throws Exception;

    /**
     * Invalidates an object from the pool.
     */
    void invalidateObject(T obj) throws Exception;

    /**
     * Creates an object using the PooledObjectFactory or other
     * implementation dependent mechanism, passivate it, and then place it in
     * the idle object pool.
     */
    void addObject() throws Exception, IllegalStateException ,UnsupportedOperationException;

    /**
     * Returns the number of instances currently idle in this pool.
     */
    int getNumIdle();

    /**
     * Returns the number of instances currently borrowed from this pool.
     */
    int getNumActive();

    /**
     * Clears any objects sitting idle in the pool。
     */
    void clear() throws Exception, UnsupportedOperationException;

    /**
     * Closes this pool, and free any resources associated with it.
     */
    @Override
    void close();
}

 Object obj = null;
 try {
     // pre-loading a pool with idle objects.
     pool.addObject();
     // Obtains an instance from this pool.
     obj = pool.borrowObject();
     try {
         //...use the object...
     } catch(Exception e) {
         // invalidate the object
         pool.invalidateObject(obj);
         // do not return the object to the pool twice
         obj = null;
     } finally {
         // make sure the object is returned to the pool
         if(null != obj) {
             pool.returnObject(obj);
        }
     }
 } catch(Exception e) {
       // failed to borrow an object
 }

public class ProxiedObjectPool<T> implements ObjectPool<T> {

    private final ObjectPool<T> pool;
    private final ProxySource<T> proxySource;

    /**
     * Create a new proxied object pool.
     *
     * @param pool  The object pool to wrap
     * @param proxySource The source of the proxy objects
     */
    public ProxiedObjectPool(final ObjectPool<T> pool, final ProxySource<T> proxySource) {
        this.pool = pool;
        this.proxySource = proxySource;
    }

    @SuppressWarnings("unchecked")
    @Override
    public T borrowObject() throws Exception, NoSuchElementException, IllegalStateException {
        UsageTracking<T> usageTracking = null;
        if (pool instanceof UsageTracking) {
            usageTracking = (UsageTracking<T>) pool;
        }
        final T pooledObject = pool.borrowObject();
        final T proxy = proxySource.createProxy(pooledObject, usageTracking);
        return proxy;
    }

    @Override
    public void returnObject(final T proxy) throws Exception {
        final T pooledObject = proxySource.resolveProxy(proxy);
        pool.returnObject(pooledObject);
    }

    @Override
    public void invalidateObject(final T proxy) throws Exception {
        final T pooledObject = proxySource.resolveProxy(proxy);
        pool.invalidateObject(pooledObject);
    }
    // ... ...
}

private final ObjectPool<T> pool;
private final ErodingFactor factor;
public ErodingObjectPool(final ObjectPool<T> pool, final float factor) {
    this.pool = pool;
    this.factor = new ErodingFactor(factor);
}
@Override
public void returnObject(final T obj) {
    boolean discard = false;
    final long now = System.currentTimeMillis();
    synchronized (pool) {
        if (factor.getNextShrink() < now) { // XXX: Pool 3: move test
                                            // out of sync block
            final int numIdle = pool.getNumIdle();
            if (numIdle > 0) {
                discard = true;
            }

            factor.update(now, numIdle);
        }
    }
    try {
        // 动态收缩
        if (discard) {
            pool.invalidateObject(obj);
        } else {
            pool.returnObject(obj);
        }
    } catch (final Exception e) {
        // swallowed
    }
}
// --------------------------------------------------
private static final class ErodingFactor {
/** Determines frequency of "erosion" events */
private final float factor;

/** Time of next shrink event */
private transient volatile long nextShrink;

/** High water mark - largest numIdle encountered */
private transient volatile int idleHighWaterMark;

public ErodingFactor(final float factor) {
    this.factor = factor;
    nextShrink = System.currentTimeMillis() + (long) (900000 * factor);
    // now + 15 min  * factor
     idleHighWaterMark = 1;
 }

 public void update(final long now, final int numIdle) {
     final int idle = Math.max(0, numIdle);
     idleHighWaterMark = Math.max(idle, idleHighWaterMark);
     final float maxInterval = 15f;
     final float minutes = maxInterval +
             ((1f - maxInterval) / idleHighWaterMark) * idle;
     nextShrink = now + (long) (minutes * 60000f * factor);
 }

 public long getNextShrink() {
     return nextShrink;
 }
}

public class SoftReferenceObjectPool<T> extends BaseObjectPool<T> {
    // 池化对象的构建工厂
    private final PooledObjectFactory<T> factory;
    // 结合软引用的 ReferenceQueue
    private final ReferenceQueue<T> refQueue = new ReferenceQueue<>();
    // 被借出的对象数
    private int numActive = 0;
    // 销毁的对象数
    private long destroyCount = 0;
    // 创建的对象数
    private long createCount = 0;
    // 空闲对象队列
    private final LinkedBlockingDeque<PooledSoftReference<T>> idleReferences =
        new LinkedBlockingDeque<>();
    // 所有对象的存储队列
    private final ArrayList<PooledSoftReference<T>> allReferences =
        new ArrayList<>();

  // 新增对象
  @Override
  public synchronized void addObject() throws Exception {
    assertOpen();
    if (factory == null) {
        throw new IllegalStateException("Cannot add objects without a factory.");
    }
    final T obj = factory.makeObject().getObject();
    createCount++;
    // 创建软引用，并在 queue中注册
    final PooledSoftReference<T> ref = new PooledSoftReference<>(
            new SoftReference<>(obj, refQueue));
    allReferences.add(ref);

    boolean success = true;
    if (!factory.validateObject(ref)) {
        success = false;
    } else {
        factory.passivateObject(ref);
    }

    final boolean shouldDestroy = !success;
    if (success) {
        idleReferences.add(ref);
        notifyAll(); // numActive has changed
        // 没有发现 wait 方法的使用？此处可能不需要notifyAll()
    }

    if (shouldDestroy) {
        try {
            destroy(ref);
        } catch (final Exception e) {
            // ignored
        }
    }
  }
  private void destroy(final PooledSoftReference<T> toDestroy) throws Exception {
    toDestroy.invalidate();
    idleReferences.remove(toDestroy);
    allReferences.remove(toDestroy);
    try {
        factory.destroyObject(toDestroy);
    } finally {
        destroyCount++;
        // 注意，SoftReference是对象的软引用，而不是池化对象的软引用
        // 此处将SoftReference的引用对象强制设为 null,防止其他地方持有对象的引用，导致无法回收
        toDestroy.getReference().clear();
    }
  }
  // ... ...
}

public T borrowObject(final long borrowMaxWaitMillis) throws Exception {
    // #1 对象池是打开的
    assertOpen();

    // #2 租借前，Abandoned处理
    final AbandonedConfig ac = this.abandonedConfig;
    if (ac != null && ac.getRemoveAbandonedOnBorrow() &&
        (getNumIdle() < 2) &&(getNumActive() > getMaxTotal() - 3) ) {
        removeAbandoned(ac);
    }

    PooledObject<T> p = null;

    // Get local copy of current config so it is consistent for entire
    // method execution
    final boolean blockWhenExhausted = getBlockWhenExhausted();

    boolean create;
    final long waitTime = System.currentTimeMillis();

    while (p == null) {
        create = false;
        // #3 取出一个空闲对象
        p = idleObjects.pollFirst();
        if (p == null) {
            // #3.1 idleObjects为空，新建对象
            p = create();
            if (p != null) {
                create = true;
            }
        }
        // #3.2 阻塞策略
        if (blockWhenExhausted) {
            if (p == null) {
                // #3.3 对象池已达上限，无法新建对象
                if (borrowMaxWaitMillis < 0) {
                    // #3.4 租借等待时间 <0,一直阻塞直到有空闲
                    p = idleObjects.takeFirst();
                } else {
                    // #3.5 有时间上限的阻塞
                    p = idleObjects.pollFirst(borrowMaxWaitMillis,TimeUnit.MILLISECONDS);
                }
            }
            if (p == null) {
                throw new NoSuchElementException("Timeout waiting for idle object");
            }
        } else {
            if (p == null) {
                throw new NoSuchElementException("Pool exhausted");
            }
        }
        if (!p.allocate()) {
            // #4 申请使用失败，置空
            p = null;
        }

        if (p != null) {
            try {
                // #5 激活对象
                factory.activateObject(p);
            } catch (final Exception e) {
                try {
                    destroy(p);
                } catch (final Exception e1) {
                    // Ignore - activation failure is more important
                }
                p = null;
                if (create) {
                    final NoSuchElementException nsee = new NoSuchElementException("Unable to activate object");
                    nsee.initCause(e);
                    throw nsee;
                }
            }
            if (p != null && (getTestOnBorrow() || create && getTestOnCreate())) {
                boolean validate = false;
                Throwable validationThrowable = null;
                try {
                    // #6 验证对象
                    validate = factory.validateObject(p);
                } catch (final Throwable t) {
                    PoolUtils.checkRethrow(t);
                    validationThrowable = t;
                }
                if (!validate) {
                    try {
                        destroy(p);
                        destroyedByBorrowValidationCount.incrementAndGet();
                    } catch (final Exception e) {
                        // Ignore - validation failure is more important
                    }
                    p = null;
                    if (create) {
                        final NoSuchElementException nsee = new NoSuchElementException("Unable to validate object");
                        nsee.initCause(validationThrowable);
                        throw nsee;
                    }
                }
            }
        }
    }
    // #7 更新状态
    updateStatsBorrow(p, System.currentTimeMillis() - waitTime);
    return p.getObject();
}

public void returnObject(final T obj) {
    // #1 获取对象对应的池化对象
    final PooledObject<T> p = allObjects.get(new IdentityWrapper<>(obj));
    if (p == null) {
        if (!isAbandonedConfig()) {
            throw new IllegalStateException("Returned object not currently part of this pool");
        }
        return; // Object was abandoned and removed
    }

    // #2 修改对象状态
    markReturningState(p);
    final long activeTime = p.getActiveTimeMillis();

    if (getTestOnReturn() && !factory.validateObject(p)) {
        // #3 验证未通过
        try {
            destroy(p);
        } catch (final Exception e) {
            swallowException(e);
        }
        try {
            // #4 池容量判断
            ensureIdle(1, false);
        } catch (final Exception e) {
            swallowException(e);
        }
        // #5 更新对应状态
        updateStatsReturn(activeTime);
        return;
    }

    try {
        // #3 钝化对象
        factory.passivateObject(p);
    } catch (final Exception e1) {
        swallowException(e1);
        try {
            destroy(p);
        } catch (final Exception e) {
            swallowException(e);
        }
        try {
            // #4 池容量判断
            ensureIdle(1, false);
        } catch (final Exception e) {
            swallowException(e);
        }
         // #5 更新对应状态
        updateStatsReturn(activeTime);
        return;
    }

    // #4 解除使用
    if (!p.deallocate()) {
        throw new IllegalStateException(
                "Object has already been returned to this pool or is invalid");
    }

    final int maxIdleSave = getMaxIdle();
    if (isClosed() || maxIdleSave > -1 && maxIdleSave <= idleObjects.size()) {
        // #5 池关闭或容量达上限，销毁对象
        try {
            destroy(p);
        } catch (final Exception e) {
            swallowException(e);
        }
    } else {
        // #5 进入空闲容器
        if (getLifo()) {
            idleObjects.addFirst(p);
        } else {
            idleObjects.addLast(p);
        }
        if (isClosed()) {
            // Pool closed while object was being added to idle objects.
            // Make sure the returned object is destroyed rather than left
            // in the idle object pool (which would effectively be a leak)
            clear();
        }
    }
    // #6 更新对应状态
    updateStatsReturn(activeTime);
}

final void startEvictor(final long delay) {
    synchronized (evictionLock) {
        if (null != evictor) { // 先释放资源
            EvictionTimer.cancel(evictor, evictorShutdownTimeoutMillis, TimeUnit.MILLISECONDS);
            evictor = null;
            evictionIterator = null;
        }
        if (delay > 0) {
            evictor = new Evictor();
            EvictionTimer.schedule(evictor, delay, delay);
        }
    }
}
// --------------------------
// 定时启动 evictor 线程
// 提供一个所有"对象池"共享的"空闲对象的驱逐定时器
static synchronized void schedule(
            final BaseGenericObjectPool<?>.Evictor task, final long delay, final long period) {
    if (null == executor) {
        executor = new ScheduledThreadPoolExecutor(1, new EvictorThreadFactory());
        executor.setRemoveOnCancelPolicy(true);
    }
    final ScheduledFuture<?> scheduledFuture =
            executor.scheduleWithFixedDelay(task, delay, period, TimeUnit.MILLISECONDS);
    task.setScheduledFuture(scheduledFuture);
}

class Evictor implements Runnable {
    /**  
     * 运行对象池维护线程。  
     * 驱逐对象具有驱逐者的资格，同时保证空闲实例可用的最小数量。  
     * 因为调用"驱逐者线程"的定时器是被所有对象池共享的，  
     * 但对象池可能存在不同的类加载器中，所以驱逐者必须确保采取的任何行为
     * 都得在与对象池相关的工厂的类加载器下。  
     */  
    @Override
    public void run() {
        final ClassLoader savedClassLoader =
                Thread.currentThread().getContextClassLoader();
        try {
            if (factoryClassLoader != null) {
                // Set the class loader for the factory
                // factoryClassLoader 是 classloader 的弱引用
                final ClassLoader cl = factoryClassLoader.get();
                if (cl == null) {
                    // The pool has been dereferenced and the class loader
                    // GC'd. Cancel this timer so the pool can be GC'd as
                    // well.
                    cancel();
                    return;
                }
                Thread.currentThread().setContextClassLoader(cl);
                // 见上方中文注释
                // [相关的一个 bug](https://issues.apache.org/jira/browse/POOL-161)
            }

            // Evict from the pool
            try {
                evict();
            } catch(final Exception e) {
                swallowException(e);
            } catch(final OutOfMemoryError oome) {
                // Log problem but give evictor thread a chance to continue
                // in case error is recoverable
                oome.printStackTrace(System.err);
            }
            // Re-create idle instances.
            try {
                ensureMinIdle();
            } catch (final Exception e) {
                swallowException(e);
            }
        } finally {
            // Restore the previous CCL
            Thread.currentThread().setContextClassLoader(savedClassLoader);
        }
    }
}

public void evict() throws Exception {
    // #1 确保"对象池"还打开着
    assertOpen();

    if (idleObjects.size() > 0) {
        PooledObject<T> underTest = null;
        // #2 获取"驱逐回收策略"
        final EvictionPolicy<T> evictionPolicy = getEvictionPolicy();

        synchronized (evictionLock) {
            // #3 获取"驱逐配置"
            final EvictionConfig evictionConfig = new EvictionConfig(
                    getMinEvictableIdleTimeMillis(),
                    getSoftMinEvictableIdleTimeMillis(),
                    getMinIdle());

            final boolean testWhileIdle = getTestWhileIdle();

            // #4 对所有待检测的"空闲对象"进行驱逐检测 ，注意循环次数，即检测个数是可配置的
            for (int i = 0, m = getNumTests(); i < m; i++) {
                // #4.1 初始化"驱逐检测对象(空闲池对象)的迭代器"  
                if (evictionIterator == null || !evictionIterator.hasNext()) {
                    evictionIterator = new EvictionIterator(idleObjects);
                }
                if (!evictionIterator.hasNext()) {
                    // Pool exhausted, nothing to do here
                    return;
                }

                try {
                    underTest = evictionIterator.next();
                } catch (final NoSuchElementException nsee) {
                    // Object was borrowed in another thread
                    // Don't count this as an eviction test so reduce i;
                    i--;
                    evictionIterator = null;
                    continue;
                }
                // #4.2 将"池对象"标记为"开始驱逐状态"  
                if (!underTest.startEvictionTest()) {
                    // Object was borrowed in another thread
                    // Don't count this as an eviction test so reduce i;
                    i--;
                    continue;
                }

                // User provided eviction policy could throw all sorts of
                // crazy exceptions. Protect against such an exception
                // killing the eviction thread.
                boolean evict;
                try {
                    // #4.3 进行真正的"驱逐检测"操作
                    evict = evictionPolicy.evict(evictionConfig, underTest,
                            idleObjects.size());
                } catch (final Throwable t) {
                    // Slightly convoluted as SwallowedExceptionListener
                    // uses Exception rather than Throwable
                    PoolUtils.checkRethrow(t);
                    swallowException(new Exception(t));
                    // Don't evict on error conditions
                    evict = false;
                }

                if (evict) {
                     // #4.3.1 如果"池对象"是可驱逐的，则销毁它  
                    destroy(underTest);
                    destroyedByEvictorCount.incrementAndGet();
                } else {
                    // #4.3.2 否则，是否允许空闲时进行有效性测试  
                    if (testWhileIdle) {
                        boolean active = false;
                        try {
                            // #4.3.2.1 先激活"池对象"  
                            factory.activateObject(underTest);
                            active = true;
                        } catch (final Exception e) {
                            destroy(underTest);
                            destroyedByEvictorCount.incrementAndGet();
                        }
                        if (active) {
                            if (!factory.validateObject(underTest)) {
                                // #4.3.2.2 如果"池对象"不是有效的，则销毁它
                                destroy(underTest);
                                destroyedByEvictorCount.incrementAndGet();
                            } else {
                                try {
                                    // #4.3.2.3 否则，钝化并放回池中
                                    factory.passivateObject(underTest);
                                } catch (final Exception e) {
                                    destroy(underTest);
                                    destroyedByEvictorCount.incrementAndGet();
                                }
                            }
                        }
                    }
                     // #4.3.2.4 通知"空闲对象队列"，驱逐测试已经结束  
                    if (!underTest.endEvictionTest(idleObjects)) {
                        // TODO - May need to add code here once additional
                        // states are used
                    }
                }
            }
        }
    }
    final AbandonedConfig ac = this.abandonedConfig;
    if (ac != null && ac.getRemoveAbandonedOnMaintenance()) {
        // #5 移除"被废弃的池对象"
        removeAbandoned(ac);
    }
}