From f6ffb4b264ae2ac3e9086abb8c825b195b207bff Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Mon, 20 Jan 2014 00:09:53 -0500 Subject: document that a new Python thread context is created in ctypes callbacks (closes #6627) Patch by Nikolaus Rath. --- Doc/library/ctypes.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index ae10b71..f001165 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1022,12 +1022,18 @@ As we can easily check, our array is sorted now:: 1 5 7 33 99 >>> -**Important note for callback functions:** +**Important notes for callback functions:** Make sure you keep references to :func:`CFUNCTYPE` objects as long as they are used from C code. :mod:`ctypes` doesn't, and if you don't, they may be garbage collected, crashing your program when a callback is made. +Also, note that if the callback function is called in a thread created outside +of Python's control (e.g. by the foreign code that calls the callback), ctypes +creates a new dummy Python thread on every invocation. This behavior is correct +for most purposes, but it means that values stored with `threading.local` will +*not* survive across different callbacks, even when those calls are made from +the same C thread. .. _ctypes-accessing-values-exported-from-dlls: -- cgit v0.12 From 1cfe009b96e500034faf923fff8bbf87a4c7e182 Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Mon, 20 Jan 2014 00:10:23 -0500 Subject: put notes in a ..note section --- Doc/library/ctypes.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index f001165..f46da85 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1022,18 +1022,18 @@ As we can easily check, our array is sorted now:: 1 5 7 33 99 >>> -**Important notes for callback functions:** - -Make sure you keep references to :func:`CFUNCTYPE` objects as long as they are -used from C code. :mod:`ctypes` doesn't, and if you don't, they may be garbage -collected, crashing your program when a callback is made. - -Also, note that if the callback function is called in a thread created outside -of Python's control (e.g. by the foreign code that calls the callback), ctypes -creates a new dummy Python thread on every invocation. This behavior is correct -for most purposes, but it means that values stored with `threading.local` will -*not* survive across different callbacks, even when those calls are made from -the same C thread. +.. note:: + + Make sure you keep references to :func:`CFUNCTYPE` objects as long as they + are used from C code. :mod:`ctypes` doesn't, and if you don't, they may be + garbage collected, crashing your program when a callback is made. + + Also, note that if the callback function is called in a thread created + outside of Python's control (e.g. by the foreign code that calls the + callback), ctypes creates a new dummy Python thread on every invocation. This + behavior is correct for most purposes, but it means that values stored with + `threading.local` will *not* survive across different callbacks, even when + those calls are made from the same C thread. .. _ctypes-accessing-values-exported-from-dlls: -- cgit v0.12