Add a C macro to configure "Py_mod_gil" at C compile time (GH-7404)

scoder · web-flow · commit 066da48828b8 · 2025-12-12T10:42:41.000+01:00
I found a use case for setting `Py_mod_gil` differently in Py3.13 and Py3.14,
but regenerating the whole C file just to switch between them is rather wasteful.
So here's a new C macro `CYTHON_FREETHREADING_COMPATIBLE` that allows
defining the setting from the outside.

Having a directive is still useful because we don't want to require the
C macro to be set. It should usually have a fixed value for a given module.
diff --git a/Cython/Compiler/ModuleNode.py b/Cython/Compiler/ModuleNode.py
@@ -979,6 +979,17 @@ def generate_module_preamble(self, env, options, cimported_modules, metadata, co
             code.putln("#endif")
             code.putln("")
 
+        code.putln("#ifdef CYTHON_FREETHREADING_COMPATIBLE")
+        code.putln("#if CYTHON_FREETHREADING_COMPATIBLE")
+        code.putln("#define __Pyx_FREETHREADING_COMPATIBLE Py_MOD_GIL_NOT_USED")
+        code.putln("#else")
+        code.putln("#define __Pyx_FREETHREADING_COMPATIBLE Py_MOD_GIL_USED")
+        code.putln("#endif")
+        code.putln("#else")
+        ft_compatible = "Py_MOD_GIL_NOT_USED" if env.directives["freethreading_compatible"] else "Py_MOD_GIL_USED"
+        code.putln(f"#define __Pyx_FREETHREADING_COMPATIBLE {ft_compatible}")
+        code.putln("#endif")
+
         c_string_type = env.directives['c_string_type']
         c_string_encoding = env.directives['c_string_encoding']
         if c_string_type not in ('bytes', 'bytearray') and not c_string_encoding:
@@ -3628,10 +3639,7 @@ def generate_pymoduledef_struct(self, env, code):
         code.putln("{Py_mod_create, (void*)%s}," % Naming.pymodule_create_func_cname)
         code.putln("{Py_mod_exec, (void*)%s}," % exec_func_cname)
         code.putln("#if CYTHON_COMPILING_IN_CPYTHON_FREETHREADING")
-        gil_option = ("Py_MOD_GIL_NOT_USED"
-                      if env.directives["freethreading_compatible"]
-                      else "Py_MOD_GIL_USED")
-        code.putln("{Py_mod_gil, %s}," % gil_option)
+        code.putln("{Py_mod_gil, __Pyx_FREETHREADING_COMPATIBLE},")
         code.putln("#endif")
         code.putln("#if PY_VERSION_HEX >= 0x030C0000 && CYTHON_USE_MODULE_STATE")
         subinterp_option = {
diff --git a/docs/src/userguide/source_files_and_compilation.rst b/docs/src/userguide/source_files_and_compilation.rst
@@ -960,6 +960,8 @@ Cython code.  Here is the list of currently supported directives:
     the logic and consider it safe to run. Since free-threading support
     is still experimental itself, this is also an experimental directive that
     might be changed or removed in future releases.
+    This option can be overridden at C compile time by setting the
+    ``CYTHON_FREETHREADING_COMPATIBLE`` C macro to 1/0 for True/False.
 
 ``subinterpreters_compatible``  (no / shared_gil / own_gil), *default=no*
     If set to ``shared_gil`` or ``own_gil``, then Cython sets the
@@ -1416,6 +1418,12 @@ most important to least important:
     to the constants due to reference counting. Disabled by default, but enabled
     in free-threaded builds.
 
+``CYTHON_FREETHREADING_COMPATIBLE``
+    In Freethreading Python runtimes, setting this to ``0`` will force enabling
+    the GIL when importing the module, ``1`` will keep it untouched.
+    The default setting depends on the ``freethreading_compatible`` directive.
+    This C macro allows to override the directive at C compile time.
+
 There is a further list of macros which turn off various optimizations or language
 features.  Under normal circumstance Cython enables these automatically based on the
 version of Python you are compiling for so there is no need to use them
