Add a new internal thread safe handle for asyncio

[kumaraditya303]

loop.call_soon_threadsafe ¹ is a thread safe API to schedule callbacks from other threads however the handle returned by it i.e. asyncio.Handle ² isn't thread safe like its cancel ³ method. This is an issue even with the GIL because thread switching is preemptive and is a bigger issue for free-threading builds.

Proposal

Add a new _ThreadSafeHandle which inherits from asyncio.Handle but internally uses a mutex to avoid multiple threads cancelling and running the callback at the same time for callbacks scheduled by loop.call_soon_threadsafe API, other APIs such as loop.call_soon will continue to use the old asyncio.Handle.

Linked PRs

• gh-128340: make asyncio.events.Handle.cancel() atomic #128347
• gh-128340: thread safe handle for loop.call_soon_threadsafe #128369

Footnotes

1. https://docs.python.org/3.13/library/asyncio-eventloop.html#asyncio.loop.call_soon_threadsafe ↩

2. https://docs.python.org/3.13/library/asyncio-eventloop.html#asyncio.Handle ↩

3. https://docs.python.org/3.13/library/asyncio-eventloop.html#asyncio.Handle.cancel ↩

[graingert]

do you have a use-case for cancelling a call_soon_threadsafe from another thread?

[graingert]

It also looks like you don't need a mutex, you could just combine the "self._cancelled" and "self._callback" attributes into one attribute where a None callback causes the handle to be considered cancelled.

[kumaraditya303]

do you have a use-case for cancelling a call_soon_threadsafe from another thread?

It's not about use case, this API has been published and this should work in both free-threading and normal builds.

[graingert]

Ah I see, I'll make a PR that makes this threadsafe without a mutex

[kumaraditya303]

It also looks like you don't need a mutex, you could just combine the "self._cancelled" and "self._callback" attributes into one attribute where a None callback causes the handle to be considered cancelled.

If you combine the two, won't there be race when event loop would check if callback is None and another thread setting it to None?

What about the following sequence without mutex:

• Event loop checks the handle if cancelled handle._callback == None is False
• The thread calling loop.call_soon_threadsafe cancels it handle._callback == None is True
• Event loop tries to run the callback but is None and thus crashes

[graingert]

• Event loop checks the handle if cancelled handle._callback == None is False

  • The thread calling loop.call_soon_threadsafe cancels it handle._callback == None is True

  • Event loop tries to run the callback but is None and thus crashes

this won't happen because the eventloop calls handle.run() so we can check cancellation here.
If there's a race condition some extra debug code (the 100ms debug callback timer) but won't crash

[kumaraditya303]

I saw your PR, it adds quite a lot of code for the common case when thread safety is not required, specifically you are adding unnecessary comparison and tuple packing/unpacking to the hot path of handle._run.

FWIW the handle API is very performance sensitive as all the callbacks are called thorough it, I worry this could cause a significant performance loss for no real benefit.

[graingert]

You'll need the mutex in the hot path anyway, although only for call_soon_threadsafe it will change the code quite drastically anyway. Probably it's worth benchmarking the approaches

I can replace the tuple unpacking for index lookups instead, and see if that's faster