Multi-Phase Initialization¶

Extensions that use multi-phase initialization (i.e.,PyModuleDef_Init()) should add aPy_mod_gil slot in themodule definition. If your extension supports older versions of CPython,you should guard the slot with aPY_VERSION_HEX check.

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,...};

Single-Phase Initialization¶

Extensions that use single-phase initialization (i.e.,PyModule_Create()) should callPyUnstable_Module_SetGIL() toindicate that they support running with the GIL disabled. The function isonly defined in the free-threaded build, so you should guard the call with#ifdefPy_GIL_DISABLED to avoid compilation errors in the regular build.

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;}

Container Thread Safety¶

Containers likePyListObject,PyDictObject, andPySetObject perform internal lockingin the free-threaded build. For example, thePyList_Append() willlock the list before appending an item.

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

What Are Critical Sections?¶

Conceptually, critical sections act as a deadlock avoidance layer built ontop of simple mutexes. Each thread maintains a stack of active criticalsections. When a thread needs to acquire a lock associated with a criticalsection (e.g., implicitly when calling a thread-safe C API function likePyDict_SetItem(), or explicitly using macros), it attempts to acquirethe underlying mutex.

Using Critical Sections¶

The primary APIs for using critical sections are:

• Py_BEGIN_CRITICAL_SECTION andPy_END_CRITICAL_SECTION -For locking a single object

• Py_BEGIN_CRITICAL_SECTION2 andPy_END_CRITICAL_SECTION2- For locking two objects simultaneously

These macros must be used in matching pairs and must appear in the same Cscope, since they establish a new local scope. These macros are no-ops innon-free-threaded builds, so they can be safely added to code that needs tosupport both build types.

A common use of a critical section would be to lock an object while accessingan internal attribute of it. For example, if an extension type has an internalcount field, you could use a critical section while reading or writing thatfield:

// read the count, returns new reference to internal count valuePyObject*result;Py_BEGIN_CRITICAL_SECTION(obj);result=Py_NewRef(obj->count);Py_END_CRITICAL_SECTION();returnresult;// write the count, consumes reference from new_countPy_BEGIN_CRITICAL_SECTION(obj);obj->count=new_count;Py_END_CRITICAL_SECTION();

How Critical Sections Work¶

Unlike traditional locks, critical sections do not guarantee exclusive accessthroughout their entire duration. If a thread would block while holding acritical section (e.g., by acquiring another lock or performing I/O), thecritical section is temporarily suspended—all locks are released—and thenresumed when the blocking operation completes.

This behavior is similar to what happens with the GIL when a thread makes ablocking call. The key differences are:

• Critical sections operate on a per-object basis rather than globally

• Critical sections follow a stack discipline within each thread (the “begin” and“end” macros enforce this since they must be paired and within the same scope)

• Critical sections automatically release and reacquire locks around potentialblocking operations

Deadlock Avoidance¶

Critical sections help avoid deadlocks in two ways:

1. If a thread tries to acquire a lock that’s already held by another thread,it first suspends all of its active critical sections, temporarily releasingtheir locks

2. When the blocking operation completes, only the top-most critical section isreacquired first

This means you cannot rely on nested critical sections to lock multiple objectsat once, as the inner critical section may suspend the outer ones. Instead, usePy_BEGIN_CRITICAL_SECTION2 to lock two objects simultaneously.

Note that the locks described above are onlyPyMutex based locks.The critical section implementation does not know about or affect other lockingmechanisms that might be in use, like POSIX mutexes. Also note that whileblocking on anyPyMutex causes the critical sections to besuspended, only the mutexes that are part of the critical sections arereleased. IfPyMutex is used without a critical section, it willnot be released and therefore does not get the same deadlock avoidance.

Important Considerations¶

• Critical sections may temporarily release their locks, allowing other threadsto modify the protected data. Be careful about making assumptions about thestate of the data after operations that might block.

• Because locks can be temporarily released (suspended), entering a criticalsection does not guarantee exclusive access to the protected resourcethroughout the section’s duration. If code within a critical section callsanother function that blocks (e.g., acquires another lock, performs blockingI/O), all locks held by the thread via critical sections will be released.This is similar to how the GIL can be released during blocking calls.

• Only the lock(s) associated with the most recently entered (top-most)critical section are guaranteed to be held at any given time. Locks forouter, nested critical sections might have been suspended.

• You can lock at most two objects simultaneously with these APIs. If you needto lock more objects, you’ll need to restructure your code.

• While critical sections will not deadlock if you attempt to lock the sameobject twice, they are less efficient than purpose-built reentrant locks forthis use case.

• When usingPy_BEGIN_CRITICAL_SECTION2, the order of the objectsdoesn’t affect correctness (the implementation handles deadlock avoidance),but it’s good practice to always lock objects in a consistent order.

• Remember that the critical section macros are primarily for protecting accesstoPython objects that might be involved in internal CPython operationssusceptible to the deadlock scenarios described above. For protecting purelyinternal extension state, standard mutexes or other synchronizationprimitives might be more appropriate.

Limited C API and Stable ABI¶

The free-threaded build does not currently support theLimited C API or the stable ABI. If you usesetuptools to buildyour extension and currently setpy_limited_api=True you can usepy_limited_api=notsysconfig.get_config_var("Py_GIL_DISABLED") to opt outof the limited API when building with the free-threaded build.

Windows¶

Due to a limitation of the official Windows installer, you will need tomanually definePy_GIL_DISABLED=1 when building extensions from source.