pep 525: Add "asyncio" section describing new "shutdown_asyncgens"

pep-0525.txt

@@ -257,6 +257,34 @@ loops running in parallel threads can use it safely.
 with ``firstiter`` and ``finalizer`` fields.
 
 
+asyncio
+-------
+
+The asyncio event loop will use ``sys.set_asyncgen_hooks()`` API to maintain
+a weak set of all scheduled asynchronous generators, and to schedule their
+``aclose()`` coroutine methods when it is time for generators to be GCed.
+
+To make sure that asyncio programs can finalize all scheduled asynchronous
+generators reliably, we propose to add a new event loop method
+``loop.shutdown_asyncgens(*, timeout=30)``.  The method will schedule all
+currently open asynchronous generators to close with an ``aclose()`` call.
+
+After calling the ``loop.shutdown_asyncgens()`` method, the event loop will
+issue a warning whenever a new asynchronous generator is iterated for the first
+time.  The idea is that after requesting all asynchronous generators to be
+shutdown, the program should not execute code that iterates over new
+asynchronous generators.
+
+An example of how ``shutdown_asyncgens`` should be used::
+
+    try:
+        loop.run_forever()
+        # or loop.run_until_complete(...)
+    finally:
+        loop.shutdown_asyncgens()
+        loop.close()
+
+
 Asynchronous Generator Object
 -----------------------------
 
@@ -422,6 +450,9 @@ New Standard Library Functions and Types
 3. ``inspect.isasyncgen()`` and ``inspect.isasyncgenfunction()``
    introspection functions.
 
+4. New method for asyncio event loop:
+   ``loop.shutdown_asyncgens(*, timeout=30)``.
+
 
 Backwards Compatibility
 -----------------------