Oct 13, 2023 · Oct 12, 2023 · Oct 13, 2023 · Oct 13, 2023 · Oct 13, 2023 · Oct 13, 2023
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
   .. versionchanged:: 3.12
      Added the *timeout* parameter.

 .. method:: loop.run_forever_setup()

   Set up an event loop so that it is ready to start actively looping and
   processing events.

   .. note::

      End users should not use this method directly. This method is only needed
      if you are writing your own ``EventLoop`` subclass, with a customized
      event processing loop. For example, if you are integrating Python's
      asyncio event loop with a GUI library's event loop, you may need to write
      a customized :meth:`loop.run_forever` implementation that accommodates
      both CPython's event loop and the GUI library's event loop. You can use
      this method to ensure that Python's event loop is correctly configured and
      ready to start processing events.

      The specific details of a customized ``EventLoop`` subclass will depend
      on the GUI library you are integrating with. However, the broad structure
      of a custom ``EventLoop`` would look something like::

         class CustomGUIEventLoop(EventLoop):
            def run_forever(self):
               try:
                  self.run_forever_setup()
                  gui_library.setup()
                  while True:
                     self._run_once()
                     gui_library.process_events()
                     if self._stopping:
                        break
               finally:
                  self.run_forever_cleanup()
                  gui_library.cleanup()

   .. versionadded:: 3.13

 .. method:: loop.run_forever_cleanup()

   Perform any cleanup necessary at the conclusion of event processing to ensure
   that the event loop has been fully shut down.

   .. note::

      End users should not use this method directly. This method is only needed
      if you are writing your own ``EventLoop`` subclass, with a customized
      inner event processing loop. See :meth:`loop.run_forever_setup()` for
      details on why and how to use this method.

   .. versionadded:: 3.13

 Scheduling callbacks
 ^^^^^^^^^^^^^^^^^^^^

