fast_io Improve code comments around pend_throw.

Author: peterhinch

fast_io/__init__.py

@@ -103,7 +103,7 @@ def wait(self, delay):
                 if isinstance(cb, tuple):
                     cb[0](*cb[1])
                 else:
-                    cb.pend_throw(None)  # Clears the pend_throw(False) executed when IOWrite was yielded
+                    cb.pend_throw(None)  # Ensure that, if task is cancelled, it doesn't get queued again
                     self._call_io(cb)  # Put coro onto runq (or ioq if one exists)
             if ev & select.POLLIN:
                 cb = self.rdobjmap[id(sock)]

fast_io/core.py

@@ -200,7 +200,8 @@ def run_forever(self):
                                 if isinstance(ret, After):
                                     delay = int(delay*1000)
                         elif isinstance(ret, IORead):  # coro was a StreamReader read method
-                            cb.pend_throw(False)  # Why? I think this is for debugging. If it is scheduled other than by wait
+                            cb.pend_throw(False)  # If task is cancelled or times out, it is put on runq to process exception.
+                            # Note if it is scheduled other than by wait
                             # (which does pend_throw(None) an exception (exception doesn't inherit from Exception) is thrown
                             self.add_reader(arg, cb)  # Set up select.poll for read and store the coro in object map
                             continue  # Don't reschedule. Coro is scheduled by wait() when poll indicates h/w ready
@@ -361,7 +362,7 @@ def __next__(self):
 
 def cancel(coro):
     prev = coro.pend_throw(CancelledError())
-    if prev is False:
+    if prev is False:  # Not on runq so put it there
         _event_loop.call_soon(coro)