Миграция на стабильный ABI для свободной многопоточности (abi3t)¶Migrating to Stable ABI for free threading (abi3t)

Зачем это нужно¶Why do this

Обычная причина использования стабильного ABI – сократить количество артефактов, которые необходимо собирать и распространять для каждой версии своей библиотеки.

Без стабильного ABI необходимо собирать отдельную разделяемую библиотеку и, как правило, дистрибутив wheel для каждой функциональной версии CPython, которую требуется поддерживать. Например, каждый тег в следующей таблице представляет отдельную библиотеку/wheel:

Это много сборок, особенно если умножить на количество поддерживаемых платформ.

Благодаря стабильному ABI (abi3, представленному в CPython 3.2), одно расширение (на платформу) может покрывать все сборки без свободной потоковости CPython:

Стабильный ABI для сборок со свободной потоковостью (abi3t), представленный в CPython 3.15, делает то же самое для сборок со свободной потоковостью. И он также совместим со сборками без свободной потоковости:

* (Как и выше, расширение abi3 совместимо со всеми сборками без свободной потоковости; даже с теми версиями 3.15+, которые эта таблица «приписывает» abi3t.)

Предварительные требования¶Prerequisites

В этом руководстве предполагается, что у вас есть расширение, написанное непосредственно на C (или C++), которое вы хотите портировать на abi3t.

Если ваше расширение использует генератор кода (например, Cython) или языковую привязку (например, PyO3), лучше подождать, пока этот инструмент не получит поддержку abi3t. Если вы поддерживаете такой инструмент, возможно, вы сможете адаптировать инструкции из этого руководства для своего инструмента.

Настройка сборки¶Setting up the build

Если вы используете инструмент сборки (например, setuptools, meson-python, scikit-build-core), найдите в его документации способ выбрать abi3t. На момент написания не все они это поддерживают; но если ваш инструмент поддерживает, используйте его. Возможно, вам стоит проверить, что он установил правильный флаг, временно добавив следующий код сразу после #include <Python.h>:

#if Py_TARGET_ABI3T+0 <= 0x30f0000
#error "abi3t define is not set!"
#endif

Это должно привести к другой ошибке, нежели «abt3t define is not set».

#define Py_TARGET_ABI3T 0x30f0000

-DPy_TARGET_ABI3T=0x30f0000

В этом руководстве вам будет предложено выполнить ряд изменений. После каждого изменения проверяйте, что ваше расширение по-прежнему собирается в исходной (не-abi3t) конфигурации, и желательно запускайте тесты на всех поддерживаемых вами версиях Python. Это гарантирует, что в процессе портирования ничего не сломается.

Хук экспорта модуля¶Module export hook

Если вы ещё не выполнили этот шаг, ваш модуль расширения определяет функцию инициализации модуля с именем PyInit_<module_name>. Вам нужно будет перенести её в хук экспорта модуля, PyModExport_<module name>, функцию, добавленную в CPython 3.15 в PEP 793.

Ваша существующая функция init должна выглядеть примерно так (с вашими собственными именами для <modname> и <moddef>):

PyMODINIT_FUNC
PyInit_<modname>(void)
{
    return PyModuleDef_Init(&<moddef>);
}

Если перед return есть какой-то код, переместите его в слот-функцию Py_mod_create или Py_mod_exec. См. документацию PyInit для получения дополнительной информации.

Функция ссылается на объект PyModuleDef (<moddef> в коде выше). Его определение должно быть похоже на следующее, с другими значениями и, возможно, некоторыми неименованными или пропущенными полями:

static PyModuleDef <moddef> = {
    PyModuleDef_HEAD_INIT,
    .m_name = "my_module",
    .m_doc = "my docstring",
    .m_size = sizeof(my_state_struct),
    .m_methods = my_methods,
    .m_slots = my_slots,
    .m_traverse = my_traverse,
    .m_clear = my_clear,
    .m_free = my_free,
};

