Update comments about how loops run. [skip ci]

src/gevent/_ffi/loop.py

@@ -324,13 +324,17 @@ class AbstractLoop(object):
 
 
         # self._check is a watcher that runs in each iteration of the
-        # mainloop, just after the blocking call
+        # mainloop, just after the blocking call. It's point is to handle
+        # signals. It doesn't run watchers or callbacks, it just exists to give
+        # CFFI a chance to raise signal exceptions so we can handle them.
         self._check = self._ffi.new(self._CHECK_POINTER)
         self._check.data = self._handle_to_self
         self._init_and_start_check()
 
         # self._prepare is a watcher that runs in each iteration of the mainloop,
-        # just before the blocking call
+        # just before the blocking call. It's where we run deferred callbacks
+        # from self.run_callback. This cooperates with _setup_for_run_callback()
+        # to schedule self._timer0 if needed.
         self._prepare = self._ffi.new(self._PREPARE_POINTER)
         self._prepare.data = self._handle_to_self
         self._init_and_start_prepare()
@@ -589,6 +593,9 @@ class AbstractLoop(object):
         raise NotImplementedError()
 
     def run_callback(self, func, *args):
+        # If we happen to already be running callbacks (inside
+        # _run_callbacks), this could happen almost immediately,
+        # without the loop cycling.
         cb = callback(func, args)
         self._callbacks.append(cb)
         self._setup_for_run_callback()

src/gevent/libuv/loop.py

@@ -173,23 +173,31 @@ class loop(AbstractLoop):
         # while True:
         #   uv__update_time(loop);
         #   uv__run_timers(loop);
+        #   # we don't use pending watchers. They are how libuv
+        #   # implements the pipe/udp/tcp streams.
         #   ran_pending = uv__run_pending(loop);
         #   uv__run_idle(loop);
         #   uv__run_prepare(loop);
         #   ...
-        #   uv__io_poll(loop, timeout);
+        #   uv__io_poll(loop, timeout); # <--- IO watchers run here!
         #   uv__run_check(loop);
 
         # libev looks something like this (pseudo code because the real code is
         # hard to read):
         #
         # do {
+        #    run_fork_callbacks();
         #    run_prepare_callbacks();
         #    timeout = min(time of all timers or normal block time)
-        #    io_poll()
+        #    io_poll() # <--- Only queues IO callbacks
         #    update_now(); calculate_expired_timers();
-        #    run_timers()
-        #    run_pending()
+        #    run callbacks in this order: (although specificying priorities changes it)
+        #        check
+        #        stat
+        #        child
+        #        signal
+        #        timer
+        #        io
         # }
 
         # So instead of running a no-op and letting the side-effect of spinning