Gevent（3）调度核心：gevent.hub

class Waiter(object):
    """
    A low level communication utility for greenlets.

    Waiter is a wrapper around greenlet's ``switch()`` and ``throw()`` calls that makes them somewhat safer:

    * switching will occur only if the waiting greenlet is executing :meth:`get` method currently;
    * any error raised in the greenlet is handled inside :meth:`switch` and :meth:`throw`
    * if :meth:`switch`/:meth:`throw` is called before the receiver calls :meth:`get`, then :class:`Waiter`
      will store the value/exception. The following :meth:`get` will return the value/raise the exception.

    The :meth:`switch` and :meth:`throw` methods must only be called from the :class:`Hub` greenlet.
    The :meth:`get` method must be called from a greenlet other than :class:`Hub`.
    ...

    def get(self):
        """If a value/an exception is stored, return/raise it. Otherwise until switch() or throw() is called."""
        if self._exception is not _NONE:
            if self._exception is None:
                return self.value
            else:
                getcurrent().throw(*self._exception)
        else:
            if self.greenlet is not None:
                raise ConcurrentObjectUseError('This Waiter is already used by %r' % (self.greenlet, ))
            self.greenlet = getcurrent()
            try:
                return self.hub.switch()
            finally:
                self.greenlet = None

    def switch(self, value=None):
        """Switch to the greenlet if one's available. Otherwise store the value."""
        greenlet = self.greenlet
        if greenlet is None:
            self.value = value
            self._exception = None
        else:
            assert getcurrent() is self.hub, "Can only use Waiter.switch method from the Hub greenlet"
            switch = greenlet.switch
            try:
                switch(value)
            except: # pylint:disable=bare-except
                self.hub.handle_error(switch, *sys.exc_info())

import _thread
_threadlocal = _thread._local()

def get_hub(*args, **kwargs):
    global _threadlocal
    try:
        return _threadlocal.hub
    except AttributeError:
        hubtype = get_hub_class()
        hub = _threadlocal.hub = hubtype(*args, **kwargs)
        return hub

# fileobject.py 中:
# 创建一个 io 类型的 watcher
# 用户监视 fileno 这个文件描述符
self._read_event = io(fileno, 1)
##############################################
# fileobject.py 中:
# IO 完成后阻塞，将当前 greenlet 切换到 hub
# 让出控制权
# 等到感兴趣的 IO 事件发生后
# hub 会切换到这个点，继续执行
self.hub.wait(self._read_event)
##############################################
# Hub:
# hub.wait 函数：
        waiter = Waiter()
        unique = object()
        # 这个 watcher 就是 _read_event
        # 下面将 waiter.switch 这个回调函数，绑定到 watcher 上（io 类型的）
        watcher.start(waiter.switch, unique) 
        try:
            # 切换到 hub, 等待 io 事件被触发
            # 然后 hub 切换到被挂起的 greenlet 继续运行
            result = waiter.get()
        finally:
            watcher.stop()
##############################################
# Wait:
# wait.get 函数:
            self.greenlet = getcurrent()
            try:
                # 切换到 hub
                return self.hub.switch()
            finally:
                self.greenlet = None
##############################################
# Hub:
# hub.switch 函数:
        # 切换到 hub
        return greenlet.switch(self)

loop_class = config('gevent.core.loop', 'GEVENT_LOOP')
...
self.loop = loop_class(flags=loop, default=default)

def wait(self, watcher):
    waiter = Waiter()         # 创建 Waiter 类实例
    unique = object()         # object() 是一个唯一的对象，作为从 main greenlet 返回时的跟踪对象
    watcher.start(waiter.switch, unique) # 将 waiter.switch 这个 callback 附加到 watcher 上，参数为 unique
    try:
        result = waiter.get() # 执行 waiter.get 从当前 greenlet 切换到 main greenlet
                              # 当 watcher 感兴趣的事件发生后，触发调度，从 main greenlet 切换回来，代码继续执行
        assert result is unique, 'Invalid...'
    finally:    
        watcher.stop()

def switch(self):
    switch_out = getattr(getcurrent(), 'switch_out', None) # 在当前 greenlet 对象中寻找 `switch_out` 属性，如果找到就调用。
    if switch_out is not None:
        switch_out()
    return greenlet.switch(self) # 调用 `greenlet.switch(self)`，切换到 hub。

def join(self, timeout=None):
    assert getcurrent() is self.parent, "only possible from the MAIN greenlet"
    if self.dead:
        return True
    waiter = Waiter()                # 初始化一个 Waiter 类的实例
    if timeout is not None:
        timeout = self.loop.timer(timeout, ref=False)
        timeout.start(waiter.switch) # 如果提供了 timeout，会启动超时器，等待 timeout 秒后，在切换到 main greenlet
    try:
        try:
            waiter.get()             # 如果未提供 timeout 参数，则直接切换到 main greenlet
        except LoopExit:
            return True
    finally:
        if timeout is not None:
            timeout.stop() 
    return False 

def run(self):
    assert self is getcurrent(), 'Do not call Hub.run() directly'
    while True:
        loop = self.loop
        loop.error_handler = self
        try:
            loop.run()
        finally:
            loop.error_handler = None  # break the refcount cycle
        self.parent.throw(LoopExit('This operation would block forever'))

class Greenlet(greenlet):
    def __init__(self, run=None, *args, **kwargs):
        hub = get_hub()
        greenlet.__init__(self, parent=hub)

    @classmethod
    def spawn(cls, *args, **kwargs):
        """Return a new :class:`Greenlet` object, scheduled to start.
        The arguments are passed to :meth:`Greenlet.__init__`.
        """
        g = cls(*args, **kwargs)
        g.start()
        return g

    def start(self):
        """Schedule the greenlet to run in this loop iteration"""
        if self._start_event is None:
            self._start_event = self.parent.loop.run_callback(self.switch)


    def run_callback(self, func, *args):
        CHECK_LOOP2(self)
        cdef callback cb = callback(func, args)
        self._callbacks.append(cb)
        libev.ev_ref(self._ptr)
        return cb