document that a new Python thread context is created in ctypes callbacks (closes...

Patch by Nikolaus Rath.

diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index ae10b71d4a0a9cc45403a70013f996243843db0d..f001165320ee1b6428922faa2fb39b47a26d945f 100644 (file)
--- 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: