開源項目剖析之apache-common-pool

前沿

     該工程提供了對象池解決方案，該方案主要用於提高像文件句柄，數據庫連接，socket通信這類大對象的調用效率。簡單的說就是一種對象一次創建多次使用的技術。

整體結構

     整個項目有三個包分別是org.apache.commons.pool2，org.apache.commons.pool2.impl和org.apache.commons.pool2.proxy。org.apache.commons.pool2主要定義整個項目要實現的接口；org.apache.commons.pool2.impl主要定義對接口的一般實現；org.apache.commons.pool2.proxy主要定義對接口的代理實現。

     接下來我們看看整體的代碼關系，如下類圖

      整個方案從ObjectPool，PooledObjectFactory和PooledObject三個接口展開，其中ObjectPool定義了對象池要實現的功能【比如怎么存取，怎么過期】；PooledObjectFactory定義了被池化的對象的創建，初始化，激活，鈍化以及銷毀功能；PooledObject定了一被池化對象的一些附加信息【創建時間，池中狀態】；大概流程就是由PooledObjectFactory創建的對象經過PooledObject的包裝然后放到ObjectPool里面來。

ObjectPool 

//從池中獲取對象
T borrowObject() throws Exception, NoSuchElementException,IllegalStateException;
//將對象放回池中
void returnObject(T obj) throws Exception;
//廢棄對象
void invalidateObject(T obj) throws Exception;
//添加對象
void addObject() throws Exception, IllegalStateException,UnsupportedOperationException;
//獲取對象個數
int getNumIdle();
//獲取活躍對象個數
int getNumActive();
//清除池，池可用
void clear() throws Exception, UnsupportedOperationException;
//關閉池，池不可用
void close();

PooledObjectFactory

//創建一個新對象;當對象池中的對象個數不足時,將會使用此方法來"輸出"一個新的"對象",並交付給對象池管理
PooledObject<T> makeObject() throws Exception;
//銷毀對象,如果對象池中檢測到某個"對象"idle的時間超時,或者操作者向對象池"歸還對象"時檢測到"對象"已經無效,那么此時將會導致"對象銷毀";"銷毀對象"的操作設計相差甚遠,但是必須明確:當調用此方法時,"對象"的生命周期必須結束.如果object是線程,那么此時線程必須退出;如果object是socket操作,那么此時socket必須關閉;如果object是文件流操作,那么此時"數據flush"且正常關閉.
void destroyObject(PooledObject<T> p) throws Exception;
//檢測對象是否"有效";Pool中不能保存無效的"對象",因此"后台檢測線程"會周期性的檢測Pool中"對象"的有效性,如果對象無效則會導致此對象從Pool中移除,並destroy;此外在調用者從Pool獲取一個"對象"時,也會檢測"對象"的有效性,確保不能講"無效"的對象輸出給調用者;當調用者使用完畢將"對象歸還"到Pool時,仍然會檢測對象的有效性.所謂有效性,就是此"對象"的狀態是否符合預期,是否可以對調用者直接使用;如果對象是Socket,那么它的有效性就是socket的通道是否暢通/阻塞是否超時等.
boolean validateObject(PooledObject<T> p);
// "激活"對象,當Pool中決定移除一個對象交付給調用者時額外的"激活"操作,比如可以在activateObject方法中"重置"參數列表讓調用者使用時感覺像一個"新創建"的對象一樣;如果object是一個線程,可以在"激活"操作中重置"線程中斷標記",或者讓線程從阻塞中喚醒等;如果object是一個socket,那么可以在"激活操作"中刷新通道,或者對socket進行鏈接重建(假如socket意外關閉)等.
void activateObject(PooledObject<T> p) throws Exception;
//"鈍化"對象,當調用者"歸還對象"時,Pool將會"鈍化對象";鈍化的言外之意,就是此"對象"暫且需要"休息"一下.如果object是一個socket,那么可以passivateObject中清除buffer,將socket阻塞;如果object是一個線程,可以在"鈍化"操作中將線程sleep或者將線程中的某個對象wait.需要注意的時,activateObject和passivateObject兩個方法需要對應,避免死鎖或者"對象"狀態的混亂.
void passivateObject(PooledObject<T> p) throws Exception;

PooledObject

T getObject();
long getCreateTime();
long getActiveTimeMillis();
long getIdleTimeMillis();
long getLastBorrowTime();
long getLastReturnTime();
long getLastUsedTime();
int compareTo(PooledObject<T> other);
boolean equals(Object obj);
int hashCode();
String toString();
//后台清理線程
boolean startEvictionTest();
boolean endEvictionTest(Deque<PooledObject<T>> idleQueue);
boolean allocate();
boolean deallocate();
void invalidate()
void setLogAbandoned(boolean logAbandoned);
void use();
void printStackTrace(PrintWriter writer);
PooledObjectState getState();
//自動補償功能
void markAbandoned();
void markReturning();

      方案提供了三種類型的pool，分別是GenericKeyedObjectPool，SoftReferenceObjectPool和GenericObjectPool。其中GenericObjectPool是一般意義上的對象池；SoftReferenceObjectPool是弱引用的對象池；GenericKeyedObjectPool是具備分組的對象池。

以下是各個類的詳細分析

SoftReferenceObjectPool

//可用對象列表
private final LinkedBlockingDeque<PooledSoftReference<T>> idleReferences = new LinkedBlockingDeque<PooledSoftReference<T>>();
//所有對象列表
private final ArrayList<PooledSoftReference<T>> allReferences = new ArrayList<PooledSoftReference<T>>();

borrowObject

//可用對象列表
private final LinkedBlockingDeque<PooledSoftReference<T>> idleReferences = new LinkedBlockingDeque<PooledSoftReference<T>>();
//所有對象列表
private final ArrayList<PooledSoftReference<T>> allReferences = new ArrayList<PooledSoftReference<T>>();


    public synchronized T borrowObject() throws Exception {
        assertOpen();//確定池打開
        T obj = null;
        boolean newlyCreated = false;
        PooledSoftReference<T> ref = null;
        while (null == obj) {
            if (idleReferences.isEmpty()) {
                if (null == factory) {
                    throw new NoSuchElementException();
                } else {
                    //如果可用列表為空則創建新的對象
                    newlyCreated = true;
                    obj = factory.makeObject().getObject();
                    //累加計數器
                    createCount++;
                    // Do not register with the queue
                    //關聯
                    ref = new PooledSoftReference<T>(new SoftReference<T>(obj));
                    //添加進所有列表
                    allReferences.add(ref);
                }
            } else {
                //從可用隊列獲取對象
                ref = idleReferences.pollFirst();
                obj = ref.getObject();
                // Clear the reference so it will not be queued, but replace with a
                // a new, non-registered reference so we can still track this object
                // in allReferences
                //重建關聯
                ref.getReference().clear();
                ref.setReference(new SoftReference<T>(obj));
            }
            if (null != factory && null != obj) {
                try {
                    //激活對象
                    factory.activateObject(ref);
                    if (!factory.validateObject(ref)) {
                        throw new Exception("ValidateObject failed");
                    }
                } catch (Throwable t) {
                    PoolUtils.checkRethrow(t);
                    try {
                        destroy(ref);
                    } catch (Throwable t2) {
                        PoolUtils.checkRethrow(t2);
                        // Swallowed
                    } finally {
                        obj = null;
                    }
                    if (newlyCreated) {
                        throw new NoSuchElementException(
                                "Could not create a validated object, cause: " +
                                        t.getMessage());
                    }
                }
            }
        }
        
        numActive++;
        //鎖定
        ref.allocate();
        return obj;
    }

returnObject

    public synchronized void returnObject(T obj) throws Exception {
        boolean success = !isClosed();
        //判斷對象來自於池【通過對象的equals方法】
        final PooledSoftReference<T> ref = findReference(obj);
        if (ref == null) {
            throw new IllegalStateException(
                "Returned object not currently part of this pool");
        }
        if (factory != null) {
            //判斷對象合格
            if (!factory.validateObject(ref)) {
                success = false;
            } else {
                try {
                    //鈍化對象
                    factory.passivateObject(ref);
                } catch (Exception e) {
                    success = false;
                }
            }
        }
        
        boolean shouldDestroy = !success;
        numActive--;
        if (success) {
            //如果對象合格並且鈍化成功則解除鎖定並添加到可用列表中
            // Deallocate and add to the idle instance pool
            ref.deallocate();
            idleReferences.add(ref);
        }
        notifyAll(); // numActive has changed

        if (shouldDestroy && factory != null) {
            try {
                destroy(ref);
            } catch (Exception e) {
                // ignored
            }
        }
    }

弱引用對象池最簡單，沒有后台清理線程只有當內存不夠的情況下由虛擬機清除。

GenericObjectPool

//默認出隊方式
private volatile boolean lifo = BaseObjectPoolConfig.DEFAULT_LIFO; 
//后台清理邏輯
class Evictor extends TimerTask
//所有對象列表
private final Map<T, PooledObject<T>> allObjects = new ConcurrentHashMap<T, PooledObject<T>>();
//可用對象列表【雙向鏈表】
private final LinkedBlockingDeque<PooledObject<T>> idleObjects = new LinkedBlockingDeque<PooledObject<T>>();

