pep 525: set_asyncgen_finalizer -> set_asyncgen_hooks

pep-0525.txt

@@ -9,7 +9,7 @@ Type: Standards Track
 Content-Type: text/x-rst
 Created: 28-Jul-2016
 Python-Version: 3.6
-Post-History: 02-Aug-2016
+Post-History: 02-Aug-2016, 23-Aug-2016, 01-Sep-2016
 
 
 Abstract
@@ -199,12 +199,20 @@ To solve this problem we propose to do the following:
                                          # RuntimeError.
 
 3. Add two new methods to the ``sys`` module:
-   ``set_asyncgen_finalizer()`` and ``get_asyncgen_finalizer()``.
+   ``set_asyncgen_hooks()`` and ``get_asyncgen_hooks()``.
 
-The idea behind ``sys.set_asyncgen_finalizer()`` is to allow event
-loops to handle generators finalization, so that the end user
-does not need to care about the finalization problem, and it just
-works.
+The idea behind ``sys.set_asyncgen_hooks()`` is to allow event
+loops to intercept asynchronous generators iteration and finalization,
+so that the end user does not need to care about the finalization
+problem, and everything just works.
+
+``sys.set_asyncgen_hooks()`` accepts two arguments:
+
+* ``firstiter``: a callable which will be called when an asynchronous
+  generator is iterated for the first time.
+
+* ``finalizer``: a callable which will be called when an asynchronous
+  generator is about to be GCed.
 
 When an asynchronous generator is iterated for the first time,
 it stores a reference to the current finalizer.  If there is none,
@@ -226,20 +234,28 @@ finalization of asynchronous generators::
 
        def run_forever(self):
            ...
-           old_finalizer = sys.get_asyncgen_finalizer()
-           sys.set_asyncgen_finalizer(self._finalize_asyncgen)
+           old_hooks = sys.get_asyncgen_hooks()
+           sys.set_asyncgen_hooks(finalizer=self._finalize_asyncgen)
            try:
                ...
            finally:
-               sys.set_asyncgen_finalizer(old_finalizer)
+               sys.set_asyncgen_hooks(*old_hooks)
                ...
 
        def _finalize_asyncgen(self, gen):
            self.create_task(gen.aclose())
 
-``sys.set_asyncgen_finalizer()`` is thread-specific, so several event
+The second argument, ``firstiter``, allows event loops to maintain
+a weak set of asynchronous generators instantiated under their control.
+This makes it possible to implement "shutdown" mechanisms to safely
+finalize all open generators and close the event loop.
+
+``sys.set_asyncgen_hooks()`` is thread-specific, so several event
 loops running in parallel threads can use it safely.
 
+``sys.get_asyncgen_hooks()`` returns a namedtuple-like structure
+with ``firstiter`` and ``finalizer`` fields.
+
 
 Asynchronous Generator Object
 -----------------------------
@@ -399,8 +415,9 @@ New Standard Library Functions and Types
 1. ``types.AsyncGeneratorType`` -- type of asynchronous generator
    object.
 
-2. ``sys.set_asyncgen_finalizer()`` and ``sys.get_asyncgen_finalizer()``
-   methods to set up asynchronous generators finalizers in event loops.
+2. ``sys.set_asyncgen_hooks()`` and ``sys.get_asyncgen_hooks()``
+   methods to set up asynchronous generators finalizers and iteration
+   interceptors in event loops.
 
 3. ``inspect.isasyncgen()`` and ``inspect.isasyncgenfunction()``
    introspection functions.