gh-145342: asyncio: Add guest mode for running inside external event loops#145343
Open
congzhangzh wants to merge 2 commits intopython:mainfrom
Open
gh-145342: asyncio: Add guest mode for running inside external event loops#145343congzhangzh wants to merge 2 commits intopython:mainfrom
congzhangzh wants to merge 2 commits intopython:mainfrom
Conversation
…event loops Add asyncio.start_guest_run() which allows asyncio to run cooperatively inside a host event loop (e.g. Tkinter, Qt, GTK). The host loop stays in control of the main thread while asyncio I/O polling runs in a background daemon thread. Implementation: - Add three public methods to BaseEventLoop -- poll_events(), process_events(), and process_ready() -- that decompose _run_once() into independently callable steps. - Refactor _run_once() to delegate to these three methods (zero behaviour change for existing code). - Add Lib/asyncio/guest.py with start_guest_run(). - Add comprehensive tests using a mock host loop (no GUI dependency). - Add a Tkinter demo in Doc/includes/. Inspired by Trio start_guest_run() and the asyncio-guest project.
|
All commit authors signed the Contributor License Agreement. |
Author
|
@gvanrossum Hi Guido, I try to add guest mode to asyncio now, as I found that if I do not do it now, I will never have time to do it:) |
asvetlov
reviewed
Feb 28, 2026
Contributor
asvetlov
left a comment
There was a problem hiding this comment.
How does the proposed approach work with the Windows proactor event loop?
Does the thread boundary crossing function well with IOCP ports?
| _process_on_host([]) | ||
|
|
||
| threading.Thread( | ||
| target=_backend, daemon=True, name='asyncio-guest-io' |
Contributor
There was a problem hiding this comment.
A deamon thread smells like a red herring
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add
asyncio.start_guest_run()which allows asyncio to run cooperativelyinside a host event loop (e.g. Tkinter, Qt, GTK). The host loop stays in
control of the main thread while asyncio I/O polling runs in a background
daemon thread.
Motivation
GUI applications with a native main loop (Tkinter, Qt, GTK) cannot use
asyncio.run()without blocking or replacing the host loop. Guest modeenables incremental migration of GUI apps to async/await without replacing
the host event loop.
Implementation
Lib/asyncio/guest.pywithstart_guest_run().BaseEventLoop—poll_events(),process_events(), andprocess_ready()— that decompose_run_once()into independently callable steps (zero behavior change for existing code).
_run_once()to delegate to the three new methods.Lib/test/test_asyncio/test_guest.pyusing amock host loop (no GUI dependency, 12 test methods).
Doc/includes/asyncio_guest_tkinter.py.Doc/library/asyncio-guest.rst.Prior Art
Inspired by Trio's
start_guest_run()and the asyncio-guest proof-of-concept.
Testing
All 12 tests pass. The mock host loop tests cover: simple return, None return,
arguments, exceptions, cancellation from host,
asyncio.sleep(), task creation,asyncio.gather(),call_later, andcall_soon_threadsafe.📚 Documentation preview 📚: https://cpython-previews--145343.org.readthedocs.build/