Resolve a few TBD/TODOs.

pep-3156.txt

@@ -740,8 +740,7 @@ non-blocking socket.
   ``None``.  Note: the name uses ``sendall`` instead of ``send``, to
   reflect that the semantics and signature of this method echo those
   of the standard library socket method ``sendall()`` rather than
-  ``send()``.  (TBD: but maybe it would be better to emulate
+  ``send()``.
-  ``send()`` after all?  That would be better for datagram sockets.)
 
 - ``sock_connect(sock, address)``.  Connect to the given address.
   Returns a Future whose result on success will be ``None``.
@@ -962,11 +961,16 @@ futures this should be understood to refer to ``asyncio.Future`` unless
 ``concurrent.futures.Future`` is explicitly mentioned.  The supported
 public API is as follows, indicating the differences with PEP 3148:
 
-- ``cancel()``.  If the Future is already done (or cancelled), return
+- ``cancel()``.  If the Future is already done (or cancelled), do
-  ``False``.  Otherwise, change the Future's state to cancelled (this
+  nothing and return ``False``.  Otherwise, this attempts to cancel
-  implies done), schedule the callbacks, and return ``True``.
+  the Future and returns ``True``.  If the the cancellation attempt is
+  successful, eventually the Future's state will change to cancelled
+  and the callbacks will be scheduled.  For regular Futures,
+  cancellation will always succeed immediately; but for Tasks (see
+  below) the task may ignore or delay the cancellation attempt.
 
-- ``cancelled()``.  Returns ``True`` if the Future was cancelled.
+- ``cancelled()``.  Returns ``True`` if the Future was successfully
+  cancelled.
 
 - ``done()``.  Returns ``True`` if the Future is done.  Note that a
   cancelled Future is considered done too (here and everywhere).
@@ -1031,8 +1035,7 @@ The following exceptions are defined:
 - ``TimeoutError``.  An alias for ``concurrent.futures.TimeoutError``.
   May be raised by ``run_until_complete()``.
 
-A Future is associated with the default event loop when it is created.
+A Future is associated with an event loop when it is created.
-(TBD: Optionally pass in an alternative event loop instance?)
 
 A ``asyncio.Future`` object is not acceptable to the ``wait()`` and
 ``as_completed()`` functions in the ``concurrent.futures`` package.
@@ -1045,9 +1048,10 @@ when used in a coroutine.  This is implemented through the
 and the Scheduler" below.
 
 When a Future is garbage-collected, if it has an associated exception
-but neither ``result()`` nor ``exception()`` nor ``__iter__()`` has
+but neither ``result()`` nor ``exception()`` has ever been called, the
-ever been called (or the latter hasn't raised the exception yet --
+exception is logged.  (When a coroutine uses ``yield from`` to wait
-details TBD), the exception is logged.
+for a Future, that Future's ``result()`` method is called once the
+coroutine is resumed.)
 
 In the future (pun intended) we may unify ``asyncio.Future`` and
 ``concurrent.futures.Future``, e.g. by adding an ``__iter__()`` method
@@ -1171,10 +1175,13 @@ Bidirectional stream transports have the following public methods:
 - ``pause_reading()``.  Suspend delivery of data to the protocol until
   a subsequent ``resume_reading()`` call.  Between ``pause_reading()``
   and ``resume_reading()``, the protocol's ``data_received()`` method
-  will not be called.  This has no effect on ``write()``.
+  will not be called.
 
 - ``resume_reading()``.  Restart delivery of data to the protocol via
-  ``data_received()``.
+  ``data_received()``.  Note that "paused" is a binary state --
+  ``pause_reading()`` should only be called when the transport is not
+  paused, while ``resume_reading()`` should only be called when the
+  transport is paused.
 
 - ``close()``.  Sever the connection with the entity at the other end.
   Any data buffered by ``write()`` will (eventually) be transferred
