Threading brings no performance improvement + no cp314t wheel support

[yannsadowski]

Environment of launching

• pymunk version: v7.2.0
• Python version: 3.14t
• OS: Ubuntu 24 (WSL2)
• CPU: Intel(R) Core(TM) Ultra 7 255U

Issue 1 — Threading shows no improvement (or regression)

Running the official threaded_space.py example with varying thread counts and higher pyramide yields no speedup:

Threads 0, time 7.10s
Threads 1, time 7.26s
Threads 2, time 7.11s
Threads 4, time 7.26s
Threads 8, time 7.58s

With 8 threads, performance is actually worse than single-threaded. This appears to be due to synchronization overhead exceeding the parallelism gain at this simulation scale (1275 bodies, pyramid of 50 rows).

Is there a recommended minimum simulation size where threading becomes beneficial? Should the example be updated with a note about this?

Issue 2 — No wheel available for Python 3.14 free-threaded (cp314t)

Attempting to install pymunk on a Python 3.14 free-threaded build (cp314t) fails — no compatible wheel is available on PyPI, and building from source raises the following error:

RuntimeError: Unable to run "sdl-config". Please make sure a development version of SDL is installed.

Is there a plan to support the free-threaded Python 3.14 build (cp314t)? This would be particularly relevant given that free-threaded Python removes the GIL, which could make pymunk's threaded mode actually beneficial.

Question

Would free-threaded Python (cp314t) allow Chipmunk's threaded solver to run without GIL contention, and would that finally yield real multi-core speedups for the physics simulation?

Thanks for the great library!

[viblo]

Unfortunately threading support in Pymunk is quite limited for threads: Its capped at max 2 threads, since more wont help anyway. If you see a difference for a thread number above that its just benchmark noise(!)

I guess the docs could be clearer on the limited benefits from using two threads instead of just one, but the limit of 2 threads is already mentioned on the threads property on the Space. On the other hand, maybe it would be good with an assert, to not give false hope and prevent wasting time on testing.

Free threading support in Pymunk would not help performance inside Pymunk itself (it would probably be a bit worse since it now have to have more locking everywhere). All the heavy calculations are done in Munk2D, a C library. The multithread logic is also completely contained inside this library, meaning Pymunk does not use any threads on the Python side. There can only be overhead. On the other hand, for most of the time the overhead should be fairly limited, most of the time the bottleneck is in the simulation itself, not in the overhead calling the C code from Python. And for the most critical path, reading and setting properties, there's always the batch module (The main exception is collision callbacks, there the overhead is more obvious).

However, what free threading could help with is mainly two things:

1. Easier to run multiple simulations in a single python process. E.g. you have two spaces you want to simulate at the same time, with free threading it would be easier since it could be done without sub processes.
2. Easier to do other tasks while Pymunk does its simulation, e.g. lets say your rendering logic could run in a separate thread while the Space.step method runs (given the rendering library also support free threading).

I do think these are interesting to look into now that free threading is a bit more stable in 3.14.

I will keep this issue open while I investigate a bit what it would take to support free threading in Pymunk.