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

Многофазная инициализация¶Multi-Phase Initialization

Расширения, использующие многофазную инициализацию (т.е. PyModuleDef_Init()), должны добавить слот Py_mod_gil в определение модуля. Если расширение поддерживает старые версии CPython, следует защитить слот проверкой PY_VERSION_HEX.

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

Однофазная инициализация¶Single-Phase Initialization

Расширения, использующие однофазную инициализацию (т.е. PyModule_Create()), должны вызывать PyUnstable_Module_SetGIL(), чтобы указать, что они поддерживают работу с отключённым GIL. Эта функция определена только в free-threaded сборке, поэтому вызов следует защитить проверкой #ifdef Py_GIL_DISABLED, чтобы избежать ошибок компиляции в обычной сборке.

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

Потокобезопасность контейнеров¶Container Thread Safety

Контейнеры, такие как PyListObject, PyDictObject и PySetObject, выполняют внутреннюю блокировку в сборке со свободными потоками. Например, PyList_Append() будет блокировать список перед добавлением элемента.

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

Что такое критические секции?¶What Are Critical Sections?

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

Использование критических секций¶Using Critical Sections

Основные API для работы с критическими секциями:

• Py_BEGIN_CRITICAL_SECTION и Py_END_CRITICAL_SECTION – для блокировки одного объекта

• Py_BEGIN_CRITICAL_SECTION2 и Py_END_CRITICAL_SECTION2 – для одновременной блокировки двух объектов

Эти макросы должны использоваться парами и находиться в одной области видимости C, так как они создают новую локальную область. Эти макросы ничего не делают в сборках без свободной потоковой обработки, поэтому их можно безопасно добавлять в код, который должен поддерживать оба типа сборки.

Типичное применение критической секции – блокировка объекта при доступе к его внутреннему атрибуту. Например, если тип расширения имеет внутреннее поле счётчика, можно использовать критическую секцию при чтении или записи этого поля:

// читать счётчик, возвращает новую ссылку на внутреннее значение счётчика
PyObject *result;
Py_BEGIN_CRITICAL_SECTION(obj);
result = Py_NewRef(obj->count);
Py_END_CRITICAL_SECTION();
return result;

// записывать счётчик, потребляет ссылку из new_count
Py_BEGIN_CRITICAL_SECTION(obj);
obj->count = new_count;
Py_END_CRITICAL_SECTION();

Как работают критические секции¶How Critical Sections Work

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

Такое поведение аналогично тому, что происходит с GIL, когда поток выполняет блокирующий вызов. Ключевые отличия:

• Критические секции работают пообъектно, а не глобально

• Критические секции подчиняются стековой дисциплине в рамках каждого потока (макросы «begin» и «end» обеспечивают это, поскольку они должны быть парными и находиться в одной области видимости)

• Критические секции автоматически освобождают и повторно захватывают блокировки вокруг потенциально блокирующих операций

Предотвращение взаимоблокировок¶Deadlock Avoidance

Критические секции помогают избежать взаимоблокировок двумя способами:

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

2. После завершения блокирующей операции сначала повторно захватывается только самая верхняя критическая секция

Это означает, что нельзя полагаться на вложенные критические секции для блокировки нескольких объектов одновременно, так как внутренняя критическая секция может приостановить внешние. Вместо этого используйте Py_BEGIN_CRITICAL_SECTION2 для одновременной блокировки двух объектов.

Обратите внимание, что описанные выше блокировки – это только блокировки на основе PyMutex. Реализация критических секций не знает о других механизмах блокировки, которые могут использоваться (например, мьютексах POSIX), и не влияет на них. Также учтите, что блокирование на любом PyMutex приводит к приостановке критических секций, но освобождаются только мьютексы, входящие в состав критических секций. Если PyMutex используется без критической секции, он не будет освобождён и, следовательно, не получит того же предотвращения взаимоблокировок.

Важные замечания¶Important Considerations

• Критические секции могут временно освобождать свои блокировки, позволяя другим потокам изменять защищённые данные. Будьте осторожны с предположениями о состоянии данных после операций, которые могут блокироваться.

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

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

• С помощью этих API можно блокировать не более двух объектов одновременно. Если потребуется заблокировать больше объектов, придётся перестроить код.

• Хотя критические секции не приводят к взаимоблокировке при попытке заблокировать один и тот же объект дважды, для такого случая они менее эффективны, чем специально разработанные рекурсивные блокировки.

• При использовании Py_BEGIN_CRITICAL_SECTION2 порядок объектов не влияет на корректность (реализация сама предотвращает взаимоблокировки), но рекомендуется всегда блокировать объекты в одном и том же порядке.

• Помните, что макросы критических секций предназначены в первую очередь для защиты доступа к объектам Python, которые могут участвовать во внутренних операциях CPython, подверженных описанным выше сценариям взаимоблокировок. Для защиты чисто внутреннего состояния расширения более подходящими могут оказаться стандартные мьютексы или другие примитивы синхронизации.

Ограниченный C API и стабильный ABI¶Limited C API and Stable ABI

Сборка со свободной многопоточностью в настоящее время не поддерживает Ограниченный C API или стабильный ABI. Если вы используете setuptools для сборки вашего расширения и в настоящее время устанавливаете py_limited_api=True, вы можете использовать py_limited_api=not sysconfig.get_config_var("Py_GIL_DISABLED"), чтобы отказаться от ограниченного API при сборке со свободной многопоточностью.

Windows¶

Из-за ограничения официального установщика Windows вам потребуется вручную определить Py_GIL_DISABLED=1 при сборке расширений из исходных кодов.