10 | Tornado源码分析：Gen 对象(上)

# -*- encoding: utf-8 -*-
# !/usr/bin/python
"""
@File    : gen_ll.py
@Time    : 2020/08/29 15:10
@Author  : haishiniu
@Software: PyCharm
"""
# gen 模块是 "协程" 的实现。

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

# 1：创建协程
def _make_coroutine_wrapper(func, replace_callback):
    wrapped = func
    if hasattr(types, 'coroutine'):
        func = types.coroutine(func)

    # wrapper 表示代表一个协程对象；启动协程，会返回一个Future对象。
    @functools.wraps(wrapped)
    def wrapper(*args, **kwargs):
        # 生成一个绑定到该协程的Future对象
        future = TracebackFuture()
        if replace_callback and 'callback' in kwargs:
            # 当 replace_callback为True，并且通过关键字参数callback指定了回调函数，那么当Future对象完成时，它会将回调函数
            # lambda future: callback(future.result())
            # 添加到当前线程的IOLoop上，在下一次事件循环时，
            # 就会执行这个回调函数
            callback = kwargs.pop('callback')
            IOLoop.current().add_future(future, lambda future: callback(future.result()))

        try:
            # 调用被封装的函数（重点）
            result = func(*args, **kwargs)
        except (Return, StopIteration) as e:
            # 若抛出了gen.Return或StopIteration异常，
            # 那么则从异常对象中提取执行结果，并将结果保存到Future对象，协程执行结束。
            result = _value_from_stopiteration(e)
        except Exception:
            # 若出现其他异常，那么将异常信息保存到Future对象，协程执行结束。
            future.set_exc_info(sys.exc_info())
            return future
        else:
            if isinstance(result, types.GeneratorType):
                # 若被封装的函数是一个生成器函数，那么调用它会返回一个生成器，接下来，会启动生成器。
                # 之所以在这里启动生成器是因为很多生成器协程并不会真正的yield，也就说，在执行过程中，所经历的分支上，并没有yield语句，所以直接在这里进行迭代，以避免创建Runner对象，提升性能。
                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:
                    # 若抛出了gen.Return或StopIteration异常，那么则从异常对象中提取执行结果，并将结果保存到Future对象，协程执行结束。
                    future.set_result(_value_from_stopiteration(e))
                except Exception:
                    # 若出现其他异常，那么，将异常信息保存到Future对象，协程执行结束。
                    future.set_exc_info(sys.exc_info())
                else:
                    # 否则，使用 生成器、代表协程执行结果的Future对象、以及生成器第一次yield的值创建Runner对象
                    _futures_to_runners[future] = Runner(result, future, yielded)
                yielded = None

                try:
                    return future
                finally:
                    future = None
        future.set_result(result)
        return future

    # 将被封装的函数保存到协程对象的属性中（编程技巧）
    wrapper.__wrapped__ = wrapped
    # 给协程对象设置一个标记，拥有该标记的对象就是一个tornado协程对象
    wrapper.__tornado_coroutine__ = True
    # 返回协程对象
    return wrapper