From e8740568e8ba6475231e6fec28a1661391798692 Mon Sep 17 00:00:00 2001 From: Phil Ruffwind Date: Sat, 11 Jul 2026 16:56:07 -0700 Subject: [PATCH] Warn against constructing asyncio synchronization primitives outside loop This seems to be an easy-to-make rookie mistake for someone unfamiliar to asyncio. Surprised it's not already documented somewhere? --- Doc/library/asyncio-sync.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Doc/library/asyncio-sync.rst b/Doc/library/asyncio-sync.rst index f9e98e05cab7aca..8f9960d45836c3f 100644 --- a/Doc/library/asyncio-sync.rst +++ b/Doc/library/asyncio-sync.rst @@ -11,7 +11,7 @@ Synchronization Primitives ----------------------------------------------- asyncio synchronization primitives are designed to be similar to -those of the :mod:`threading` module with two important caveats: +those of the :mod:`threading` module with several important caveats: * asyncio primitives are not thread-safe, therefore they should not be used for OS thread synchronization (use :mod:`threading` for @@ -21,6 +21,10 @@ those of the :mod:`threading` module with two important caveats: argument; use the :func:`asyncio.wait_for` function to perform operations with timeouts. +* asyncio primitives are bound to a specific event loop and must be + constructed inside the loop to function correctly. A common mistake is + constructing them before the loop starts, such as with global variables. + asyncio has the following basic synchronization primitives: * :class:`Lock`