Поддержка расширений C API для Free Threading

Идентификация сборки с бесплатными потоками в C

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

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

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

Модули расширений должны явно указывать, что они поддерживают работу с отключенным 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

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

• Поля структур: Доступ к полям в объектах или структурах Python C API напрямую не является потокобезопасным, если поле может быть одновременно изменено.
• Макросы: Макросы-аксессоры, такие как 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();

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

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

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

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

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

API выделения памяти

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

Состояние потока и API GIL

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

• PyGILState_Ensure() и PyGILState_Release()
• PyEval_SaveThread() и PyEval_RestoreThread()
• Py_BEGIN_ALLOW_THREADS и Py_END_ALLOW_THREADS

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

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

Защита внутреннего состояния расширения

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

• Кэши: глобальные кэши — распространённый источник совместного состояния. Рассмотрите возможность использования блокировки для защиты кэша или отключения его в сборке с поддержкой свободных потоков, если кэш не является критическим для производительности.
• Глобальное состояние: глобальное состояние может потребовать защиты блокировкой или перемещения в хранилище локальных потоков. C11 и C++11 предоставляют thread_local или _Thread_local для хранилища локальных потоков.

Создание расширений для сборки с поддержкой свободных потоков

Расширения API C должны быть скомпилированы специально для сборки с поддержкой свободных потоков. Упаковки, общие библиотеки и двоичные файлы маркируются суффиксом t.

• pypa/manylinux поддерживает сборку с поддержкой свободных потоков с суффиксом t, например python3.13t.
• pypa/cibuildwheel поддерживает сборку с поддержкой свободных потоков, если вы установите CIBW_FREE_THREADED_SUPPORT.