Удалите это определение и функцию PyInit (или поместите их в блок #ifndef Py_TARGET_ABI3T для сохранения обратной совместимости), и замените их следующим:

PyABIInfo_VAR(abi_info);

static PySlot my_slot_array[] = {
    PySlot_STATIC_DATA(Py_mod_abi, &abi_info),
    PySlot_STATIC_DATA(Py_mod_name, "my_module"),
    PySlot_STATIC_DATA(Py_mod_doc, "my docstring"),
    PySlot_SIZE(Py_mod_state_size, sizeof(my_state_struct)),
    PySlot_STATIC_DATA(Py_mod_methods, my_methods),
    PySlot_STATIC_DATA(Py_mod_slots, my_slots),
    PySlot_FUNC(Py_mod_state_traverse, my_traverse),
    PySlot_FUNC(Py_mod_state_clear, my_clear),
    PySlot_FUNC(Py_mod_state_free, my_free),
    PySlot_END
};

PyMODEXPORT_FUNC
PyModExport_<modname>(void)
{
    return my_slot_array;
}

Опустите любые поля, которые отсутствовали (кроме нового Py_mod_abi), и подставьте свои собственные значения.

См. документацию PySlot и хука экспорта для получения подробностей об этом API.

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

static PyObject *create_module(PyObject *spec, PyModuleDef *def) { ... }
static int my_first_module_exec(PyObject *module) { ... }
static int my_second_module_exec(PyObject *module) { ... }

static PyModuleDef_Slot my_slots[] = {
   {Py_mod_gil, Py_MOD_GIL_NOT_USED},
   {Py_mod_multiple_interpreters, Py_MOD_PER_INTERPRETER_GIL_SUPPORTED},
   {Py_mod_create, my_module_create},
   {Py_mod_exec, my_first_module_exec},
   {Py_mod_exec, my_second_module_exec},
   {0, NULL}
};

static PyObject *create_module(PyObject *spec, PyModuleDef *_unused) { ... }

static int my_module_exec(PyObject *module) {
   if (my_first_module_exec(module) < 0) return -1;
   if (my_second_module_exec(module) < 0) return -1;
}

static PyModuleDef_Slot my_slots[] = {
   ...
   /* удалить остальные слоты Py_mod_exec */
   ...
   {Py_mod_exec, my_module_exec},
   {0, NULL}
};

static PySlot my_slot_array[] = {
    ...
    PySlot_DATA(Py_mod_gil, Py_MOD_GIL_NOT_USED),
    PySlot_DATA(Py_mod_multiple_interpreters,
         Py_MOD_PER_INTERPRETER_GIL_SUPPORTED)
    PySlot_FUNC(Py_mod_create, my_module_create),
    PySlot_FUNC(Py_mod_exec, my_module_exec),
    PySlot_END
};

PyObject непрозрачность¶PyObject opaqueness

Структуры PyObject и PyVarObject являются непрозрачными в abi3t.

Обращаться к их членам запрещено. Если вы это делали, переключитесь на функции-геттеры/сеттеры, упомянутые в их документации:

• PyObject.ob_type

• PyObject.ob_refcnt

• PyVarObject.ob_size

Кроме того, компилятору неизвестен размер структур PyObject. Он может – и действительно – изменяться между разными сборками CPython.

typedef struct {
   PyObject_HEAD  // раскрывается в `PyObject ob_base;` с неизвестным размером

   int my_data;
} CustomObject;

static PyType_Spec CustomType_spec = {
   ...
   .basicsize = sizeof(CustomObject),
   ...
};

typedef struct {
   int my_data;
} CustomObjectData;

static PyType_Spec CustomType_spec = {
   ...
   .basicsize = -sizeof(CustomObjectData), /* обратите внимание на знак минус */
   ...
};

PyObject *obj = ...;
CustomObjectData *data = PyObject_GetTypeData(obj, cls);

class Sub(YourCustomClass):
   __slots__ = ('a', 'b')

╭─ PyObject *obj
│              ╭─ the pointer you want
│              │                    ╭─ PyObject_GetTypeData(obj, Py_TYPE(obj))
▼              ▼                    ▼
┌──────────┬───┬────────────────┬───┬─────────────┬───┬─────────────┐
│ PyObject │...│ CustomTypeData │...│ PyObject *a │...│ PyObject *b │
└──────────┴───┴────────────────┴───┴─────────────┴───┴─────────────┘

Избегайте условной компиляции¶Avoid build-time conditionals

Проверьте свой код на наличие API, определяющего версию Python, под которую собран ваш модуль расширения. Больше это не соответствует той версии Python, на которой модуль выполняется, поэтому такой код часто требует изменений. Ищите следующие макросы:

• PY_VERSION_HEX, PY_MAJOR_VERSION, PY_MINOR_VERSION:

  • Чтобы получить версию времени выполнения, используйте Py_Version;

  • Чтобы определить, какой C API доступен, используйте Py_TARGET_ABI3T. Этот макрос устанавливается в минимальную поддерживаемую версию.

• Py_GIL_DISABLED: в abi3t этот макрос всегда определён. Код, работающий со свободно-поточной версией Python, должен также работать и с включённым GIL (поскольку GIL может быть включён во время выполнения), и обычно работает (если только по какой-то причине ему не требуется более одного прикреплённого состояния потока одновременно).

Дальнейшие изменения кода¶Further code changes

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

Если вы столкнулись с проблемой, с которой могут встретиться другие авторы расширений, рассмотрите возможность сообщить о проблеме (или отправить pull request) для этого руководства.

Возможно, вашу проблему невозможно исправить в текущей версии abi3t. В таком случае сообщение о ней может помочь расставить приоритеты для следующей версии CPython.

Тегирование и распространение¶Tagging and distribution

Если вы используете инструмент сборки с поддержкой abi3t, ваше расширение готово, но вы, возможно, захотите проверить, что оно собрано правильно.

Расширения, собранные с abi3t, должны иметь следующее расширение:

• В Windows: .pyd (как и любое другое расширение);

• Linux, macOS и другие системы, использующие суффикс .so: .abi3t.so (не .cpython-315t.so или .abi3.so). Обратите внимание, что как свободно-поточные, так и несвободно-поточные сборки будут загружать расширения .abi3t.so;

• Другие системы: обратитесь к своему дистрибьютору и, возможно, обновите это руководство.

Если вы распространяете расширение в виде wheel, используйте следующие теги:

• Тег Python: cp3XX, где XX – минимальная версия Python, для которой собрано расширение. (Например, cp315, если вы установили Py_TARGET_ABI3T в 0x30f0000. См. Компиляция для стабильного ABI для других значений.)

• Тег ABI: abi3.abi3t. Это сжатый набор тегов, который указывает на поддержку как несвободно-поточных, так и свободно-поточных сборок.

Например, имя файла wheel может выглядеть так:

myproject-1.0-cp315-abi3.abi3t-macosx_11_0_arm64.whl

Если имя файла или теги неверны, исправьте их.

Тестирование¶Testing

Обратите внимание: при сборке расширения, совместимого с несколькими версиями CPython, следует всегда тестировать его с каждой поддерживаемой версией (например, 3.15, 3.16 и так далее). Стабильный ABI гарантирует только ABI-совместимость; возможны также изменения поведения – как намеренные (описанные в PEP 387), так и ошибки.

Обязательно запускайте тесты как на свободно-поточной, так и на несвободно-поточной сборках CPython.

Если они проходят, поздравляем! У вас есть расширение abi3t.