Tweaks.

pep-3156.txt

@@ -236,7 +236,8 @@ Some methods in the standard conforming interface return Futures:
   remarks as for ``getaddrinfo()``.
 
 - ``create_transport(...)``.  Creates a transport.  Returns a Future.
-  TBD: Signature.  Do we pass in a protocol or protocol class?
+  TBD: Signature.  Do we pass in a protocol or protocol factory?
+  TBD: Should this be called create_connection()?
 
 - ``start_serving(...)``.  Enters a loop that accepts connections.
   TBD: Signature.  There are two possibilities:
@@ -290,7 +291,10 @@ i.e. no disk files.
   used to cancel the callback.  Note that, unlike ``call_later()``,
   the callback may be called many times.  Calling ``add_reader()``
   again for the same file descriptor implicitly cancels the previous
-  callback for that file descriptor.
+  callback for that file descriptor.  (TBD: Returning a
+  ``DelayedCall`` that can be cancelled seems awkward.  Let's forget
+  about that.)  (TBD: Change this to raise an exception if a handler
+  is already set.)
 
 - ``add_writer(fd, callback, *args)``.  Like ``add_reader()``,
   but registers the callback for writing instead of for reading.
@@ -300,11 +304,19 @@ i.e. no disk files.
   currently set for the file descriptor.  (The reason for providing
   this alternate interface is that it is often more convenient to
   remember the file descriptor than to remember the ``DelayedCall``
-  object.)
+  object.)  (TBD: Return ``True`` if a handler was removed, ``False``
+  if not.)
 
 - ``remove_writer(fd)``.  This is to ``add_writer()`` as
   ``remove_reader()`` is to ``add_reader()``.
 
+TBD: What about multiple callbacks per fd?  The current semantics is
+that ``add_reader()/add_writer()`` replace a previously registered
+callback.
+
+TBD: Should ``remove_*()`` return a bool telling is whether it removed
+anything?
+
 The following methods for doing async I/O on sockets are optional.
 They are alternative to the previous set of optional methods, intended
 for transport implementations on Windows using IOCP (if the event loop
@@ -411,7 +423,8 @@ exceptions.)
 TBD: Public attribute recording the realtime value when the callback
 is scheduled?  (Since this is needed anyway for storing it in a heap.)
 
-TBD: A better name for the class?
+TBD: A better name for the class?  Reasonable suggestions so far:
+``Callback``, ``Call``, ``Handler`` (my current favorite).
 
 Futures
 -------
@@ -427,7 +440,8 @@ indicating the differences with PEP 3148:
 - ``cancelled()``.
 
 - ``running()``.  Note that the meaning of this method is essentially
-  "cannot be cancelled and isn't done yet".
+  "cannot be cancelled and isn't done yet".  (TBD: Would be nice if
+  this could be set *and* cleared in some cases, e.g. sock_recv().)
 
 - ``done()``.