Clarify the semantics of closing channels.

ericsnowcurrently · Sep 22, 2017 · Sep 15, 2017 · Sep 16, 2017 · Sep 16, 2017 · Sep 22, 2017
commit 84eec8fb565682642ae72d919ce91f5de969ec2f
diff --git a/pep-0554.rst b/pep-0554.rst
@@ -161,43 +161,50 @@ channels have no buffer.
 
    interpreters:
 
-      The list of associated interpreters (those that have called
-      the "recv()" method).
+      The list of associated interpreters: those that have called
+      the "recv()" or "__next__()" methods and haven't called "close()".
 
    __next__():
 
       Return the next object from the channel.  If none have been sent
-      then wait until the next send.
+      then wait until the next send.  See the recv() method.
 
    recv():
 
       Return the next object from the channel.  If none have been sent
-      then wait until the next send.  If the channel has been closed
-      then EOFError is raised.
+      then wait until the next send.  This associates the current
+      interpreter with the channel.
+
+      If the channel is already closed (see the close() method)
+      then raise EOFError.  If the channel isn't closed, but the current
+      interpreter already called the "close()" method (which drops its
+      association with the channel) then raise ValueError.
 
    recv_nowait(default=None):
 
       Return the next object from the channel.  If none have been sent
-      then return the default.  If the channel has been closed
-      then EOFError is raised.
+      then return the default.  Otherwise, this is the same as the
+      "recv()" method.
 
    close():
 
       No longer associate the current interpreter with the channel (on
-      the receiving end).  This is a noop if the interpreter isn't
-      already associated.  Once an interpreter is no longer associated
-      with the channel, subsequent (or current) send() and recv() calls
-      from that interpreter will raise EOFError.
+      the receiving end) and block future association (via the "recv()"
+      method.  If the interpreter was never associated with the channel
+      then still block future association.  Once an interpreter is no
+      longer associated with the channel, subsequent (or current) send()
+      and recv() calls from that interpreter will raise ValueError
+      (or EOFError if the channel is actually marked as closed).
 
-      Once number of associated interpreters on both ends drops to 0,
-      the channel is actually marked as closed.  The Python runtime
-      will garbage collect all closed channels.  Note that "close()" is
-      automatically called when it is no longer used in the current
-      interpreter.
+      Once the number of associated interpreters on both ends drops
+      to 0, the channel is actually marked as closed.  The Python
+      runtime will garbage collect all closed channels, though it may
+      not be immediately.  Note that "close()" is automatically called
+      in behalf of the current interpreter when the channel is no longer
+      used in that interpreter.
 
-      This operation is idempotent.  Return True if the current
-      interpreter was still associated with the receiving end of the
-      channel and False otherwise.
+      This operation is idempotent.  Return True if "close()" has not
+      been called before by the current interpreter.
 
 
 ``SendChannel(id)``::
@@ -217,36 +224,26 @@ channels have no buffer.
 
    send(obj):
 
-       Send the object to the receiving end of the channel.  Wait until
-       the object is received.  If the channel does not support the
-       object then TypeError is raised.  Currently only bytes are
-       supported.  If the channel has been closed then EOFError is
-       raised.
+      Send the object to the receiving end of the channel.  Wait until
+      the object is received.  If the channel does not support the
+      object then TypeError is raised.  Currently only bytes are
+      supported.
+
+      If the channel is already closed (see the close() method)
+      then raise EOFError.  If the channel isn't closed, but the current
+      interpreter already called the "close()" method (which drops its
+      association with the channel) then raise ValueError.
 
    send_nowait(obj):
 
        Send the object to the receiving end of the channel.  If the
-       object is received then return True.  Otherwise return False.
-       If the channel does not support the object then TypeError is
-       raised.  If the channel has been closed then EOFError is raised.
+       object is received then return True.  If not then return False.
+       Otherwise, this is the same as the "send()" method.
 
    close():
 
-      No longer associate the current interpreter with the channel (on
-      the sending end).  This is a noop if the interpreter isn't already
-      associated.  Once an interpreter is no longer associated with the
-      channel, subsequent (or current) send() and recv() calls from that
-      interpreter will raise EOFError.
-
-      Once number of associated interpreters on both ends drops to 0,
-      the channel is actually marked as closed.  The Python runtime
-      will garbage collect all closed channels.  Note that "close()" is
-      automatically called when it is no longer used in the current
-      interpreter.
-
-      This operation is idempotent.  Return True if the current
-      interpreter was still associated with the sending end of the
-      channel and False otherwise.
+      This is the same as "RecvChannel.close(), but applied to the
+      sending end of the channel.
 
 
 Examples