classification
Title: ctypes.PyDLL documentation
Type: Stage: resolved
Components: Documentation Versions: Python 3.5
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Marc.Brünink, docs@python, eryksun, marc@bruenink.de
Priority: normal Keywords:

Created on 2013-05-20 00:38 by Marc.Brünink, last changed 2021-03-13 03:48 by eryksun. This issue is now closed.

Messages (5)
msg189629 - (view) Author: Marc Brünink (Marc.Brünink) Date: 2013-05-20 00:38
The documentation for is not very clear regarding the usage of CDLL and PyDLL. Especially it is not obvious that you should use PyDLL whenever you call any function of the Python/C API. Since calling a Python/C API function without owning the GIL will most likely cause latent segfaults, I think it warrants a warning box in section 16.17.2.2 and maybe also somewhere prominent in http://docs.python.org/dev/c-api/intro.html.

For section 16.17.2.2 I would put a box next the decription of CDLL saying something like: "The Python GIL is released before a function call. It is not safe to call any Pyhon/C API function within the loaded library without acquiring the GIL first. Thus, if the loaded library calls functions of the Python/C API, for example in case it creates and returns a new Python object, and does not manually acquire and release the GIL, use PyDLL instead."
msg220994 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2014-06-19 15:44
@Marc can you prepare a patch for this issue?
msg221024 - (view) Author: Eryk Sun (eryksun) * (Python triager) Date: 2014-06-19 21:31
16.17.2.2 already has a warning after it introduces CDLL, OleDLL, and WinDLL:

    The Python global interpreter lock is released before 
    calling any function exported by these libraries, and 
    reacquired afterwards.

It links to the glossary entry:

    https://docs.python.org/3/glossary.html#term-global-interpreter-lock

It wouldn't hurt to elaborate and box this warning.

Subsequently, PyDLL is documented to *not* release the GIL. Also,  section 16.17.2.4 documents that CFUNCTYPE and WINFUNCTYPE functions release the GIL and PYFUNCTYPE functions will *not* release the GIL.
msg221069 - (view) Author: marc (marc@bruenink.de) Date: 2014-06-20 06:47
I think the problem was a combination of two issues.

First, the warning in 16.17.2.2 is a bit hidden. Kind of squeezed in 
between CDLL, etc and PyDLL. In contrast, 16.17.2.4 does a much better 
job, because it restates the fact that the GIL is released at each and 
every item. I think this is much better, because chances are high that 
you actually read the entry completely. In contrast, in case you 
are in a hurry you might miss the warning in 16.17.2.2

I think the second problem was that back then I was not aware of the 
fact that you need the GIL to call the Python/C API. That was a bit 
stupid indeed. But as a Python beginner it was just not obvious. Maybe 
the Introduction of the Python/C API needs some work, too. No GIL 
mentioned at https://docs.python.org/3/c-api/intro.html.
Furthermore, the examples at 
https://docs.python.org/3/extending/extending.html also do not talk 
about the GIL.
msg388587 - (view) Author: Eryk Sun (eryksun) * (Python triager) Date: 2021-03-13 03:48
I think the documentation of ctypes.PyDLL and ctypes.pythonapi is good enough as is.
History
Date User Action Args
2021-03-13 03:48:45eryksunsetstatus: open -> closed
resolution: rejected
messages: + msg388587

stage: resolved
2019-03-15 23:36:08BreamoreBoysetnosy: - BreamoreBoy
2014-06-20 06:47:22marc@bruenink.desetnosy: + marc@bruenink.de
messages: + msg221069
2014-06-19 21:31:12eryksunsetnosy: + eryksun
messages: + msg221024
2014-06-19 15:44:27BreamoreBoysetnosy: + BreamoreBoy
messages: + msg220994
2013-05-20 00:38:39Marc.Brüninkcreate