gh-145342: Update asyncio guest mode docs and NEWS

Document the non-daemon I/O thread, lifecycle and cleanup semantics,
signal-handling delegation to the host, and the host requirements.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: congzhangzh

Doc/includes/asyncio_guest_tkinter.py

@@ -64,7 +64,7 @@ async def count(progress, root):
     progress.configure(maximum=MAX_COUNT)
 
     task = asyncio.current_task()
-    loop = asyncio.get_event_loop()
+    loop = asyncio.get_running_loop()
 
     # Wire the Cancel button and window close to task.cancel().
     # Use call_soon_threadsafe so the I/O thread's selector is woken.

Doc/library/asyncio-guest.rst

@@ -18,15 +18,16 @@ such as a GUI toolkit's main loop (Tkinter, Qt, GTK, etc.).  Instead of
 replacing the host loop, asyncio piggybacks on it:
 
 * The **host thread** keeps running its own main loop as usual.
-* A **background daemon thread** blocks on the selector (I/O polling).
+* A **background I/O thread** blocks on the selector (I/O polling).
   When I/O events arrive it hands them back to the host thread via a
-  thread-safe callback.
+  thread-safe callback.  The thread is not a daemon thread; it is joined
+  when the guest run finishes.
 * The host thread then runs :meth:`~asyncio.BaseEventLoop.process_events`
   and :meth:`~asyncio.BaseEventLoop.process_ready` to advance the asyncio
-  event loop by one step, then signals the background thread to poll again.
+  event loop by one step, then signals the I/O thread to poll again.
 
-This dual-thread architecture means neither the host loop nor the asyncio
-loop starves the other.
+Exactly one of the two threads touches the event loop at any moment, so
+neither the host loop nor the asyncio loop starves the other.
 
 Typical use cases:
 
@@ -47,23 +48,26 @@ example that embeds asyncio inside ``tkinter.mainloop()`` using
 
    Run *async_fn* as a guest inside another event loop.
 
-   The host event loop (e.g. ``tkinter.mainloop()``) remains in control of the
-   main thread.  asyncio I/O polling runs in a daemon background thread and
-   dispatches work back to the host thread via *run_sync_soon_threadsafe*.
+   Must be called from the host event loop's thread.  The host loop
+   (e.g. ``tkinter.mainloop()``) remains in control of that thread;
+   asyncio I/O polling runs in a background non-daemon thread that is
+   joined when the run finishes.
 
    :param async_fn: The async function to run as the top-level coroutine.
    :param args: Positional arguments forwarded to *async_fn*.
    :param run_sync_soon_threadsafe: A callable that schedules a zero-argument
-       callable on the host event loop's thread in a thread-safe manner.
-       For Tkinter use ``widget.after(0, fn)``; for Qt use a
-       ``QMetaObject.invokeMethod`` wrapper; etc.
-   :param done_callback: Called on the host thread when *async_fn* finishes.
-       Receives the completed :class:`Task` as its sole argument.  Inspect
-       the outcome with :meth:`Task.result`, :meth:`Task.exception`, or
+       callable on the host event loop's thread.  It must be thread-safe,
+       must not block, and must not raise; it need not preserve ordering.
+       For Tkinter use a ``root.call('after', 'idle', ...)`` wrapper; for
+       Qt use a ``QMetaObject.invokeMethod`` wrapper; etc.
+   :param done_callback: Called on the host thread after the run has fully
+       finished and the loop is closed (see :ref:`asyncio-guest-lifecycle`).
+       Receives the :class:`Task` as its sole argument.  Inspect the
+       outcome with :meth:`Task.result`, :meth:`Task.exception`, or
        :meth:`Task.cancelled`.
    :returns: The :class:`Task` wrapping *async_fn*.
 
-   To cancel the task from the host thread, use::
+   To cancel the task from the host, use::
 
        loop.call_soon_threadsafe(task.cancel)
 
@@ -72,6 +76,56 @@ example that embeds asyncio inside ``tkinter.mainloop()`` using
 
    .. versionadded:: 3.15
 
+.. _asyncio-guest-lifecycle:
+
+Lifecycle and Cleanup
+=====================
+
+For the whole guest run the guest loop is the host thread's running
+loop: :func:`get_running_loop` works inside guest tasks,
+:meth:`loop.is_running() <asyncio.loop.is_running>` returns ``True``, and
+starting another event loop on that thread — including a nested
+:func:`asyncio.run` or :meth:`loop.run_until_complete` — raises
+:exc:`RuntimeError`.  Consequently a thread that is already running an
+asyncio event loop cannot start a guest run.
+
+When the main task finishes, cleanup equivalent to :func:`asyncio.run`
+takes place on the host thread: remaining tasks are cancelled,
+asynchronous generators and the default executor are shut down, the I/O
+thread is joined, and the loop is closed.  Only then is *done_callback*
+invoked.
+
+If the interpreter exits while a guest run is unfinished, the run is
+abandoned: the I/O thread is woken and joined so that interpreter
+shutdown does not hang, pending tasks are not cancelled, and
+*done_callback* is not called.
+
+Signal Handling
+===============
+
+In guest mode the *host* owns signal handling:
+
+* The guest loop never touches :func:`signal.set_wakeup_fd`, neither to
+  install a file descriptor nor to reset it on close, so the host's
+  signal wake-up pipeline stays intact.
+* :meth:`loop.add_signal_handler` and :meth:`loop.remove_signal_handler`
+  raise :exc:`RuntimeError`.
+* To let asyncio code react to a signal, catch it in the host (with
+  :func:`signal.signal` or the host framework's facilities) and forward
+  it into the loop with :meth:`loop.call_soon_threadsafe`.
+
+Host Requirements
+=================
+
+* *run_sync_soon_threadsafe* must be thread-safe, non-blocking, and must
+  not raise.  It may run callbacks in any order.
+* Host code running *outside* guest callbacks (for example a GUI button
+  handler) must interact with the loop exclusively through
+  :meth:`loop.call_soon_threadsafe`, even though it runs on the loop's
+  own thread: the I/O thread may be inside the selector, and only
+  ``call_soon_threadsafe`` wakes it safely.
+* :meth:`loop.stop` is not supported in guest mode.
+
 .. rubric:: Low-level Event Loop Methods
 
 The following three methods on :class:`BaseEventLoop` are used internally by

Misc/NEWS.d/next/Library/2026-02-28-14-00-00.gh-issue-145342.GuestMode.rst

@@ -1,8 +1,12 @@
 Add :func:`asyncio.start_guest_run` to allow asyncio to run cooperatively
 inside a host event loop (e.g. Tkinter, Qt, GTK). The host loop retains
-control of the main thread while asyncio I/O polling runs in a background
-daemon thread. Also adds three low-level :class:`~asyncio.BaseEventLoop`
-methods -- :meth:`~asyncio.BaseEventLoop.poll_events`,
+control of its thread while asyncio I/O polling runs in a background
+non-daemon thread that is joined when the run finishes. In guest mode the
+host owns signal handling: the loop never touches
+:func:`signal.set_wakeup_fd` and :meth:`loop.add_signal_handler` raises
+:exc:`RuntimeError`. Also adds three low-level
+:class:`~asyncio.BaseEventLoop` methods --
+:meth:`~asyncio.BaseEventLoop.poll_events`,
 :meth:`~asyncio.BaseEventLoop.process_events`, and
 :meth:`~asyncio.BaseEventLoop.process_ready` -- that decompose
 :meth:`~asyncio.BaseEventLoop._run_once` into independently callable steps.