borrowObject

    public T borrowObject(long borrowMaxWaitMillis) throws Exception {
        assertOpen();
//是否在獲取對象的時候檢查對象，開啟的話則檢查【主要是檢查過期】
        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
//當池耗盡的時候是否block，如果block的話則會idleObjects.pollFirst(borrowMaxWaitMillis,TimeUnit.MILLISECONDS);否則直接throw new NoSuchElementException("Pool exhausted");
        boolean blockWhenExhausted = getBlockWhenExhausted();

        boolean create;
        long waitTime = 0;

        while (p == null) {
            create = false;
            if (blockWhenExhausted) {
                p = idleObjects.pollFirst();
                if (p == null) {
                    create = true;
                    p = create();
                }
                if (p == null) {
                    if (borrowMaxWaitMillis < 0) {
                        p = idleObjects.takeFirst();
                    } else {
                        waitTime = System.currentTimeMillis();
                        p = idleObjects.pollFirst(borrowMaxWaitMillis,
                                TimeUnit.MILLISECONDS);
                        waitTime = System.currentTimeMillis() - waitTime;
                    }
                }
                if (p == null) {
                    throw new NoSuchElementException(
                            "Timeout waiting for idle object");
                }
                if (!p.allocate()) {
                    p = null;
                }
            } else {
                p = idleObjects.pollFirst();
                if (p == null) {
                    create = true;
                    p = create();
                }
                if (p == null) {
                    throw new NoSuchElementException("Pool exhausted");
                }
                if (!p.allocate()) {
                    p = null;
                }
            }

            if (p != null) {
                try {
//激活對象
                    factory.activateObject(p);
                } catch (Exception e) {
                    try {
                        destroy(p);
                    } catch (Exception e1) {
                        // Ignore - activation failure is more important
                    }
                    p = null;
                    if (create) {
                        NoSuchElementException nsee = new NoSuchElementException(
                                "Unable to activate object");
                        nsee.initCause(e);
                        throw nsee;
                    }
                }
//如果獲取對象是檢查則validateObject
                if (p != null && getTestOnBorrow()) {
                    boolean validate = false;
                    Throwable validationThrowable = null;
                    try {
                        validate = factory.validateObject(p);
                    } catch (Throwable t) {
                        PoolUtils.checkRethrow(t);
                        validationThrowable = t;
                    }
//檢查不通過則destroy
                    if (!validate) {
                        try {
                            destroy(p);
                            destroyedByBorrowValidationCount.incrementAndGet();
                        } catch (Exception e) {
                            // Ignore - validation failure is more important
                        }
                        p = null;
                        if (create) {
                            NoSuchElementException nsee = new NoSuchElementException(
                                    "Unable to validate object");
                            nsee.initCause(validationThrowable);
                            throw nsee;
                        }
                    }
                }
            }
        }

        updateStatsBorrow(p, waitTime);

        return p.getObject();
    }

returnObject

    public void returnObject(T obj) {
        PooledObject<T> p = allObjects.get(obj);

        if (!isAbandonedConfig()) {
            if (p == null) {
                throw new IllegalStateException(
                        "Returned object not currently part of this pool");
            }
        } else {
            if (p == null) {
                return;  // Object was abandoned and removed
            } else {
                // Make sure object is not being reclaimed
                synchronized(p) {
                    final PooledObjectState state = p.getState();
                    if (state == PooledObjectState.ABANDONED ||
                            state == PooledObjectState.INVALID) {
                        return;
                    } else {
                        p.markReturning(); // Keep from being marked abandoned
                    }
                }
            }
        }

        long activeTime = p.getActiveTimeMillis();
//驗證合格
        if (getTestOnReturn()) {
            if (!factory.validateObject(p)) {
                try {
                    destroy(p);
                } catch (Exception e) {
                    swallowException(e);
                }
                updateStatsReturn(activeTime);
                return;
            }
        }
//鈍化
        try {
            factory.passivateObject(p);
        } catch (Exception e1) {
            swallowException(e1);
            try {
                destroy(p);
            } catch (Exception e) {
                swallowException(e);
            }
            updateStatsReturn(activeTime);
            return;
        }

        if (!p.deallocate()) {
            throw new IllegalStateException(
                    "Object has already been retured to this pool or is invalid");
        }
//池大小
        int maxIdleSave = getMaxIdle();
        if (isClosed() || maxIdleSave > -1 && maxIdleSave <= idleObjects.size()) {
            try {
                destroy(p);
            } catch (Exception e) {
                swallowException(e);
            }
        } else {
            if (getLifo()) {
                idleObjects.addFirst(p);
            } else {
                idleObjects.addLast(p);
            }
        }
        updateStatsReturn(activeTime);
    }

GenericKeyedObjectPool和GenericObjectPool類似。這里不再累述，下面主要說說怎么調用