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
   Set up an event loop so that it is ready to start actively looping and
   processing events.

   Returns the state that must be restored when the loop concludes. This state
   should be passed in as arguments to :meth:`loop.run_forever_cleanup()`.

   .. note::

      This method is only needed if you are writing your own ``EventLoop``
      subclass, with a customized inner event processing loop. For example, if
      you are integrating Python's asyncio event loop with a 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 individual events. Most
      end users will not need to use this method directly.
      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(original_state)
 .. 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.

   The *original_state* argument is the return value provided by the call to
   :meth:`loop.run_forever_setup()` that was used to set up the event loop.

   .. note::

      This method is only needed if you are writing your own ``EventLoop``
      subclass, with a customized inner event processing loop. For example, if
      you are integrating Python's asyncio event loop with a GUI library's event
      loop, you can use this method to ensure that Python's event loop has been
      fully shut down at the conclusion of processing events. Most end users
      will not need to use this method directly.
      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
Original file line number	Diff line number	Diff line change
Expand Up		@@ -215,36 +215,48 @@ Running and stopping the loop
		Set up an event loop so that it is ready to start actively looping and
		processing events.

		Returns the state that must be restored when the loop concludes. This state
		should be passed in as arguments to :meth:`loop.run_forever_cleanup()`.

		.. note::

		This method is only needed if you are writing your own ``EventLoop``
		subclass, with a customized inner event processing loop. For example, if
		you are integrating Python's asyncio event loop with a 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 individual events. Most
		end users will not need to use this method directly.
		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(original_state)
		.. 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?

		The original_state argument is the return value provided by the call to
		:meth:`loop.run_forever_setup()` that was used to set up the event loop.

		.. note::

		This method is only needed if you are writing your own ``EventLoop``
		subclass, with a customized inner event processing loop. For example, if
		you are integrating Python's asyncio event loop with a GUI library's event
		loop, you can use this method to ensure that Python's event loop has been
		fully shut down at the conclusion of processing events. Most end users
		will not need to use this method directly.
		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

Expand Down