[Python-checkins] peps: Add Protocol.eof_received() and protocol call sequence chart.

[guido.van.rossum]

http://hg.python.org/peps/rev/01dd5725807e
changeset:   4611:01dd5725807e
user:        Guido van Rossum <guido at google.com>
date:        Fri Dec 14 15:36:20 2012 -0800
summary:
  Add Protocol.eof_received() and protocol call sequence chart.

files:
  pep-3156.txt |  17 ++++++++++++++---
  1 files changed, 14 insertions(+), 3 deletions(-)


diff --git a/pep-3156.txt b/pep-3156.txt
--- a/pep-3156.txt
+++ b/pep-3156.txt
@@ -582,6 +582,11 @@
 
   (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
+  ``connection_lost()`` to be called (eventually) on the protocol.
+
 - ``connection_lost(exc)``.  The transport has been closed or aborted,
   has detected that the other end has closed the connection cleanly,
   or has encountered an unexpected error.  In the first three cases
@@ -589,9 +594,15 @@
   the exception that caused the transport to give up.  (TBD: Do we
   need to distinguish between the first three cases?)
 
-TBD: How do we detect a half-close (``write_eof()`` in our parlance)
-initiated by the other end?  Does this call connection_lost()?  Is the
-protocol then allowed to write more?  (I think it should be!)
+Here is a chart indicating the order and multiplicity of calls:
+
+  1. ``connection_made()`` -- exactly once
+  2. ``data_received()`` -- zero or more times
+  3. ``eof_received()`` -- at most once
+  4. ``connection_lost()`` -- exactly once
+
+TBD: Discuss whether user code needs to do anything to make sure that
+protocol and transport aren't garbage-collected prematurely.
 
 Callback Style
 --------------

-- 
Repository URL: http://hg.python.org/peps