ProcessPoolExecutor deadlocks against the import lock when the submitted callable is defined in the module being imported

[shuanat]

Bug report

Bug description

ProcessPoolExecutor deadlocks silently — no output, no traceback, no exit — when all three of the following hold:

1. work is submitted from a module body, i.e. while that module is being imported;
2. the submitted callable is defined in that same module;
3. the module body blocks on the outcome, either on Future.result() or simply by leaving the with block, which calls shutdown(wait=True).

A timeout on Future.result() does not rescue it: when the timeout expires, __exit__ calls shutdown(wait=True), which joins the very thread that is stuck.

Minimal reproducer, mod_a.py:

from concurrent.futures import ProcessPoolExecutor


def square(x):
    return x * x


with ProcessPoolExecutor(max_workers=1) as ex:
    print(ex.submit(square, 3).result(timeout=30))

$ python -c "import mod_a"
   (hangs forever)

Control — byte-for-byte the same, except that the callable lives in another module.

worker.py:

def square(x):
    return x * x

mod_b.py:

from concurrent.futures import ProcessPoolExecutor

from worker import square

with ProcessPoolExecutor(max_workers=1) as ex:
    print(ex.submit(square, 3).result(timeout=30))

$ python -c "import mod_b"
9

The third ingredient is equally necessary: if the module body submits without waiting and the result is collected after the import has finished, there is no deadlock either.

Analysis

faulthandler.dump_traceback_later() on the hung process shows the cycle directly:

Thread 0x0001344c (most recent call first):
  File "<frozen importlib._bootstrap>", line 365 in acquire
  File "<frozen importlib._bootstrap>", line 471 in _lock_unlock_module
  File ".../Lib/multiprocessing/reduction.py", line 51 in dumps
  File ".../Lib/multiprocessing/queues.py", line 262 in _feed
  File ".../Lib/threading.py", line 995 in run
  File ".../Lib/threading.py", line 1044 in _bootstrap_inner
  File ".../Lib/threading.py", line 1015 in _bootstrap

Thread 0x00011d44 (most recent call first):
  File ".../Lib/threading.py", line 1095 in join
  File ".../Lib/concurrent/futures/process.py", line 851 in shutdown
  File ".../Lib/concurrent/futures/_base.py", line 647 in __exit__
  File ".../mod_a.py", line 9 in <module>
  File "<frozen importlib._bootstrap>", line 488 in _call_with_frames_removed
  File "<frozen importlib._bootstrap_external>", line 1023 in exec_module
  File "<frozen importlib._bootstrap>", line 935 in _load_unlocked
  File "<frozen importlib._bootstrap>", line 1331 in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 1360 in _find_and_load
  File "<string>", line 1 in <module>

• the main thread holds mod_a's per-module import lock for as long as the module body runs, and blocks inside that body waiting for the pool;
• the work item is pickled on the queue feeder thread (multiprocessing.queues.Queue._feed → multiprocessing.reduction.dumps);
• pickling square by reference calls __import__("mod_a"), which waits on that module's lock in importlib._bootstrap._lock_unlock_module.

Neither thread can move. Note that the cycle passes through a non-import resource — the queue and the future — so no amount of import-lock refinement can detect or break it.

What stands out is that the work item is serialized on the feeder thread rather than on the thread that called submit(). Had it been pickled in submit() — on the thread that already holds the module lock — this particular cycle could not form. There is precedent for moving work out of that thread for robustness reasons: bpo-31699 dealt with pickling errors in the same queue silently deadlocking the executor.

Prior art

• multiprocess.Queue operations during import can lead to deadlocks #51956 (bpo-7707), "multiprocess.Queue operations during import can lead to deadlocks", filed 2010, closed 2012 as fixed by a documentation note. I cannot find that note in the documentation today: Doc/library/multiprocessing.rst, Doc/library/threading.rst and Doc/library/concurrent.futures.rst on main say nothing about the import lock. It may well have been dropped when per-module import locks arrived in 3.3 (bpo-9260), which fixed most of this family — but not this case.
• multiprocessing with maxtasksperchild can hang if unpickling causes import #93580 is the mirror image, an import triggered while unpickling a result. It was closed as not planned, on the grounds that fork is unsafe in the presence of threads. That reasoning does not carry over here: this reproduces under spawn, and the whole deadlock lives inside the parent process.

Whatever the appetite for a code change, the silent hang seems worth at least a documented warning. Nothing surfaces — not a traceback, not a TimeoutError, not a broken-pool error — and the natural defensive measure, a timeout on result(), moves the hang from result() to shutdown() rather than avoiding it.

CPython versions tested on

3.13

Operating systems tested on

Windows

Nothing in the mechanism appears platform-specific — the feeder thread pickles under every start method — but I have only run it on Windows.

[picnixz]

Isn't it because you are not having it in a __main__ block?

[shuanat]

No - the guard is orthogonal.

mod_a is imported, so __name__ == "mod_a": a guard around its body would just make the body dead code. And a correct guard on the entry point does not help — main_guarded.py:

from multiprocessing import freeze_support

if __name__ == "__main__":
    freeze_support()
    import mod_a

$ python main_guarded.py
   (hangs forever)

Same two-thread cycle in the traceback (3.13.13, Windows, spawn).

What decides it is not the guard but whether the module is executed as __main__ (no import lock held — python mod_a.py with the body guarded prints 9) or imported (per-module lock held for the whole body — hangs). That is the _lock_unlock_module edge in the traceback.

The guard's own failure mode is loud, not silent, and lives elsewhere: running the unguarded module as a script raises RuntimeError: An attempt has been made to start a new process before the current process has finished its bootstrapping phase plus BrokenProcessPool, exit 1, with a pointer to the docs. It happens in the child re-importing __main__; the deadlock here is entirely in the parent - both threads in the traceback are parent threads, and nothing reaches a child because the pickling never completes.

[picnixz]

What decides it is not the guard but whether the module is executed as main

Yes, that's what I meant. By putting if __name__ == '__main__': ... around the process pool. However, this also changes the semantics now so this may still be a problem for modules that want to do real multiprocessing work on import.

---

I acknowledge this is an issue then.

cc @gpshead