@@ -173,24 +173,22 @@ the existing crashes caused by :c:func:`PyGILState_Ensure`.
173173The term "GIL" is tricky for free-threading
174174*******************************************
175175
176- A large issue with the term "GIL" in the C API is that it's semantically
177- misleading, as noted in `python/cpython#127989
176+ A large issue with the term "GIL" in the C API is that it is semantically
177+ misleading. This was noted in `python/cpython#127989
178178<https://github.com/python/cpython/issues/127989> `_,
179179created by the authors of this PEP:
180180
181181 The biggest issue is that for free-threading, there is no GIL, so users
182182 erroneously call the C API inside ``Py_BEGIN_ALLOW_THREADS `` blocks or
183183 omit ``PyGILState_Ensure `` in fresh threads.
184184
185- In reality, :c:func: `PyGILState_Ensure ` doesn't just "acquire the GIL" in
186- modern versions (that being since 3.12). It attaches a :term: `thread state `
187- for the current thread--*that's * what lets a thread invoke the C API. On
188- with-GIL builds, holding an :term: `attached thread state ` implies holding the
189- GIL, so only one thread can have one at a time. Free-threaded builds achieve
190- the effect of multi-core parallism while remaining backwards-compatible by
191- simply removing that limitation: threads still need a thread state (and thus
192- need to call :c:func: `PyGILState_Ensure `), but they don't need to wait on one
193- another to do so.
185+ Since Python 3.12, it is an :term: `attached thread state ` that lets a thread
186+ invoke the C API. On with-GIL builds, holding an :term: `attached thread state `
187+ implies holding the GIL, so only one thread can have one at a time. Free-threaded
188+ builds achieve the effect of multi-core parallism while remaining
189+ ackwards-compatible by simply removing that limitation: threads still need a
190+ thread state (and thus need to call :c:func: `PyGILState_Ensure `), but they
191+ don't need to wait on one another to do so.
194192
195193Subinterpreters don't work with :c:func: `PyGILState_Ensure `
196194-----------------------------------------------------------
0 commit comments