Specify start_serving(). Add Post-History.

pep-3156.txt

@@ -7,7 +7,7 @@ Status: Draft
 Type: Standards Track
 Content-Type: text/x-rst
 Created: 12-Dec-2012
-Post-History: TBD
+Post-History: 21-Dec-2012
 
 Abstract
 ========
@@ -257,7 +257,8 @@ Some methods in the standard conforming interface return Futures:
   format as returned by ``socket.getaddrinfo()``.  The default
   implementation calls ``socket.getaddrinfo()`` using
   ``run_in_executor()``, but other implementations may choose to
-  implement their own DNS lookup.
+  implement their own DNS lookup.  The optional arguments *must* be
+  specified as keyword arguments.
 
 - ``getnameinfo(sockaddr, flags=0)``.  Similar to
   ``socket.getnameinfo()`` but returns a Future.  The Future's result
@@ -267,7 +268,8 @@ Some methods in the standard conforming interface return Futures:
 - ``create_transport(protocol_factory, host, port, **kwargs)``.
   Creates a transport and a protocol and ties them together.  Returns
   a Future whose result on success is a (transport, protocol) pair.
-  Note that when the Future completes, the protocol's
+  The protocol is created by calling ``protocol_factory()`` without
+  arguments.  Note that when the Future completes, the protocol's
   ``connection_made()`` method has not yet been called; that will
   happen when the connection handshake is complete.  When it is
   impossible to connect to the given host and port, the Future will
@@ -286,36 +288,31 @@ Some methods in the standard conforming interface return Futures:
 
   TBD: Should this be called create_connection()?
 
-- ``start_serving(...)``.  Enters a loop that accepts connections.
-  TBD: Signature.  There are two possibilities:
+- ``start_serving(protocol_factory, host, port, **kwds)``.  Enters a
+  loop that accepts connections.  Returns a Future that completes once
+  the loop is set up to serve; its return value is None.  Each time a
+  connection is accepted, ``protocol_factory`` is called without
+  arguments to create a protocol, a transport is created to represent
+  the network side of the connection, and the two are tied together by
+  calling ``protocol.connection_made(transport)``.
 
-  1. You pass it a non-blocking socket that you have already prepared
-     with ``bind()`` and ``listen()`` (these system calls do not block
-     AFAIK), a protocol factory (I hesitate to use this word :-), and
-     optional flags that control the transport creation (e.g. ssl).
+  Optional keyword arguments:
 
-  2. Instead of a socket, you pass it a host and port, and some more
-     optional flags (e.g. to control IPv4 vs IPv6, or to set the
-     backlog value to be passed to ``listen()``).
+  - ``family``, ``type``, ``proto``, ``flags``: Address familty,
+    socket type, protcol, and miscellaneous flags to be passed through
+    to ``getaddrinfo()``.  These all default to ``0`` except ``type``
+    which defaults to ``socket.SOCK_STREAM``.
 
-  In either case, once it has a socket, it will wrap it in a
-  transport, and then enter a loop accepting connections (the best way
-  to implement such a loop depends on the platform).  Each time a
-  connection is accepted, a transport and protocol are created for it.
+  TBD: Support SSL?  I don't even know how to do that synchronously,
+  and I suppose it needs a certificate.
 
-  This should return an object that can be used to control the serving
-  loop, e.g. to stop serving, abort all active connections, and (if
-  supported) adjust the backlog or other parameters.  It may also have
-  an API to inquire about active connections.  If version (2) is
-  selected, it should probably return a Future whose result on success
-  will be that control object, and which becomes done once the accept
-  loop is started.
-
-  TBD: It may be best to use version (2), since on some platforms the
-  best way to start a server may not involve sockets (but will still
-  involve transports and protocols).
-
-  TBD: Be more specific.
+  TBD: Maybe make the Future's result an object that can be used to
+  control the serving loop, e.g. to stop serving, abort all active
+  connections, and (if supported) adjust the backlog or other
+  parameters?  It could also have an API to inquire about active
+  connections.  Alternatively, return a Future (subclass?) that only
+  completes if the loop stops serving due to an error, or if it cannot
+  be started?  Cancelling it might stop the loop.
 
 TBD: Some platforms may not be interested in implementing all of
 these, e.g. start_serving() may be of no interest to mobile apps.