Choose cancelled. Add/remove connector. Misc small additions.

pep-3156.txt

@@ -160,7 +160,7 @@ A conforming event loop object has the following methods:
 
   - No more calls scheduled with ``call_later()``,
   ``call_repeatedly()``, ``call_soon()``, or
-  ``call_soon_threadsafe()``, except for canceled calls.
+  ``call_soon_threadsafe()``, except for cancelled calls.
 
   - No more registered file descriptors.  It is up to the registering
     party to unregister a file descriptor when it is closed.
@@ -171,6 +171,8 @@ A conforming event loop object has the following methods:
   Note: if you schedule a call with ``call_repeatedly()``, ``run()``
   will not exit until you cancel it.
 
+  TBD: A method to run the loop forever, i.e. until ``stop()`` is called?
+
 - ``stop()``.  Stops the event loop as soon as it is convenient.  It
   is fine to restart the loop with ``run()`` (or one of its variants)
   subsequently.
@@ -203,7 +205,7 @@ A conforming event loop object has the following methods:
 
 - ``call_later(delay, callback, *args)``.  Arrange for
   ``callback(*args)`` to be called approximately ``delay`` seconds in
-  the future, once, unless canceled.  Returns
+  the future, once, unless cancelled.  Returns
   a ``Handler`` object representing the callback, whose
   ``cancel()`` method can be used to cancel the callback.
 
@@ -226,7 +228,7 @@ A conforming event loop object has the following methods:
 - TBD: A way to register a callback that is already wrapped in a
   ``Handler``.  Maybe ``call_soon()`` could just check
   ``isinstance(callback, Handler)``?  It should silently skip
-  a canceled callback.
+  a cancelled callback.
 
 Some methods in the standard conforming interface return Futures:
 
@@ -335,6 +337,13 @@ i.e. no disk files.
 - ``remove_writer(fd)``.  This is to ``add_writer()`` as
   ``remove_reader()`` is to ``add_reader()``.
 
+- ``add_connector(fd, callback, *args)``.  Like ``add_writer()`` but
+  meant to wait for ``connect()`` operations, which on some platforms
+  require different handling (e.g. ``WSAPoll()`` on Windows).
+
+- ``remove_connector(fd)``.  This is to ``remove_writer()`` as
+  ``add_connector()`` is to ``add_writer()``.
+
 TBD: What about multiple callbacks per fd?  The current semantics is
 that ``add_reader()/add_writer()`` replace a previously registered
 callback.  Change this to raise an exception if a callback is already
@@ -433,7 +442,7 @@ Read-only public attributes:
 
 - ``args``.  The argument tuple with which to call the callback function.
 
-- ``canceled``.  True if ``cancel()`` has been called.
+- ``cancelled``.  True if ``cancel()`` has been called.
 
 Note that some callbacks (e.g. those registered with ``call_later()``)
 are meant to be called only once.  Others (e.g. those registered with
@@ -552,8 +561,6 @@ Transports have the following public methods:
     t.write(b'e')
     t.write(b'f')
 
-  (TBD: What about datagram transports?)
-
 - ``writelines(iterable)``.  Equivalent to::
 
     for data in iterable:
@@ -638,8 +645,6 @@ above.)
     p.data_received(b'abc')
     p.data_received(b'def')
 
-  (TBD: What about datagram transports?)
-
 - ``eof_received()``.  This is called when the other end called
   ``write_eof()`` (or something equivalent).  The default
   implementation calls ``close()`` on the transport, which causes
@@ -761,9 +766,9 @@ becomes done when its coroutine returns or raises an exception; if it
 returns a result, that becomes the task's result, if it raises an
 exception, that becomes the task's exception.
 
-Canceling a task that's not done yet prevents its coroutine from
+Cancelling a task that's not done yet prevents its coroutine from
 completing; in this case an exception is thrown into the coroutine
-that it may catch to further handle cancelation, but it doesn't have
+that it may catch to further handle cancellation, but it doesn't have
 to (this is done using the standard ``close()`` method on generators,
 described in PEP 342).
 
@@ -822,7 +827,7 @@ TBD: Be more specific.
 Cancellation
 ------------
 
-TBD.  When a Task is canceled its coroutine may see an exception at
+TBD.  When a Task is cancelled its coroutine may see an exception at
 any point where it is yielding to the scheduler (i.e., potentially at
 any ``yield from`` operation).  We need to spell out which exception
 is raised.
@@ -833,12 +838,9 @@ Also TBD: timeouts.
 Open Issues
 ===========
 
-- How to spell the past tense of 'cancel'?  American usage prefers
-  (though not absolutely dictates) 'canceled' (one ell), but outside
-  the US 'cancelled' (two ells) prevails.  PEP 3148, whose author
-  currently lives in Australia, uses ``cancelled()`` as a method name
-  on its Future class.  Also, even in the US, 'cancellation' seems
-  to be preferred over cancelation.
+- A debugging API?  E.g. something that logs a lot of stuff, or logs
+  unusual conditions (like queues filling up faster than they drain)
+  or even callbacks taking too much time...
 
 - Do we need introspection APIs?  E.g. asking for the read callback
   given a file descriptor.  Or when the next scheduled call is.  Or
@@ -883,6 +885,12 @@ Open Issues
         fs.remove(f)
         <inspect f>        
 
+- Support for datagram protocols, "connected" or otherwise?  Probably
+  need more socket I/O methods, e.g. ``sock_sendto()`` and
+  ``sock_recvfrom()``.  Or users can write their own (it's not rocket
+  science).  Is it reasonable to map ``write()``, ``writelines()``,
+  ``data_received()`` to single datagrams?
+
 - Task or callback priorities?  (I hope not.)