【原创】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();
    }
});