asyncio: Document EventLoop.close().

3 files changed, 20 insertions, 0 deletions

diff --git a/Lib/asyncio/base_events.py b/Lib/asyncio/base_events.py
index f18a556..6e409ea 100644
--- a/Lib/asyncio/base_events.py
+++ b/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
diff --git a/Lib/asyncio/events.py b/Lib/asyncio/events.py
index a47253a..7ebc3cb 100644
--- a/Lib/asyncio/events.py
+++ b/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.
 
diff --git a/Lib/test/test_asyncio/test_events.py b/Lib/test/test_asyncio/test_events.py
index fd2af2e..83d7397 100644
--- a/Lib/test/test_asyncio/test_events.py
+++ b/Lib/test/test_asyncio/test_events.py
@@ -1472,6 +1472,8 @@ class AbstractEventLoopTests(unittest.TestCase):
         self.assertRaises(
             NotImplementedError, loop.is_running)
         self.assertRaises(
+            NotImplementedError, loop.close)
+        self.assertRaises(
             NotImplementedError, loop.call_later, None, None)
         self.assertRaises(
             NotImplementedError, loop.call_at, f, f)