From 23852d0fcd3e1b1d24ecdc3132608238bbf198b2 Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee <russell@keith-magee.com>
Date: Fri, 13 Oct 2023 14:18:20 +0200
Subject: [PATCH] Improvements to docs, including a prototype custom event
 loop.

---
 Doc/library/asyncio-eventloop.rst | 50 +++++++++++++++++++------------
 1 file changed, 31 insertions(+), 19 deletions(-)

diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index 204cecfbc57996..2ba1fcb24f9cf8 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -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:
+                        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