Поддержка расширений C API для свободной многопоточности¶C API Extension Support for Free Threading

Определение сборки со свободной многопоточностью в C¶Identifying the Free-Threaded Build in C

C API CPython предоставляет макрос Py_GIL_DISABLED: в сборке со свободной многопоточностью он определён как 1, а в обычной сборке не определён. Его можно использовать для включения кода, который выполняется только в сборке со свободной многопоточностью:

#ifdef Py_GIL_DISABLED
/* код, который выполняется только в сборке со свободной многопоточностью */
#endif

Инициализация модуля¶Module Initialization

Модули расширения должны явно указать, что они поддерживают работу с отключённым GIL; иначе при импорте расширения будет выдано предупреждение и GIL будет включён во время выполнения.

Есть два способа указать, что модуль расширения поддерживает работу с отключённым GIL, в зависимости от того, использует ли расширение многофазную или однофазную инициализацию.

static struct PyModuleDef_Slot module_slots[] = {
    ...
#if PY_VERSION_HEX >= 0x030D0000
    {Py_mod_gil, Py_MOD_GIL_NOT_USED},
#endif
    {0, NULL}
};

static struct PyModuleDef moduledef = {
    PyModuleDef_HEAD_INIT,
    .m_slots = module_slots,
    ...
};

static struct PyModuleDef moduledef = {
    PyModuleDef_HEAD_INIT,
    ...
};

PyMODINIT_FUNC
PyInit_mymodule(void)
{
    PyObject *m = PyModule_Create(&moduledef);
    if (m == NULL) {
        return NULL;
    }
#ifdef Py_GIL_DISABLED
    PyUnstable_Module_SetGIL(m, Py_MOD_GIL_NOT_USED);
#endif
    return m;
}

Общие рекомендации по API¶General API Guidelines

Большая часть C API потокобезопасна, но есть некоторые исключения.

• Поля структур: прямой доступ к полям объектов C API Python или структур не является потокобезопасным, если поле может быть одновременно изменено.

• Макросы: Макросы-аксессоры, такие как PyList_GET_ITEM и PyList_SET_ITEM, не выполняют никаких проверок ошибок и блокировок. Эти макросы не являются потокобезопасными, если объект-контейнер может изменяться одновременно.

• Заимствованные ссылки: функции C API, возвращающие заимствованные ссылки, могут не быть потокобезопасными, если содержащий объект изменяется одновременно. См. раздел заимствованные ссылки для получения дополнительной информации.

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

Заимствованные ссылки¶Borrowed References

Некоторые функции C API возвращают заимствованные ссылки. Эти API не являются потокобезопасными, если содержащий объект изменяется одновременно. Например, небезопасно использовать PyList_GetItem(), если список может быть одновременно изменён.

В следующей таблице перечислены некоторые API заимствованных ссылок и их замены, которые возвращают сильные ссылки.

Не все API, возвращающие заимствованные ссылки, проблематичны. Например, PyTuple_GetItem() безопасен, так как кортежи неизменяемы. Аналогично, не все варианты использования вышеперечисленных API проблематичны. Например, PyDict_GetItem() часто используется для разбора словарей именованных аргументов в вызовах функций; эти словари именованных аргументов фактически являются приватными (недоступны другим потокам), поэтому использование заимствованных ссылок в этом контексте безопасно.

Некоторые из этих функций были добавлены в Python 3.13. Можно использовать пакет pythoncapi-compat, чтобы предоставить реализации этих функций для старых версий Python.

API выделения памяти¶Memory Allocation APIs

C API для управления памятью Python предоставляет функции в трёх различных доменах выделения: «raw», «mem» и «object». Для потокобезопасности сборка со свободной многопоточностью требует, чтобы только объекты Python выделялись с помощью домена object, и чтобы все объекты Python выделялись с его помощью. Это отличается от предыдущих версий Python, где это было только рекомендацией, а не жёстким требованием.

API состояния потока и GIL¶Thread State and GIL APIs

Python предоставляет набор функций и макросов для управления состоянием потока и GIL, например:

• PyGILState_Ensure() и PyGILState_Release()

• PyEval_SaveThread() и PyEval_RestoreThread()

• Py_BEGIN_ALLOW_THREADS и Py_END_ALLOW_THREADS

Эти функции по-прежнему следует использовать в сборке со свободными потоками для управления состоянием потока, даже когда GIL отключён. Например, если вы создаёте поток вне Python, необходимо вызвать PyGILState_Ensure() перед вызовом Python API, чтобы убедиться, что поток имеет корректное состояние потока Python.

Следует продолжать вызывать PyEval_SaveThread() или Py_BEGIN_ALLOW_THREADS вокруг блокирующих операций, таких как ввод-вывод или захват блокировок, чтобы позволить другим потокам запустить циклический сборщик мусора.

Защита внутреннего состояния расширения¶Protecting Internal Extension State

Ваше расширение может иметь внутреннее состояние, которое ранее защищалось GIL. Возможно, потребуется добавить блокировку для защиты этого состояния. Подход будет зависеть от вашего расширения, но некоторые распространённые шаблоны включают:

• Кэши: глобальные кэши – распространённый источник общего состояния. Рассмотрите возможность использования блокировки для защиты кэша или отключите его в сборке со свободными потоками, если кэш не критичен для производительности.

• Глобальное состояние: глобальное состояние может потребовать защиты с помощью блокировки или переноса в локальную память потока. В C11 и C++11 для локальной памяти потока предусмотрены thread_local или _Thread_local.

Сборка расширений для сборки со свободной многопоточностью¶Building Extensions for the Free-Threaded Build

Расширения C API необходимо собирать специально для сборки со свободной многопоточностью. Колеса (wheels), разделяемые библиотеки и двоичные файлы обозначаются суффиксом t.

• pypa/manylinux поддерживает сборку со свободной многопоточностью с суффиксом t, например python3.13t.

• pypa/cibuildwheel поддерживает сборку со свободной многопоточностью, если установить CIBW_ENABLE в cpython-freethreading.