asyncio: Document EventLoop.close().

Lib/asyncio/base_events.py

@@ -186,6 +186,11 @@ class BaseEventLoop(events.AbstractEventLoop):
         self.call_soon(_raise_stop_error)
 
     def close(self):
+        """Close the event loop.
+
+        This clears the queues and shuts down the executor,
+        but does not wait for the executor to finish.
+        """
         self._ready.clear()
         self._scheduled.clear()
         executor = self._default_executor

Lib/asyncio/events.py

@@ -137,6 +137,17 @@ class AbstractEventLoop:
         """Return whether the event loop is currently running."""
         raise NotImplementedError
 
+    def close(self):
+        """Close the loop.
+
+        The loop should not be running.
+
+        This is idempotent and irreversible.
+
+        No other methods should be called after this one.
+        """
+        raise NotImplementedError
+
     # Methods scheduling callbacks.  All these return Handles.
 
     def call_soon(self, callback, *args):
@@ -214,6 +225,8 @@ class AbstractEventLoop:
                                  family=0, proto=0, flags=0):
         raise NotImplementedError
 
+    # Pipes and subprocesses.
+
     def connect_read_pipe(self, protocol_factory, pipe):
         """Register read pipe in eventloop.
 

Lib/test/test_asyncio/test_events.py

@@ -1471,6 +1471,8 @@ class AbstractEventLoopTests(unittest.TestCase):
             NotImplementedError, loop.stop)
         self.assertRaises(
             NotImplementedError, loop.is_running)
+        self.assertRaises(
+            NotImplementedError, loop.close)
         self.assertRaises(
             NotImplementedError, loop.call_later, None, None)
         self.assertRaises(