Identifying the Free-Threaded Build in C¶

The CPython C API exposes thePy_GIL_DISABLED macro: in the free-threadedbuild it's defined to1, and in the regular build it's not defined.You can use it to enable code that only runs under the free-threaded build:

#ifdef Py_GIL_DISABLED/* code that only runs in the free-threaded build */#endif

Module Initialization¶

Extension modules need to explicitly indicate that they support running withthe GIL disabled; otherwise importing the extension will raise a warning andenable the GIL at runtime.

There are two ways to indicate that an extension module supports running withthe GIL disabled depending on whether the extension uses multi-phase orsingle-phase initialization.

staticstructPyModuleDef_Slotmodule_slots[]={...#if PY_VERSION_HEX >= 0x030D0000{Py_mod_gil,Py_MOD_GIL_NOT_USED},#endif{0,NULL}};staticstructPyModuleDefmoduledef={PyModuleDef_HEAD_INIT,.m_slots=module_slots,...};

staticstructPyModuleDefmoduledef={PyModuleDef_HEAD_INIT,...};PyMODINIT_FUNCPyInit_mymodule(void){PyObject*m=PyModule_Create(&moduledef);if(m==NULL){returnNULL;}#ifdef Py_GIL_DISABLEDPyUnstable_Module_SetGIL(m,Py_MOD_GIL_NOT_USED);#endifreturnm;}

General API Guidelines¶

Most of the C API is thread-safe, but there are some exceptions.

• Struct Fields: Accessing fields in Python C API objects or structsdirectly is not thread-safe if the field may be concurrently modified.

• Macros: Accessor macros likePyList_GET_ITEM andPyList_SET_ITEM do not perform any error checking or locking.These macros are not thread-safe if the container object may be modifiedconcurrently.

• Borrowed References: C API functions that returnborrowed references may not be thread-safe ifthe containing object is modified concurrently. See the section onborrowed references for more information.

Py_BEGIN_CRITICAL_SECTION(dict);PyObject*key,*value;Py_ssize_tpos=0;while(PyDict_Next(dict,&pos,&key,&value)){...}Py_END_CRITICAL_SECTION();

Borrowed References¶

Some C API functions returnborrowed references.These APIs are not thread-safe if the containing object is modifiedconcurrently. For example, it's not safe to usePyList_GetItem()if the list may be modified concurrently.

The following table lists some borrowed reference APIs and their replacementsthat returnstrong references.

Not all APIs that return borrowed references are problematic. Forexample,PyTuple_GetItem() is safe because tuples are immutable.Similarly, not all uses of the above APIs are problematic. For example,PyDict_GetItem() is often used for parsing keyword argumentdictionaries in function calls; those keyword argument dictionaries areeffectively private (not accessible by other threads), so using borrowedreferences in that context is safe.

Some of these functions were added in Python 3.13. You can use thepythoncapi-compat packageto provide implementations of these functions for older Python versions.

Memory Allocation APIs¶

Python's memory management C API provides functions in three differentallocation domains: "raw", "mem", and "object".For thread-safety, the free-threaded build requires that only Python objectsare allocated using the object domain, and that all Python object areallocated using that domain. This differs from the prior Python versions,where this was only a best practice and not a hard requirement.

Thread State and GIL APIs¶

Python provides a set of functions and macros to manage thread state and theGIL, such as:

• PyGILState_Ensure() 和PyGILState_Release()

• PyEval_SaveThread() 和PyEval_RestoreThread()

• Py_BEGIN_ALLOW_THREADS 和Py_END_ALLOW_THREADS

These functions should still be used in the free-threaded build to managethread state even when theGIL is disabled. For example, if youcreate a thread outside of Python, you must callPyGILState_Ensure()before calling into the Python API to ensure that the thread has a validPython thread state.

You should continue to callPyEval_SaveThread() orPy_BEGIN_ALLOW_THREADS around blocking operations, such as I/O orlock acquisitions, to allow other threads to run thecyclic garbage collector.

Protecting Internal Extension State¶

Your extension may have internal state that was previously protected by theGIL. You may need to add locking to protect this state. The approach willdepend on your extension, but some common patterns include:

• Caches: global caches are a common source of shared state. Considerusing a lock to protect the cache or disabling it in the free-threaded buildif the cache is not critical for performance.

• Global State: global state may need to be protected by a lock or movedto thread local storage. C11 and C++11 provide thethread_local or_Thread_local forthread-local storage.

Building Extensions for the Free-Threaded Build¶

C API extensions need to be built specifically for the free-threaded build.The wheels, shared libraries, and binaries are indicated by at suffix.

• pypa/manylinux supports thefree-threaded build, with thet suffix, such aspython3.13t.

• pypa/cibuildwheel supports thefree-threaded build if you setCIBW_FREE_THREADED_SUPPORT.