asyncio doc: explain why the loop is running twice

1 files changed, 36 insertions, 29 deletions

diff --git a/Doc/library/asyncio-protocol.rst b/Doc/library/asyncio-protocol.rst
index ae519e7..c371c56 100644
--- a/Doc/library/asyncio-protocol.rst
+++ b/Doc/library/asyncio-protocol.rst
@@ -582,6 +582,40 @@ Network functions
 Protocol example: TCP echo server and client
 ============================================
 
+Echo client
+-----------
+
+TCP echo client example, send data and wait until the connection is closed::
+
+    import asyncio
+
+    class EchoClient(asyncio.Protocol):
+        message = 'This is the message. It will be echoed.'
+
+        def connection_made(self, transport):
+            transport.write(self.message.encode())
+            print('data sent: {}'.format(self.message))
+
+        def data_received(self, data):
+            print('data received: {}'.format(data.decode()))
+
+        def connection_lost(self, exc):
+            print('server closed the connection')
+            asyncio.get_event_loop().stop()
+
+    loop = asyncio.get_event_loop()
+    coro = loop.create_connection(EchoClient, '127.0.0.1', 8888)
+    loop.run_until_complete(coro)
+    loop.run_forever()
+    loop.close()
+
+The event loop is running twice. The
+:meth:`~BaseEventLoop.run_until_complete` method is preferred in this short
+example to raise an exception if the server is not listening, instead of
+having to write a short coroutine to handle the exception and stop the
+running loop. At :meth:`~BaseEventLoop.run_until_complete` exit, the loop is
+no more running, so there is no need to stop the loop in case of an error.
+
 Echo server
 -----------
 
@@ -603,8 +637,8 @@ TCP echo server example, send back received data and close the connection::
             self.transport.close()
 
     loop = asyncio.get_event_loop()
-    task = loop.create_server(EchoServer, '127.0.0.1', 8888)
-    server = loop.run_until_complete(task)
+    coro = loop.create_server(EchoServer, '127.0.0.1', 8888)
+    server = loop.run_until_complete(coro)
     print('serving on {}'.format(server.sockets[0].getsockname()))
 
     try:
@@ -621,30 +655,3 @@ methods are asynchronous. ``yield from`` is not needed because these transport
 methods don't return coroutines.
 
 
-Echo client
------------
-
-TCP echo client example, send data and wait until the connection is closed::
-
-    import asyncio
-
-    class EchoClient(asyncio.Protocol):
-        message = 'This is the message. It will be echoed.'
-
-        def connection_made(self, transport):
-            transport.write(self.message.encode())
-            print('data sent: {}'.format(self.message))
-
-        def data_received(self, data):
-            print('data received: {}'.format(data.decode()))
-
-        def connection_lost(self, exc):
-            print('server closed the connection')
-            asyncio.get_event_loop().stop()
-
-    loop = asyncio.get_event_loop()
-    task = loop.create_connection(EchoClient, '127.0.0.1', 8888)
-    loop.run_until_complete(task)
-    loop.run_forever()
-    loop.close()
-