classification
Title: PyGILState_Ensure()/PyGILState_Release() documentation incomplete?
Type: Stage:
Components: Documentation Versions: Python 3.0, Python 2.4, Python 3.1, Python 2.7, Python 2.6, Python 2.5
process
Status: closed Resolution: works for me
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: georg.brandl, osvenskan
Priority: normal Keywords:

Created on 2009-02-17 20:43 by osvenskan, last changed 2009-04-05 17:19 by georg.brandl. This issue is now closed.

Messages (2)
msg82366 - (view) Author: Philip Semanchuk (osvenskan) * Date: 2009-02-17 20:43
The threading API documentation might omit out some important
information about the GIL. 

The GIL can be acquired by explicitly calling PyEval_AcquireLock(). One
can also acquire the GIL by calling PyGILState_Ensure(). The latter
differs from the former in that calling PyGILState_Ensure() when one
already has the GIL will not create deadlock. This is implied; it would
be helpful if this was explicitly stated. 

Likewise, I assume that the Nth call to PyGILState_Release() releases
the GIL, where N = the number of calls made previously to
PyGILState_Ensure(). But I don't know this and the documentation doesn't
make it clear. 

As a first-time user of the API, it makes me nervous to call
PyGILState_Ensure() which acquires the GIL without knowing for sure that
PyGILState_Release() releases it. I can't evaluate my code for logical
correctness, and when dealing with threads and the GIL, neither can I be
sure that timing-dependent bugs will show up in testing. As a result, my
code feels fragile.

I don't understand how the code works well enough to suggest better
documentation. If nothing else, it would be useful to see something that
promises that as long as each call to PyGILState_Ensure() is matched
with a call to PyGILState_Release(), the GIL will take care of itself.
msg85529 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2009-04-05 17:19
I think the paragraph

   Every call to :cfunc:`PyGILState_Ensure` must be matched by a call to
   :cfunc:`PyGILState_Release` on the same thread.

says exactly what you want to know.
History
Date User Action Args
2009-04-05 17:19:22georg.brandlsetstatus: open -> closed
resolution: works for me
messages: + msg85529
2009-02-17 20:43:24osvenskancreate