https://bernat.tech/tags/concurrency/Engineering notes from Bernát Gábor — PyPA maintainer of tox, virtualenv, pipx, filelock, and platformdirs. Python packaging, type hints, and supply chain security.Hugo 0.163.3en-USThu, 28 May 2026 17:57:48 +0000https://bernat.tech/posts/blanket-deterministic-threading/Thu, 28 May 2026 17:57:48 +0000Bernát Gáborhttps://bernat.tech/posts/blanket-deterministic-threading/<div class="alert alert-info"> <p class="alert-title"><i class="fa-solid fa-circle-info" aria-hidden="true"></i> TLDR:</p> <ul> <li><a href="#why-multithreaded-python-tests-are-flaky"><strong>The problem</strong></a> : testing multithreaded code is hard because the OS scheduler decides which thread runs when, making race conditions all but impossible to reproduce in a test suite.</li> <li><a href="#enter-blanket-deterministic-threading-control"><strong>The solution</strong></a> : <a href="https://pypi.org/project/blanket/" target="_blank" rel="noopener noreferrer">blanket</a> wraps real <code>threading</code> primitives (Lock, Condition, Event, Barrier, Semaphore) and lets your test act as the scheduler, controlling which thread proceeds at each step.</li> <li><a href="#why-now"><strong>Why now</strong></a> : free-threaded Python (no <a href="https://docs.python.org/3/glossary.html#term-GIL" target="_blank" rel="noopener noreferrer">GIL</a> ) shipped as an experimental build in 3.13, is <a href="https://docs.python.org/3.14/whatsnew/3.14.html" target="_blank" rel="noopener noreferrer">officially supported in 3.14</a> , and keeps maturing in <a href="https://docs.python.org/3.15/whatsnew/3.15.html" target="_blank" rel="noopener noreferrer">3.15</a> . The GIL was hiding thread-safety bugs you did not know you had; without it, they surface.</li> <li><a href="#how-it-works-under-the-hood"><strong>How it works</strong></a> : every method call on a blanket primitive becomes a <em>transaction</em> that parks at a <em>scheduler block</em>. Your test unblocks transactions in whatever order you want, making execution 100% deterministic.</li> <li><a href="#concurrency-testing-tools-compared"><strong>What makes it different</strong></a> : unlike stateless model checkers (<a href="https://github.com/tokio-rs/loom" target="_blank" rel="noopener noreferrer">Loom</a> , <a href="https://github.com/awslabs/shuttle" target="_blank" rel="noopener noreferrer">Shuttle</a> , <a href="https://www.microsoft.com/en-us/research/project/chess-find-and-reproduce-heisenbugs-in-concurrent-programs/" target="_blank" rel="noopener noreferrer">CHESS</a> ) that <em>discover</em> bugs by exploring interleavings, blanket lets you <em>declare</em> specific scenarios by hand, useful for regression tests of known bugs and for full coverage of rare code paths.</li> </ul> </div><p>Most multithreaded Python codebases keep at least one test marked <code>@pytest.mark.flaky(reruns=5)</code>: the one that fails once in a thousand because of a race condition you cannot reproduce on demand. The bug is a specific sequence of thread interactions. You do not get to pick the sequence; the OS scheduler does. You ship the retry and hope.</p>pythontestingconcurrencythreadingfree-threadingblanketpyconrace-conditiongil