@@ -100,11 +100,35 @@ For example, a module called ``spam`` would be defined like this::
100100The export hook is typically the only non-\ ``static ``
101101item defined in the module's C source.
102102
103- The hook should be kept short -- ideally, one line as above.
104- If you do need to use Python C API in this function, it is recommended to call
105- ``PyABIInfo_Check(&abi_info, "modulename") `` first to raise an exception,
106- rather than crash, in common cases of ABI mismatch.
103+ .. _pymodexport-api-caveats :
107104
105+ The hook should be kept short.
106+ If it does more than ``return `` a static array, several caveats apply:
107+
108+ - If you need to use any Python C API, it is recommended to call
109+ :c:func: `PyABIInfo_Check ` first to raise an exception,
110+ rather than crash, in common cases of ABI mismatch.
111+ - Code in the export hook must never rely on the :term: `GIL `:
112+ :term: `free-threaded builds <free-threaded build> ` of Python can only check
113+ the :c:macro: `Py_mod_gil ` slot (or the lack of it) after the hook returns,
114+ - Similarly, the hook may be called in any subinterpreter, since the
115+ :c:macro: `Py_mod_multiple_interpreters ` slot (or lack of it)
116+ is only checked after the hook returns.
117+
118+ For example::
119+
120+ PyMODEXPORT_FUNC
121+ PyModExport_modulename(void)
122+ {
123+ if (PyABIInfo_Check(&abi_info, "modulename") < 0) {
124+ /* ABI mismatch. It's not safe to examine the raised exception. */
125+ return NULL;
126+ }
127+
128+ /* use Python API (as little as possible); don't rely on GIL */
129+
130+ return modulename_slots;
131+ }
108132
109133.. note ::
110134
0 commit comments