diff --git a/Lib/asyncio/base_events.py b/Lib/asyncio/base_events.py
        self._clock_resolution = time.get_clock_info('monotonic').resolution
        self._exception_handler = None
        self.set_debug(coroutines._is_debug_mode())
        # The preserved state of async generator hooks.
        self._old_agen_hooks = None
        # In debug mode, if the execution of a callback or a step of a task
        # exceed this duration in seconds, the slow callback/task is logged.
        self.slow_callback_duration = 0.1
            raise RuntimeError(
                'Cannot run the event loop while another loop is running')

    def run_forever(self):
        """Run until stop() is called."""
    def run_forever_setup(self):
        """Prepare the run loop to process events.

        This method should be used as part of the ``run_forever()``
        implementation in a custom event loop subclass (e.g., integrating a GUI
        event loop with Python's event loop).
        """
        self._check_closed()
        self._check_running()
        self._set_coroutine_origin_tracking(self._debug)

        old_agen_hooks = sys.get_asyncgen_hooks()
        try:
            self._thread_id = threading.get_ident()
            sys.set_asyncgen_hooks(firstiter=self._asyncgen_firstiter_hook,
                                   finalizer=self._asyncgen_finalizer_hook)
        self._old_agen_hooks = sys.get_asyncgen_hooks()
        self._thread_id = threading.get_ident()
        sys.set_asyncgen_hooks(
            firstiter=self._asyncgen_firstiter_hook,
            finalizer=self._asyncgen_finalizer_hook
        )

        events._set_running_loop(self)

    def run_forever_cleanup(self):
        """Clean up after an event loop finishes the looping over events.

            events._set_running_loop(self)
        This method should be used as part of the ``run_forever()``
        implementation in a custom event loop subclass (e.g., integrating a GUI
        event loop with Python's event loop).
        """
        self._stopping = False
        self._thread_id = None
        events._set_running_loop(None)
        self._set_coroutine_origin_tracking(False)
        # Restore any pre-existing async generator hooks.
        if self._old_agen_hooks is not None:
            sys.set_asyncgen_hooks(*self._old_agen_hooks)
            self._old_agen_hooks = None

    def run_forever(self):
        """Run until stop() is called."""
        try:
            self.run_forever_setup()
            while True:
                self._run_once()
                if self._stopping:
                    break
        finally:
            self._stopping = False
            self._thread_id = None
            events._set_running_loop(None)
            self._set_coroutine_origin_tracking(False)
            sys.set_asyncgen_hooks(*old_agen_hooks)
            self.run_forever_cleanup()

    def run_until_complete(self, future):
        """Run until the Future is done.
diff --git a/Lib/asyncio/windows_events.py b/Lib/asyncio/windows_events.py
            proactor = IocpProactor()
        super().__init__(proactor)

    def run_forever(self):
        try:
            assert self._self_reading_future is None
            self.call_soon(self._loop_self_reading)
            super().run_forever()
        finally:
            if self._self_reading_future is not None:
                ov = self._self_reading_future._ov
                self._self_reading_future.cancel()
                # self_reading_future was just cancelled so if it hasn't been
                # finished yet, it never will be (it's possible that it has
                # already finished and its callback is waiting in the queue,
                # where it could still happen if the event loop is restarted).
                # Unregister it otherwise IocpProactor.close will wait for it
                # forever
                if ov is not None:
                    self._proactor._unregister(ov)
                self._self_reading_future = None
    def run_forever_setup(self):
        assert self._self_reading_future is None
        self.call_soon(self._loop_self_reading)
        super().run_forever_setup()

    def run_forever_cleanup(self):
        super().run_forever_cleanup()
        if self._self_reading_future is not None:
            ov = self._self_reading_future._ov
            self._self_reading_future.cancel()
            # self_reading_future was just cancelled so if it hasn't been
            # finished yet, it never will be (it's possible that it has
            # already finished and its callback is waiting in the queue,
            # where it could still happen if the event loop is restarted).
            # Unregister it otherwise IocpProactor.close will wait for it
            # forever
            if ov is not None:
                self._proactor._unregister(ov)
            self._self_reading_future = None

    async def create_pipe_connection(self, protocol_factory, address):
        f = self._proactor.connect_pipe(address)
diff --git a/Lib/test/test_asyncio/test_base_events.py b/Lib/test/test_asyncio/test_base_events.py
        self.loop.run_forever()
        self.loop._selector.select.assert_called_once_with(0)

    def test_custom_run_forever_integration(self):
        # Test that the run_forever_setup() and run_forever_cleanup() primitives
        # can be used to implement a custom run_forever loop.
        self.loop._process_events = mock.Mock()

        count = 0

        def callback():
            nonlocal count
            count += 1

        self.loop.call_soon(callback)

        # Set up the custom event loop
        self.loop.run_forever_setup()

        # Confirm the loop has been started
        self.assertEqual(asyncio.get_running_loop(), self.loop)
        self.assertTrue(self.loop.is_running())

        # Our custom "event loop" just iterates 10 times before exiting.
        for i in range(10):
            self.loop._run_once()

        # Clean up the event loop
        self.loop.run_forever_cleanup()

        # Confirm the loop has been cleaned up
        with self.assertRaises(RuntimeError):
            asyncio.get_running_loop()
        self.assertFalse(self.loop.is_running())

        # Confirm the loop actually did run, processing events 10 times,
        # and invoking the callback once.
        self.assertEqual(self.loop._process_events.call_count, 10)
        self.assertEqual(count, 1)

    async def leave_unfinalized_asyncgen(self):
        # Create an async generator, iterate it partially, and leave it
        # to be garbage collected.
diff --git a/Misc/NEWS.d/next/Library/2023-10-13-06-47-20.gh-issue-110771.opwdlc.rst b/Misc/NEWS.d/next/Library/2023-10-13-06-47-20.gh-issue-110771.opwdlc.rst
 Expose the setup and cleanup portions of ``asyncio.run_forever()`` as the standalone methods ``asyncio.run_forever_setup()`` and ``asyncio.run_forever_cleanup()``. This allows for tighter integration with GUI event loops.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -210,6 +210,56 @@ Running and stopping the loop
		.. versionchanged:: 3.12
		Added the timeout parameter.

		.. method:: loop.run_forever_setup()

		Set up an event loop so that it is ready to start actively looping and
		processing events.

		.. note::

		End users should not use this method directly. This method is only needed
		if you are writing your own ``EventLoop`` subclass, with a customized
		event processing loop. For example, if you are integrating Python's
		asyncio event loop with a GUI library's event loop, you may need to write
		a customized :meth:`loop.run_forever` implementation that accommodates
		both CPython's event loop and the GUI library's event loop. You can use
		this method to ensure that Python's event loop is correctly configured and
		ready to start processing events.

		The specific details of a customized ``EventLoop`` subclass will depend
		on the GUI library you are integrating with. However, the broad structure
		of a custom ``EventLoop`` would look something like::

		class CustomGUIEventLoop(EventLoop):
		def run_forever(self):
		try:
		self.run_forever_setup()
		gui_library.setup()
		while True:
		self._run_once()
		gui_library.process_events()
		if self._stopping:
Copy link Member gvanrossumOct 13, 2023 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. It's unfortunate you need to use private (technically "protected") API and variable here. Then again, maybe "private" is the right term and we're okay with subclasses using those. It's also unfortunate that this documentation now constrains what we can do in`run_forever()`. It almost seems that we might as well document what`run_forever()` does and specify it as never doing anything else.
		break
		finally:
		self.run_forever_cleanup()
		gui_library.cleanup()
Copy link Member gvanrossumOct 13, 2023 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. I would imagine these two should happen in the reverse order? Cleanup in reverse order of setup. (Also, to be more robust, I'd use multiple nested`try/finally`s, but the example doesn't need that complexity. Copy link ContributorAuthor freakboy3742Oct 13, 2023 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. I'll reverse the order; agreed that another layer of try/finally is probably overkill for documenation purposes.

		.. versionadded:: 3.13

		.. method:: loop.run_forever_cleanup()

		Perform any cleanup necessary at the conclusion of event processing to ensure
		that the event loop has been fully shut down.
Copy link Member gvanrossumOct 13, 2023 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Maybe say something about whether this is re-entrant? Should I worry about not calling it twice?

		.. note::

		End users should not use this method directly. This method is only needed
		if you are writing your own ``EventLoop`` subclass, with a customized
		inner event processing loop. See :meth:`loop.run_forever_setup()` for
		details on why and how to use this method.

		.. versionadded:: 3.13

		Scheduling callbacks
		^^^^^^^^^^^^^^^^^^^^

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -400,6 +400,8 @@ def __init__(self):
		self._clock_resolution = time.get_clock_info('monotonic').resolution
		self._exception_handler = None
		self.set_debug(coroutines._is_debug_mode())
		# The preserved state of async generator hooks.
		self._old_agen_hooks = None
		# In debug mode, if the execution of a callback or a step of a task
		# exceed this duration in seconds, the slow callback/task is logged.
		self.slow_callback_duration = 0.1
Expand DownExpand Up		@@ -601,29 +603,52 @@ def _check_running(self):
		raise RuntimeError(
		'Cannot run the event loop while another loop is running')

		def run_forever(self):
		"""Run until stop() is called."""
		def run_forever_setup(self):
		"""Prepare the run loop to process events.

		This method should be used as part of the ``run_forever()``
		implementation in a custom event loop subclass (e.g., integrating a GUI
		event loop with Python's event loop).
		"""
		self._check_closed()
		self._check_running()
		self._set_coroutine_origin_tracking(self._debug)

		old_agen_hooks = sys.get_asyncgen_hooks()
		try:
		self._thread_id = threading.get_ident()
		sys.set_asyncgen_hooks(firstiter=self._asyncgen_firstiter_hook,
		finalizer=self._asyncgen_finalizer_hook)
		self._old_agen_hooks = sys.get_asyncgen_hooks()
		self._thread_id = threading.get_ident()
		sys.set_asyncgen_hooks(
		firstiter=self._asyncgen_firstiter_hook,
		finalizer=self._asyncgen_finalizer_hook
		)

		events._set_running_loop(self)

		def run_forever_cleanup(self):
		"""Clean up after an event loop finishes the looping over events.

		events._set_running_loop(self)
		This method should be used as part of the ``run_forever()``
		implementation in a custom event loop subclass (e.g., integrating a GUI
		event loop with Python's event loop).
		"""
		self._stopping = False
		self._thread_id = None
		events._set_running_loop(None)
		self._set_coroutine_origin_tracking(False)
		# Restore any pre-existing async generator hooks.
		if self._old_agen_hooks is not None:
		sys.set_asyncgen_hooks(*self._old_agen_hooks)
		self._old_agen_hooks = None

		def run_forever(self):
		"""Run until stop() is called."""
Copy link Member gvanrossumOct 13, 2023 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Maybe clarify in this docstring that this is what calls setup/cleanup?
		try:
		self.run_forever_setup()
		while True:
		self._run_once()
		if self._stopping:
		break
		finally:
		self._stopping = False
		self._thread_id = None
		events._set_running_loop(None)
		self._set_coroutine_origin_tracking(False)
		sys.set_asyncgen_hooks(*old_agen_hooks)
		self.run_forever_cleanup()

		def run_until_complete(self, future):
		"""Run until the Future is done.
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -314,24 +314,25 @@ def __init__(self, proactor=None):
		proactor = IocpProactor()
		super().__init__(proactor)

		def run_forever(self):
		try:
		assert self._self_reading_future is None
		self.call_soon(self._loop_self_reading)
		super().run_forever()
		finally:
		if self._self_reading_future is not None:
		ov = self._self_reading_future._ov
		self._self_reading_future.cancel()
		# self_reading_future was just cancelled so if it hasn't been
		# finished yet, it never will be (it's possible that it has
		# already finished and its callback is waiting in the queue,
		# where it could still happen if the event loop is restarted).
		# Unregister it otherwise IocpProactor.close will wait for it
		# forever
		if ov is not None:
		self._proactor._unregister(ov)
		self._self_reading_future = None
		def run_forever_setup(self):
		assert self._self_reading_future is None
		self.call_soon(self._loop_self_reading)
		super().run_forever_setup()

gvanrossum marked this conversation as resolved. Show resolvedHide resolved
		def run_forever_cleanup(self):
		super().run_forever_cleanup()
		if self._self_reading_future is not None:
		ov = self._self_reading_future._ov
		self._self_reading_future.cancel()
		# self_reading_future was just cancelled so if it hasn't been
		# finished yet, it never will be (it's possible that it has
		# already finished and its callback is waiting in the queue,
		# where it could still happen if the event loop is restarted).
		# Unregister it otherwise IocpProactor.close will wait for it
		# forever
		if ov is not None:
		self._proactor._unregister(ov)
		self._self_reading_future = None

		async def create_pipe_connection(self, protocol_factory, address):
		f = self._proactor.connect_pipe(address)
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -922,6 +922,43 @@ def test_run_forever_pre_stopped(self):
		self.loop.run_forever()
		self.loop._selector.select.assert_called_once_with(0)

		def test_custom_run_forever_integration(self):
		# Test that the run_forever_setup() and run_forever_cleanup() primitives
		# can be used to implement a custom run_forever loop.
		self.loop._process_events = mock.Mock()

		count = 0

		def callback():
		nonlocal count
		count += 1

		self.loop.call_soon(callback)

		# Set up the custom event loop
		self.loop.run_forever_setup()

		# Confirm the loop has been started
		self.assertEqual(asyncio.get_running_loop(), self.loop)
		self.assertTrue(self.loop.is_running())

		# Our custom "event loop" just iterates 10 times before exiting.
		for i in range(10):
		self.loop._run_once()

		# Clean up the event loop
		self.loop.run_forever_cleanup()

		# Confirm the loop has been cleaned up
		with self.assertRaises(RuntimeError):
		asyncio.get_running_loop()
		self.assertFalse(self.loop.is_running())

		# Confirm the loop actually did run, processing events 10 times,
		# and invoking the callback once.
		self.assertEqual(self.loop._process_events.call_count, 10)
		self.assertEqual(count, 1)

		async def leave_unfinalized_asyncgen(self):
		# Create an async generator, iterate it partially, and leave it
		# to be garbage collected.
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Expose the setup and cleanup portions of ``asyncio.run_forever()`` as the standalone methods ``asyncio.run_forever_setup()`` and ``asyncio.run_forever_cleanup()``. This allows for tighter integration with GUI event loops.