@@ -1187,17 +1194,7 @@ Bidirectional stream transports have the following public methods:
 - ``abort()``.  Immediately sever the connection.  Any data still
   buffered by the transport is thrown away.  Soon, the protocol's
   ``connection_lost()`` method will be called with ``None`` as
-  argument.  (TBD: Distinguish in the ``connection_lost()`` argument
+  argument.
-  between ``close()``, ``abort()`` or a close initated by the other
-  end?  Or add a transport method to inquire about this?  Glyph's
-  proposal was to pass different exceptions for this purpose.)
-
-TBD: Provide flow control the other way -- the transport may need to
-suspend the protocol if the amount of data buffered becomes a burden.
-Proposal: let the transport call ``protocol.pause_writing()`` and
-``protocol.resume_writing()`` if they exist; if they don't exist, the
-protocol doesn't support flow control.  (Perhaps different names
-to avoid confusion between protocols and transports?)
 
 Unidirectional Stream Transports
 ''''''''''''''''''''''''''''''''
@@ -1245,8 +1242,8 @@ endpoint has been created, and ``connection_lost()`` means the
 transport is closed.  The ``connection_refused()`` method is called
 before ``connection_lost()`` when ``remote_addr`` was given and an
 explicit negative acknowledgement was received (this is a UDP
-feature).  (TBD: Do we need the latter?  It seems easy enough to
+feature).  (TBD: Should fix `connection_refused()`` to not close the
-implement this in the protocol if it needs to make the distinction.)
+transport.)
 
 Subprocess Transports
 '''''''''''''''''''''
@@ -1267,8 +1264,6 @@ protocols, and perhaps other custom protocols.  The most common type
 of protocol is a bidirectional stream protocol.  (There are no
 unidirectional protocols.)
 
-(TBD: should protocol callbacks be allowed to be coroutines?)
-
 Stream Protocols
 ''''''''''''''''
 
@@ -1296,6 +1291,9 @@ context.  (See the "Context" section way above.)
   ``write_eof()`` (or something equivalent).  If this returns a false
   value (including None), the transport will close itself.  If it
   returns a true value, closing the transport is up to the protocol.
+  However, for SSL/TLS connections this is ignored, because the TLS
+  standard requires that no more data is sent and the connection is
+  closed as soon as a "closure alert" is received.
 
   The default implementation returns None.
 
@@ -1303,8 +1301,7 @@ context.  (See the "Context" section way above.)
   has detected that the other end has closed the connection cleanly,
   or has encountered an unexpected error.  In the first three cases
   the argument is ``None``; for an unexpected error, the argument is
-  the exception that caused the transport to give up.  (TBD: Do we
+  the exception that caused the transport to give up.
-  need to distinguish between the first three cases?)
 
 Here is a chart indicating the order and multiplicity of calls:
 
@@ -1313,8 +1310,7 @@ Here is a chart indicating the order and multiplicity of calls:
   3. ``eof_received()`` -- at most once
   4. ``connection_lost()`` -- exactly once
 
-TBD: Discuss whether user code needs to do anything to make sure that
+TBD: Document ``pause_writing()`` and ``resume_writing()``.
-protocol and transport aren't garbage-collected prematurely.
 
 Datagram Protocols
 ''''''''''''''''''
@@ -1502,9 +1498,6 @@ Sleeping
 
 The coroutine ``asyncio.sleep(delay)`` returns after a given time delay.
 
-(TBD: Should the optional second argument, ``result``, be part of the
-spec?)
-
 Tasks
 -----
 
@@ -1565,17 +1558,12 @@ off the coroutine when ``connection_made()`` is called.
 TO DO
 =====
 
-- Document pause/resume reading/writing.
+- Document pause/resume_writing.
 
 - Document subprocess/pipe protocols/transports.
 
 - Document locks and queues.
 
-- Describe task cancellation details (and update future cancellation
-  spec to promise less).
-
-- Explain that eof_received() shouldn't return True with SSL/TLS.
-
 - Document SIGCHILD handling API (once it lands).
 
 - Compare all APIs with the source code to be sure there aren't any