New submission from Marc Brünink:
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 220.127.116.11 and maybe also somewhere prominent in http://docs.python.org/dev/c-api/intro.html.
For section 18.104.22.168 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."
---------- assignee: docs@python components: Documentation messages: 189629 nosy: Marc.Brünink, docs@python priority: normal severity: normal status: open title: ctypes.PyDLL documentation versions: Python 3.5
eryksun added the comment:
22.214.171.124 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:
It wouldn't hurt to elaborate and box this warning.
Subsequently, PyDLL is documented to *not* release the GIL. Also, section 126.96.36.199 documents that CFUNCTYPE and WINFUNCTYPE functions release the GIL and PYFUNCTYPE functions will *not* release the GIL.
---------- nosy: +eryksun
marc added the comment:
I think the problem was a combination of two issues.
First, the warning in 188.8.131.52 is a bit hidden. Kind of squeezed in between CDLL, etc and PyDLL. In contrast, 184.108.40.206 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 220.127.116.11
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.
---------- nosy: +email@example.com
Eryk Sun firstname.lastname@example.org added the comment:
I think the documentation of ctypes.PyDLL and ctypes.pythonapi is good enough as is.
---------- resolution: -> rejected stage: -> resolved status: open -> closed