Add Protocol.eof_received() and protocol call sequence chart.

pep-3156.txt

@@ -582,6 +582,11 @@ above.)
 
   (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 @@ above.)
   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
 --------------