jQuery源码剖析（三）——$.Deferred

var callbacks = $.Callbacks();
callbacks.add(function(){
  alert('读取到内容');
});
callbacks.add(function(content){
  alert('内容：' + content);
});
read('raphealguo.txt', function(content){
  callbacks.fire(content);
});

read("raphealguo.html")
　　.done(function(){ alert("读取到内容"); })
　　.done(function(content){ alert('内容：' + content); })
　　.fail(function(){ alert("读取文件失败"); });

function read(path){
  var dfd = $.Deferred();//jQuery的异步队列
  console.log("开始读取");
  setTimeout(function(){
    console.log("结束读取");
    dfd.resolve(path + '的内容');//resolve类似$.Callbacks的fire，派发事件，由done接管
    //dfd.reject('失败');//由fail接管
  }, 3000);
  dfd.notify('处理中');//fire派发事件，由progress方法接管
  return dfd;//返回异步队列，dfd包含了done，progress，fail方法
}
 
read("test.html")
　　.done(function(content){ console.log(content);})
　　.fail(function(){ console.log("出错！"); } )
　　.progress(function(){ console.log("处理中！"); });
 
//输出：
//开始读取
//处理中！
//结束读取
//test.html的内容

var dfd = read("test.html")
　　.done(function(content){ console.log(content);})
　　.fail(function(){ console.log("出错！"); } )
　　.progress(function(){ console.log("处理中！"); });
dfd.resolve('非法的触发');//这里竟然也能触发done回调

function read(path){
  var dfd = $.Deferred();//jQuery的异步队列
  /* other code */
  return dfd.promise();//通过promise方法把dfd里边一些状态设置的接口给隐藏掉，只暴露done|fail|progress三个接口。
}

function read(/*path*/){//这里暂时忽略掉path参数
  var dfd = this;//在Deferred里边已经把上下文切换成它生成的一个异步队列实例
  /* other code */
  return dfd.promise();//通过promise方法把dfd里边一些状态设置的接口给隐藏掉，只暴露done|fail|progress三个接口。
}
$.Deferred(read)
　　.done(function(content){ console.log(content);})
　　.fail(function(){ console.log("出错！"); } )
　　.progress(function(){ console.log("处理中！"); });

$.Deferred = function( func ) {
  var tuples = [
      // action, add listener, listener list, final state
      //三个队列，done|fail|progress 成功|失败|处理中
      //分别对应：
      //事件  暴露的添加回调的接口名   Callbacks队列   处理结束后的状态
      [ "resolve", "done", jQuery.Callbacks("once memory"), "resolved" ],
      [ "reject", "fail", jQuery.Callbacks("once memory"), "rejected" ],
      [ "notify", "progress", jQuery.Callbacks("memory") ]
    ],
    //初始状态
    state = "pending",
 
 
    promise = {
      //获取当前异步队列处理的状态
      state: function() {
        return state;
      },
 
      //可以看到，无论是成功失败，参数里边的回调都会被加入成功|失败队列
      always: function() {
        deferred.done( arguments ).fail( arguments );
        return this;
      },
 
      //deferred.done(fnDone),fail(fnFail).progress(fnProgress)的快捷方式
      then: function( /* fnDone, fnFail, fnProgress */ ) {
        // fns = [fnDone, fnFail, fnProgress]
        var fns = arguments;
 
        //这里return jQuery.Deferred(function( newDefer ) {}).promise();
        //为何还要使用jQuery.Deferred来包装
        //就then比较特殊需要重新调promise方法来屏蔽resolve|reject|notify这些接口？
        return jQuery.Deferred(function( newDefer ) {
 
          jQuery.each( tuples, function( i, tuple ) {
 
            //action = [resolve | reject | notify]
            var action = tuple[ 0 ],
              //分别对应fnDone, fnFail, fnProgress
              fn = fns[ i ];
 
            //为何这里不能直接：deferred[ tuple[1] ](fn)
 
            // deferred[ done | fail | progress ] for forwarding actions to newDefer
            // tuple[1] = [ done | fail | progress ]
            deferred[ tuple[1] ]( jQuery.isFunction( fn ) ?
              function() {
                //当前的this == deferred
                var returned = fn.apply( this, arguments );
 
                //如果回调返回的是一个Deferred实例
                if ( returned && jQuery.isFunction( returned.promise ) ) {
                  //则继续派发事件
                  returned.promise()
                    .done( newDefer.resolve )
                    .fail( newDefer.reject )
                    .progress( newDefer.notify );
                } 
                //如果回调返回的是不是一个Deferred实例，则被当做args由XXXWith派发出去
                else {
                  newDefer[ action + "With" ]( this === deferred ? newDefer : this, [ returned ] );
                }
              } :
              //传进来的不是函数
              //则默认调用[resolve | reject | notify]派发事件出去
              newDefer[ action ]
            );
          });
          //这里的fns已经没用了，有用的fn引用已经被记录了
          //退出前手工设置null避免闭包造成的内存占用
          fns = null;
        }).promise();
      },
 
      // Get a promise for this deferred
      // If obj is provided, the promise aspect is added to the object
      //在这里obj绑定了[resolve | reject | notify]这些方法
      //还记得例子中的 return deferred.promise()
      //就是因为不想把[resolve | reject | notify]这几个函数暴露出去
      promise: function( obj ) {
        return obj != null ? jQuery.extend( obj, promise ) : promise;
      }
    },
    //最终生成的异步队列实例
    deferred = {};
 
  // Keep pipe for back-compat
  //这句是为了兼容旧版
  promise.pipe = promise.then;
 
  // Add list-specific methods
  //初始化三条Callbacks队列
  jQuery.each( tuples, function( i, tuple ) {
    var list = tuple[ 2 ],//队列
      stateString = tuple[ 3 ];//最后状态
 
    // promise[ done | fail | progress ] = list.add
    //tuple[1] == done | fail | progress 
    //可以看到 done|fail|progress其实就是Callbacks里边的add方法
    promise[ tuple[1] ] = list.add;
 
    // Handle state
    //成功|失败
    //处理中是没有最后状态的！
    if ( stateString ) {
        //成功和失败默认的3个回调
        list.add(
          //1、修改最终状态
          function() {
            // state = [ resolved | rejected ]
            state = stateString;
 
          }, 
          //2、禁用对立的那条队列
          //注意 0^1 = 1   1^1 = 0
          //即是成功的时候，把失败那条队列禁用
          //即是成功的时候，把成功那条队列禁用
          // [ reject_list | resolve_list ].disable; progress_list.lock
          tuples[ i ^ 1 ][ 2 ].disable, 
 
          //3、锁住当前队列状态
          tuples[ 2 ][ 2 ].lock
      );
    }
 
    // deferred[ resolve | reject | notify ] = list.fire
    //tuple[0] == resolve | reject | notify 
    //可以看到 resolve|reject|notify其实就是Callbacks里边的fire方法
    //而resolveWith|rejectWith|notifyWith其实就是Callbacks里边的fireWith方法
    deferred[ tuple[0] ] = list.fire;
    deferred[ tuple[0] + "With" ] = list.fireWith;
  });
 
  // Make the deferred a promise
  //这一步之前promise和deferred绑定了以下方法
  // deferred[ resolve | reject | notify ]
  // deferred[ resolveWith | rejectWith | notifyWith ]
  // promise[ done | fail | progress | then | always | state | promise ]
 
  //调用内部辅助的promise的promise方法（jQ坑爹，起同样名字）
  //扩展deferred的then | done | fail | progress等方法
  promise.promise( deferred );
  //这里为什么要分成promise跟deferred两个对象呢
  //其实就是因为不想把[resolve | reject | notify]这几个函数暴露出去
  //见上边的promise()源码
 
  // Call given func if any
  //$.Deferred(func)格式，则自动执行任务func
  //并且把当前任务的上下文跟参数设置成当前生成的deferred实例
  if ( func ) {
    func.call( deferred, deferred );
  }
 
  // All done!
  //返回实例
  return deferred;
}

