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

Многофазная инициализация

Расширения, использующие многофазную инициализацию (то есть 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,
    ...
};

Однофазная инициализация

Расширения, использующие однофазную инициализацию (то есть PyModule_Create()), должны вызвать PyUnstable_Module_SetGIL(), чтобы указать, что они поддерживают работу с отключённой GIL. Эта функция определена только в сборке со свободной многопоточностью, поэтому вызов следует защитить с помощью #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;
}

Потокобезопасность контейнеров

Контейнеры, такие как 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();

Что такое критические секции?

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

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

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

• Py_BEGIN_CRITICAL_SECTION и Py_END_CRITICAL_SECTION — для блокировки одного объекта
• Py_BEGIN_CRITICAL_SECTION2 и Py_END_CRITICAL_SECTION2 — для одновременной блокировки двух объектов

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

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

// read the count, returns new reference to internal count value
PyObject *result;
Py_BEGIN_CRITICAL_SECTION(obj);
result = Py_NewRef(obj->count);
Py_END_CRITICAL_SECTION();
return result;

// write the count, consumes reference from new_count
Py_BEGIN_CRITICAL_SECTION(obj);
obj->count = new_count;
Py_END_CRITICAL_SECTION();

Как работают критические секции

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

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

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

Предотвращение взаимных блокировок

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

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

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

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

Важные замечания

• Критические секции могут временно освобождать свои блокировки, позволяя другим потокам изменять защищённые данные. Будьте осторожны с предположениями о состоянии данных после операций, которые могут заблокировать поток.
• Поскольку блокировки могут временно освобождаться (приостанавливаться), вход в критическую секцию не гарантирует исключительный доступ к защищённому ресурсу на протяжении всей секции. Если код внутри критической секции вызывает другую функцию, которая блокирует поток (например, получает другую блокировку или выполняет блокирующий ввод-вывод), все блокировки, удерживаемые потоком в рамках критических секций, будут освобождены. Это похоже на освобождение GIL во время блокирующих вызовов.
• В любой момент гарантированно удерживаются только блокировки, связанные с последней открытой (самой верхней) критической секцией. Блокировки внешних, вложенных критических секций могли быть приостановлены.
• С помощью этих API можно одновременно заблокировать не более двух объектов. Если необходимо блокировать больше объектов, потребуется переработать код.
• Хотя критические секции не приводят к взаимной блокировке при попытке дважды заблокировать один и тот же объект, для такого сценария они менее эффективны, чем специализированные рекурсивные блокировки.
• При использовании Py_BEGIN_CRITICAL_SECTION2 порядок объектов не влияет на корректность (реализация сама предотвращает взаимные блокировки), однако рекомендуется всегда блокировать объекты в одном и том же порядке.
• Помните, что макросы критических секций предназначены прежде всего для защиты доступа к объектам Python, которые могут участвовать во внутренних операциях CPython, подверженных описанным выше сценариям взаимной блокировки. Для защиты исключительно внутреннего состояния расширения могут лучше подойти стандартные мьютексы или другие примитивы синхронизации.

Ограниченный C API и стабильный 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.