gh-158287: Fix blocked asyncio event loop on macOS when child process is stopped

On macOS, waitid(os.P_PID, pid, os.WEXITED | os.WNOWAIT) returns on SIGSTOP
with si_code == CLD_STOPPED even though WSTOPPED was not requested.
In _ThreadedChildWatcher, consume the stop notification and continue waiting
for actual process termination rather than calling _reap_and_notify with
os.waitpid(pid, 0) which blocks the event loop thread.

Author: JohnnyWilson16

Lib/asyncio/unix_events.py

@@ -968,7 +968,28 @@ def _do_waitpid(self, loop, expected_pid, callback, args):
             # This makes the reaping of the child and notification of the return code
             # atomic with respect to the event loop thread.
             try:
-                os.waitid(os.P_PID, expected_pid, os.WEXITED | os.WNOWAIT)
+                while True:
+                    res = os.waitid(os.P_PID, expected_pid, os.WEXITED | os.WNOWAIT)
+                    # On macOS, waitid() with WEXITED incorrectly returns stopped
+                    # child processes (si_code == CLD_STOPPED). Consume the stop
+                    # notification so we wait for actual process termination.
+                    if (
+                        res is not None
+                        and hasattr(os, 'CLD_STOPPED')
+                        and res.si_code in (os.CLD_STOPPED, getattr(os, 'CLD_TRAPPED', None))
+                    ):
+                        consume_flags = getattr(os, 'WSTOPPED', 0)
+                        if hasattr(os, 'WCONTINUED'):
+                            consume_flags |= os.WCONTINUED
+                        if hasattr(os, 'WNOHANG'):
+                            consume_flags |= os.WNOHANG
+                        if consume_flags:
+                            try:
+                                os.waitid(os.P_PID, expected_pid, consume_flags)
+                            except ChildProcessError:
+                                pass
+                            continue
+                    break
             except ChildProcessError:
                 # The child process is already reaped
                 pass

Lib/test/test_asyncio/test_subprocess.py

@@ -1162,6 +1162,32 @@ async def run():
 
             self.loop.run_until_complete(run())
 
+        @unittest.skipUnless(hasattr(os, 'waitid'), 'needs os.waitid()')
+        @unittest.skipUnless(hasattr(signal, 'SIGSTOP'), 'needs SIGSTOP')
+        def test_stopped_child_does_not_block_event_loop(self):
+            # gh-158287: on macOS, waitid() with WEXITED incorrectly reports
+            # stopped children (si_code == CLD_STOPPED). The child watcher
+            # must not mistake this for process termination and attempt to reap
+            # the child with waitpid(), which blocks the event loop thread.
+            async def run():
+                proc = await asyncio.create_subprocess_exec(*PROGRAM_BLOCKED)
+                try:
+                    proc.send_signal(signal.SIGSTOP)
+                    # Verify event loop remains responsive while child is stopped
+                    for _ in range(3):
+                        await asyncio.sleep(0.05)
+                    self.assertIsNone(proc.returncode)
+                finally:
+                    if hasattr(signal, 'SIGCONT'):
+                        try:
+                            proc.send_signal(signal.SIGCONT)
+                        except ProcessLookupError:
+                            pass
+                    proc.kill()
+                    await proc.wait()
+
+            self.loop.run_until_complete(run())
+
     @unittest.skipUnless(
         unix_events.can_use_pidfd(),
         "operating system does not support pidfds",

Misc/NEWS.d/next/Library/2026-10-07-17-30-00.gh-issue-158287.xY9zQp.rst

@@ -0,0 +1 @@
+Fix a bug in :mod:`asyncio` where stopping a child process with ``SIGSTOP`` on macOS caused the event loop to block indefinitely in ``_ThreadedChildWatcher``.