// Deferred helper
//注意到$.when是多任务的
//当一个任务失败的时候，代表整个都失败了。
//任务是Deferred实例，我成为异步任务
//任务是普通function时，我成为同步任务
$.when: function( subordinate /* , ..., subordinateN */ ) {
  var i = 0,
    //arguments是多个任务
    resolveValues = core_slice.call( arguments ),
    length = resolveValues.length,
 
    // the count of uncompleted subordinates
    //还没完成的异步任务数
    remaining = length !== 1 || ( subordinate && jQuery.isFunction( subordinate.promise ) ) ? length : 0,
 
    // the master Deferred. If resolveValues consist of only a single Deferred, just use that.
    //只有一个异步任务的时候
    deferred = remaining === 1 ? subordinate : jQuery.Deferred(),
 
    // Update function for both resolve and progress values
    //用于更新 成功|处理 中两个状态
    //这里不考虑失败的状态是因为：
    //当一个任务失败的时候，代表整个都失败了。
    updateFunc = function( i, contexts, values ) {
      return function( value ) {
        contexts[ i ] = this;
        values[ i ] = arguments.length > 1 ? core_slice.call( arguments ) : value;
        if( values === progressValues ) {//处理中，派发正在处理事件
          deferred.notifyWith( contexts, values );
        } else if ( !( --remaining ) ) {//成功，并且最后剩余的异步任务为0了
          //说明所有任务都成功了，派发成功事件出去
          //事件包含的上下文是当前任务前边的所有任务的一个集合
          deferred.resolveWith( contexts, values );
        }
      };
    },
 
    progressValues, progressContexts, resolveContexts;
 
  // add listeners to Deferred subordinates; treat others as resolved
  //如果只有一个任务，可以不用做维护状态的处理了
  //只有大于1个任务才需要维护任务的状态
  if ( length > 1 ) {
    progressValues = new Array( length );
    progressContexts = new Array( length );
    //事件包含的上下文是当前任务前边的所有任务的一个集合，逐步更新
    resolveContexts = new Array( length );
    for ( ; i < length; i++ ) {
      if ( resolveValues[ i ] && jQuery.isFunction( resolveValues[ i ].promise ) ) {
        //如果是异步任务
 
        resolveValues[ i ].promise()
 
          //成功的时候不断更新自己的状态
          .done( updateFunc( i, resolveContexts, resolveValues ) )
 
          //当一个任务失败的时候，代表整个都失败了。直接派发一个失败即可
          .fail( deferred.reject )
 
          //正在处理的时候也要不断更新自己的状态
          .progress( updateFunc( i, progressContexts, progressValues ) );
      } else {
        //如果是同步任务，则remain不应该计它在内
        --remaining;
      }
    }
  }
 
  // if we're not waiting on anything, resolve the master
  //传进来的任务都是同步任务
  if ( !remaining ) {
    deferred.resolveWith( resolveContexts, resolveValues );
  }
 
  return deferred.promise();
}