【原創】jQuery1.8.2源碼解析之jQuery.Deferred

首先來一張jQuery.Deferred的結構圖：

 

再來一張執行deferred.then(/*fnDone, fnFail, fnProcess*/)后的結構圖：

 

最后來看看源代碼：

jQuery.extend({

    Deferred: function( func ) {
        // 數據元組集
        // 每個元組分別包含一些與當前deferred相關的信息: 
        // 分別是：觸發回調函數列表執行(函數名)，添加回調函數（函數名），回調函數列表（jQuery.Callbacks對象），deferred最終狀態（第三組數據除外）
        // 總體而言，三個元組會有對應的三個callbacklist對應於doneList, failList, processList
        // 對於jQuery.Callbacks對象，可以看之前的文章http://www.cnblogs.com/lovesueee/archive/2012/10/18/2729829.html
        var tuples = [
                // action, add listener, listener list, final state
                [ "resolve", "done", jQuery.Callbacks("once memory"), "resolved" ],
                [ "reject", "fail", jQuery.Callbacks("once memory"), "rejected" ],
                [ "notify", "progress", jQuery.Callbacks("memory") ]
            ],
            // deferred的狀態，分為三種：pending(初始狀態), resolved(解決狀態), rejected(拒絕狀態)
            state = "pending",
            // promise對象，主要有兩點作用：
            // 1. 在初始化deferred對象時，promise對象里的方法都會被extend到deferred中去，作為引用（見86行）
            // 2. 那么，生成的deferred對象里必然引用了promise對象的promise方法，所以當調用deferred.promise()時，
            //    deferred對象會通過閉包返回promise對象，這就是所謂的受限制的deferred對象（用deferred2表示），因為相比之前，
            //    返回的deferred2不在擁有resolve(With), reject(With), notify(With)這些能改變deferred對象狀態並且執行callbacklist的方法了
            promise = {
                // 返回閉包里的內部state（外部只讀）
                state: function() {
                    return state;
                },
                // 同時在doneList和failList的list里添加回調函數（引用）
                // 那么不論deferred最終狀態是resolved還是rejected, 回調函數都會被執行，這就是所謂的always
                always: function() {
                    deferred.done( arguments ).fail( arguments );
                    return this;
                },
                // jQuery.then()會創建一個新的受限制的deferred對象
                // 有點復雜，下面我有畫一個圖幫忙理解
                then: function( /* fnDone, fnFail, fnProgress */ ) {
                    var fns = arguments;
                    // 創建新的受限制的deferred對象（稱作newDeferrred），並返回
                    // 利用返回的deferred對象就可以做很多事了，你懂的
                    return jQuery.Deferred(function( newDefer ) {
                        jQuery.each( tuples, function( i, tuple ) {
                            var action = tuple[ 0 ],
                                fn = fns[ i ];
                            // deferred[ done | fail | progress ] for forwarding actions to newDefer
                            // 分別為deferred的三個callbacklist添加回調函數，根據fn的是否是函數，分為兩種情況：
                            // 1.不是函數的情況（如值為undefined或者null等），直接鏈接到newDeferred的resolve(reject,notify)方法，也就是說
                            //   newDeferrred的執行依賴外層的調用者deferred的狀態或者說是執行動作（resolve還是reject或者是notify）
                            //   此時deferred.then()相當於將自己的callbacklist和newDeferred的callbacklist連接起來了，故可以在newDeferred
                            //   中大做文章
                            // 2.是函數的情況，根據返回值(稱作returnReferred)是否是deferred對象，又可以分為兩種情況：
                            //   2.1 返回值是deferred對象，那么在returnReferred對象的三個回調函數列表中添加newDeferred的resolve(reject,notify)方法
                            //       也就是說newDeferrred的執行依賴returnDeferred的狀態
                            //   2.2 返回值不是deferred對象，那么將返回值returned作為newDeferred的參數並將從外層deferred那邊的上下文環境作為newDeferred
                            //       的執行上下文，然后執行對應的回調函數列表，此時newDeferrred的執行依賴外層的調用者deferred的狀態
                            deferred[ tuple[1] ]( jQuery.isFunction( fn ) ?
                                function() {
                                    var returned = fn.apply( this, arguments );
                                    if ( returned && jQuery.isFunction( returned.promise ) ) {
                                        returned.promise()
                                            .done( newDefer.resolve )
                                            .fail( newDefer.reject )
                                            .progress( newDefer.notify );
                                    } else {
                                        newDefer[ action + "With" ]( this === deferred ? newDefer : this, [ returned ] );
                                    }
                                } :
                                newDefer[ action ]
                            );
                        });
                        fns = null;
                    }).promise();
                },
                // Get a promise for this deferred
                // If obj is provided, the promise aspect is added to the object
                promise: function( obj ) {
                    return typeof obj === "object" ? jQuery.extend( obj, promise ) : promise;
                }
            },
            // 實際返回的deferred對象
            deferred = {};

        // Keep pipe for back-compat
        // pipe和then引用同一個函數，所以功能是一樣的
        // 只不過通常的用法是：會用pipe進行filter操作
        promise.pipe = promise.then;

        // Add list-specific methods
        // 通過上面定義的數據元組集來擴展一些方法
        jQuery.each( tuples, function( i, tuple ) {
            var list = tuple[ 2 ],
                stateString = tuple[ 3 ];

            // promise[ done | fail | progress ] = list.add
            // 給上面的promise對象添加done，fail，process方法
            // 這三個方法分別引用三個不同jQuery.Callbacks對象的add方法（不是同一個引用），
            // 那么這三個方法的用途就是向各自的回調函數列表list（各自閉包中）中添加回調函數，互不干擾
            promise[ tuple[1] ] = list.add;

            // Handle state
            // 通過stateString有值這個條件，預先向doneList,failList中的list添加三個回調函數
            // doneList : [changeState, failList.disable, processList.lock]
            // failList : [changeState, doneList.disable, processList.lock]
            // changeState 指的是下面首先添加的一個改變deferred對象的匿名函數
            // 可以看的出: 不論deferred對象最終是resolve（還是reject），在首先改變對象狀態之后，都會disable另一個函數列表failList(或者doneList)
            // 然后lock processList保持其狀態，最后執行剩下的之前done（或者fail）進來的回調函數
            // 當然了，上述情況processList除外
            if ( stateString ) {
                list.add(function() {
                    // state = [ resolved | rejected ]
                    state = stateString;

                // [ reject_list | resolve_list ].disable; progress_list.lock
                }, tuples[ i ^ 1 ][ 2 ].disable, tuples[ 2 ][ 2 ].lock );
            }

            // deferred[ resolve | reject | notify ] = list.fire
            // 給deferred對象添加resolve(With), reject(With), notify(With)方法
            // 這三個方法分別引用三個不同jQuery.Callbacks對象的fire方法（不是同一個引用），
            // 那么這三個方法的用途就是執行各自的回調函數列表，互不干擾
            deferred[ tuple[0] ] = list.fire;
            deferred[ tuple[0] + "With" ] = list.fireWith;
        });

        // Make the deferred a promise
        // 將上面的promise對象extend進deferred中
        promise.promise( deferred );

        // Call given func if any
        // 如果調用jQuery.Deferred(func)指定了參數，那么調用func並設置func的上下文和參數均為deferred
        // 在jQuery.then()中有用到這一點
        if ( func ) {
            func.call( deferred, deferred );
        }

        // All done!
        // 返回最終的deferred對象
        return deferred;
    },

    // Deferred helper
    // 參數：一個（或多個）deferred對象（或其他）
    // 當傳入的所有deferred對象都resolve或者reject了，執行when()創建的deferred對象（稱之為whenDeferred）對應的回調函數列表（非deferred對象被認為是resolve了）
    when: function( subordinate /* , ..., subordinateN */ ) {
        var i = 0,
            // 首先將arguments偽數組轉換為真正的數組
            resolveValues = core_slice.call( arguments ),
            length = resolveValues.length,

            // the count of uncompleted subordinates
            // jQuery.isFunction( subordinate.promise )用來判斷subordinate是否是deferred對象
            // 1. 在參數個數等於1的情況下：
            //   1.1 如果參數是deferred對象，那么remaining = length, 這是remaining就是1嘛
            //   1.2 否則remaining為0
            // 2. 在參數不等於1(即等於0或者大於1)的情況：remaining = length
            remaining = length !== 1 || ( subordinate && jQuery.isFunction( subordinate.promise ) ) ? length : 0,

            // the master Deferred. If resolveValues consist of only a single Deferred, just use that.
            // 到這里就可以知道：如果參數個數僅為1個，並且是deferred對象，那么就無需再生成deferred對象
            deferred = remaining === 1 ? subordinate : jQuery.Deferred(),

            // Update function for both resolve and progress values
            updateFunc = function( i, contexts, values ) {
                // 這里返回一個函數作為一個callback完全是為了創建一個閉包，主要是為了保持i的值
                return function( value ) {
                    // 保存各個deferred執行的上下文，也就是說之后whenDeferred的回調函數的上下文就是一個數組
                    contexts[ i ] = this;
                    // 保存各個deferred執行時的參數，之后傳遞給whenDeferred的回調函數
                    // 此時values的值有原先的jQuery.when()傳進來的參數變為各個deferred執行回調時的參數了，也就是說覆蓋了
                    values[ i ] = arguments.length > 1 ? core_slice.call( arguments ) : value;
                    if( values === progressValues ) {
                        // 這里，暫時不理解有什么用處？
                        deferred.notifyWith( contexts, values );
                    } else if ( !( --remaining ) ) {
                        // 時機成熟，即所有延遲都resolve，執行whenDeferred的回調函數
                        deferred.resolveWith( contexts, values );
                    }
                };
            },

            progressValues, progressContexts, resolveContexts;

        // add listeners to Deferred subordinates; treat others as resolved
        // 如果參數個數大於1，那么就是說有可能存在多個deferred對象
        // 這時需要一些條件判斷以保證是所有的deferred對象都resolve了，再執行whenDeferred的resolve
        // 或者當有一個deferred對象reject了，whenDeferred的reject
        if ( length > 1 ) {
            progressValues = new Array( length );
            progressContexts = new Array( length );
            resolveContexts = new Array( length );
            for ( ; i < length; i++ ) {
                // 如果是deferred對象
                if ( resolveValues[ i ] && jQuery.isFunction( resolveValues[ i ].promise ) ) {
                    // 給每個參數（deferred對象）添加最后的回調，用來檢查此時的狀態

                    resolveValues[ i ].promise()
                        // 用於當每一個deferred對象resolve回來，用updateFunc返回的函數檢查此時其他deferred對象的狀態（即此時remaining是否等於0了）
                        // 如果等於0，則執行whenDeferred的resolve，否則繼續等待
                        .done( updateFunc( i, resolveContexts, resolveValues ) )
                        // 如果有一個deferred對象reject,whenDeferred將執行reject
                        .fail( deferred.reject )
                        // 用於通知，暫時不知道有什么用？
                        .progress( updateFunc( i, progressContexts, progressValues ) );
                // 如果不是deferred對象，直接--remaining，視為resolve
                } else {
                    --remaining;
                }
            }
        }

        // if we're not waiting on anything, resolve the master
        // 如果此時remaining就等與0了，表示沒有什么延遲需要等待，那么立即之行whenDeferred的resolveWith
        // 此時resolveContexts為undefined， 這就意味這上下文將為全局的window
        if ( !remaining ) {
            deferred.resolveWith( resolveContexts, resolveValues );
        }

        // 返回受限制的deferred對象
        return deferred.promise();
    }
});