深入tornado中的协程

class Future(object):
    ‘‘‘
        Future对象主要保存一个回调函数列表_callbacks与一个执行结果_result，当我们set_result时，就会执行_callbacks中的函数
        如果set_result或者set_done，就会遍历_callbacks列表并执行callback(self)函数
    ‘‘‘
    def __init__(self):
        self._result = None    # 执行的结果
        self._callbacks = []    # 用来保存该future对象的回调函数

    def result(self, timeout=None):
        # 如果操作成功，返回结果。如果失败则抛出异常
        self._clear_tb_log()
        if self._result is not None:
            return self._result
        if self._exc_info is not None:
            raise_exc_info(self._exc_info)
        self._check_done()
        return self._result

    def add_done_callback(self, fn):
        if self._done:
            fn(self)
        else:
            self._callbacks.append(fn)

    def set_result(self, result):
        self._result = result
        self._set_done()

    def _set_done(self):
        # 执行结束(成功)后的操作。
        self._done = True
        for cb in self._callbacks:
            try:
                cb(self)
            except Exception:
                app_log.exception(‘Exception in callback %r for %r‘, cb, self)
        self._callbacks = None

def coroutine(func, replace_callback=True):
    return _make_coroutine_wrapper(func, replace_callback=True)

def _make_coroutine_wrapper(func, replace_callback):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        ‘‘‘
            大体过程：
            future = TracebackFuture()  
            result = func(*args, **kwargs)
            if isinstance(result, GeneratorType):
                yielded = next(result)
                Runner(result, future, yielded)
            return future
        ‘‘‘
        future = TracebackFuture()                   # TracebackFuture = Future

        if replace_callback and ‘callback‘ in kwargs:
            callback = kwargs.pop(‘callback‘)
            IOLoop.current().add_future(future, lambda future: callback(future.result()))

        try:
            result = func(*args, **kwargs)           # 执行func，若func中包含yield，则返回一个generator对象
        except (Return, StopIteration) as e:
            result = _value_from_stopiteration(e)
        except Exception:
            future.set_exc_info(sys.exc_info())
            return future
        else:
            if isinstance(result, GeneratorType):      # 判断其是否为generator对象
                try:
                    orig_stack_contexts = stack_context._state.contexts
                    yielded = next(result)            # 第一次执行
                    if stack_context._state.contexts is not orig_stack_contexts:
                        yielded = TracebackFuture()
                        yielded.set_exception(
                            stack_context.StackContextInconsistentError(
                                ‘stack_context inconsistency (probably caused ‘
                                ‘by yield within a "with StackContext" block)‘))
                except (StopIteration, Return) as e:
                    future.set_result(_value_from_stopiteration(e))
                except Exception:
                    future.set_exc_info(sys.exc_info())
                else:
                    Runner(result, future, yielded)　　# Runner(result, future, yield)
                try:
                    return future　　　　　　　　　　　　
                finally:
                    future = None
        future.set_result(result)
        return future
    return wrapper

if self.handle_yield(first_yielded): # 运行
    self.run()

def handle_yield(self, yielded):
        self.future = convert_yielded(yielded)                         # 如果yielded是Future对象则原样返回
        if not self.future.done() or self.future is moment:            # moment是tornado初始化时就建立的一个Future对象，且被set_result(None)
            self.io_loop.add_future(self.future, lambda f: self.run()) # 为该future添加callback
            return False
        return True

def add_future(self, future, callback):
    # 为future添加一个回调函数，这个回调函数的作用是：将参数callback添加至self._callbacks中
    # 大家思考一个问题： 如果某个Future对象被set_done,那么他的回调函数应该在什么时候执行？ 
    # 是立即执行亦或者是将回调函数添加到IOLoop实例的_callbacks中进行统一执行？ 
    # 虽然前者更简单，但导致回调函数的执行过于混乱，我们应该让所有满足执行条件的回调函数统一执行。显然后者更合理
    # 而add_future()的作用就是这样
    future.add_done_callback(lambda future: self.add_callback(callback, future))
        
def add_callback(self, callback, *args, **kwargs):
    # 将callback添加至_callbacks列表中
    self._callbacks.append(functools.partial(callback, *args, **kwargs))

    def run(self):
        """Starts or resumes the generator, running until it reaches a
        yield point that is not ready. 循环向generator中传递值，直到某个yield返回的yielded还没有被done
        """
        try:
            self.running = True 
            while True:
                future = self.future　　
                if not future.done():
                    return
                self.future = None　　　　　　# 清空self.future
                value = future.result()　　　# 获取future对象的结果
                try:    
                    yielded = self.gen.send(value)　　# send该结果，并将self.gen返回的值赋值给yielded(一般情况下这也是个future对象)
                except (StopIteration, Return) as e:
                    self.finished = True
                    self.future = _null_future
                    self.result_future.set_result(_value_from_stopiteration(e))
                    self.result_future = None
                    self._deactivate_stack_context()
                    return
                if not self.handle_yield(yielded):　　# 运行self.handler_yield(yielded)，如果yielded对象没有被done，则直接返回；否则继续循环
                    return
        finally:
            self.running = False