Изоляция модулей расширений¶Isolating Extension Modules

Состояние модуля¶Enter Per-Module State

Вместо концентрации на состоянии на интерпретатор, C API Python развивается в сторону лучшей поддержки более детализированного состояния на модуль. Это означает, что данные уровня C должны быть привязаны к объекту модуля. Каждый интерпретатор создаёт свой собственный объект модуля, так что данные остаются разделёнными. Для проверки изоляции в одном интерпретаторе можно загружать даже несколько объектов модулей, соответствующих одному расширению.

Состояние на модуль даёт простой способ мыслить о времени жизни и владении ресурсами: расширение инициализируется при создании объекта модуля и очищается при его освобождении. В этом отношении модуль – это просто любой другой PyObject*; не нужно думать – или забывать – о хуках «при завершении интерпретатора».

Обратите внимание, что существуют варианты использования разных видов «глобальных» переменных: состояние на процесс, на интерпретатор, на поток или на задачу. При состоянии на модуль как умолчании они всё ещё возможны, но их следует рассматривать как исключительные случаи: если они нужны, нужно уделить им дополнительное внимание и тестирование. (Заметим, что данное руководство их не рассматривает.)

Изолированные объекты модулей¶Isolated Module Objects

Ключевой момент, который следует помнить при разработке расширения: из одной разделяемой библиотеки может быть создано несколько объектов модуля. Например:

>>> import sys
>>> import binascii
>>> old_binascii = binascii
>>> del sys.modules['binascii']
>>> import binascii  # создать новый объект модуля
>>> old_binascii == binascii
False

Как правило, два модуля должны быть полностью независимы. Все объекты и состояние, специфичные для модуля, должны быть инкапсулированы внутри объекта модуля, не разделяться с другими объектами модулей и очищаться при освобождении объекта модуля. Поскольку это лишь общее правило, возможны исключения (см. раздел Управление глобальным состоянием), но они потребуют больше размышлений и внимания к краевым случаям.

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

Неожиданные краевые случаи¶Surprising Edge Cases

Заметьте, что изолированные модули действительно создают некоторые неожиданные краевые случаи. В частности, каждый объект модуля обычно не разделяет свои классы и исключения с другими аналогичными модулями. Продолжая пример выше, заметьте, что old_binascii.Error и binascii.Error – это разные объекты. В следующем коде исключение не перехватывается:

>>> old_binascii.Error == binascii.Error
False
>>> try:
...     old_binascii.unhexlify(b'qwertyuiop')
... except binascii.Error:
...     print('boo')
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
binascii.Error: Non-hexadecimal digit found

Это ожидаемо. Заметьте, что чисто Python-модули ведут себя так же: это часть того, как работает Python.

Цель – сделать расширения безопасными на уровне C, а не заставлять «хаки» вести себя интуитивно. Изменение sys.modules «вручную» считается хаком.

Управление глобальным состоянием¶Managing Global State

Иногда состояние, связанное с модулем Python, не является специфичным для этого модуля, а относится ко всему процессу (или чему-то «более глобальному», чем модуль). Например:

• Модуль readline управляет терминалом.

• Модуль, работающий на плате, хочет управлять встроенным светодиодом.

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

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

Управление состоянием на модуль¶Managing Per-Module State

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

Установите PyModuleDef.m_size в положительное число, чтобы запросить соответствующее количество байт локального хранилища для модуля. Обычно это устанавливается в размер некоторой struct, специфичной для модуля, которая может хранить всё C-уровневое состояние модуля. В частности, сюда следует помещать указатели на классы (включая исключения, но исключая статические типы) и настройки (например, csv’s field_size_limit), которые нужны C-коду для работы.

Если состояние модуля включает указатели PyObject, объект модуля должен удерживать ссылки на эти объекты и реализовывать хуки на уровне модуля m_traverse, m_clear и m_free. Они работают как tp_traverse, tp_clear и tp_free у класса. Их добавление потребует некоторой работы и сделает код длиннее; это цена за модули, которые можно чисто выгружать.

Пример модуля с состоянием уровня модуля в настоящее время доступен как xxlimited; пример инициализации модуля приведён в нижней части файла.

Отказ: ограничение одним объектом модуля на процесс¶Opt-Out: Limiting to One Module Object per Process

Неотрицательное значение PyModuleDef.m_size указывает, что модуль корректно поддерживает несколько интерпретаторов. Если ваш модуль этого ещё не делает, вы можете явно сделать его загружаемым только один раз на процесс. Например:

// Флаг уровня процесса
static int loaded = 0;

// Мьютекс для обеспечения потокобезопасности (требуется только для free-threaded Python)
static PyMutex modinit_mutex = {0};

static int
exec_module(PyObject* module)
{
    PyMutex_Lock(&modinit_mutex);
    if (loaded) {
        PyMutex_Unlock(&modinit_mutex);
        PyErr_SetString(PyExc_ImportError,
                        "cannot load module more than once per process");
        return -1;
    }
    loaded = 1;
    PyMutex_Unlock(&modinit_mutex);
    // остальная часть инициализации
}

Если функция PyModuleDef.m_clear вашего модуля способна подготовиться к будущей повторной инициализации, она должна сбросить флаг loaded. В этом случае ваш модуль не будет поддерживать одновременное существование нескольких экземпляров одновременно, но он будет, например, поддерживать загрузку после завершения работы среды выполнения Python (Py_FinalizeEx()) и повторную инициализацию (Py_Initialize()).

Доступ к состоянию модуля из функций¶Module State Access from Functions

Доступ к состоянию из функций уровня модуля не представляет сложности. Функции получают объект модуля в качестве первого аргумента; для извлечения состояния можно использовать PyModule_GetState:

static PyObject *
func(PyObject *module, PyObject *args)
{
    my_struct *state = (my_struct*)PyModule_GetState(module);
    if (state == NULL) {
        return NULL;
    }
    // остальная часть логики
}

Преобразование статических типов в кучные типы¶Changing Static Types to Heap Types

Статические типы можно преобразовать в кучные, но учтите, что API кучных типов не был разработан для преобразования «без потерь» из статических типов – то есть для создания типа, работающего в точности как данный статический тип. Поэтому при переписывании определения класса в новом API вы, вероятно, непреднамеренно измените некоторые детали (например, возможность сериализации или унаследованные слоты). Всегда тестируйте детали, важные для вас.

Обратите особое внимание на следующие два пункта (но учтите, что это не исчерпывающий список):

• В отличие от статических типов, объекты кучных типов по умолчанию изменяемы. Используйте флаг Py_TPFLAGS_IMMUTABLETYPE, чтобы предотвратить изменяемость.

• Кучные типы по умолчанию наследуют tp_new, поэтому может стать возможным создание их экземпляров из кода Python. Вы можете предотвратить это с помощью флага Py_TPFLAGS_DISALLOW_INSTANTIATION.

Определение кучных типов¶Defining Heap Types

Кучные типы можно создать, заполнив структуру PyType_Spec, которая является описанием или «чертежом» класса, и вызвав PyType_FromModuleAndSpec() для создания нового объекта класса.

Класс обычно следует хранить как в состоянии модуля (для безопасного доступа из C), так и в __dict__ модуля (для доступа из кода Python).

Протокол сборки мусора¶Garbage-Collection Protocol

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

Чтобы избежать утечек памяти, экземпляры кучных типов должны реализовывать протокол сборки мусора. А именно, кучные типы должны:

• Иметь флаг Py_TPFLAGS_HAVE_GC.

• Определить функцию обхода с помощью Py_tp_traverse, которая посещает тип (например, с помощью Py_VISIT(Py_TYPE(self))).

Обратитесь к документации Py_TPFLAGS_HAVE_GC и tp_traverse для дополнительных сведений.

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

static int my_traverse(PyObject *self, visitproc visit, void *arg)
{
    if (Py_Version >= 0x03090000) {
        Py_VISIT(Py_TYPE(self));
    }
    return 0;
}

base->tp_traverse(self, visit, arg)

if (base->tp_flags & Py_TPFLAGS_HEAPTYPE) {
    // tp_traverse типа‑кучи уже посетил Py_TYPE(self)
} else {
    if (Py_Version >= 0x03090000) {
        Py_VISIT(Py_TYPE(self));
    }
}

static void my_dealloc(PyObject *self)
{
    PyObject_GC_UnTrack(self);
    ...
    PyTypeObject *type = Py_TYPE(self);
    type->tp_free(self);
    Py_DECREF(type);
}

Доступ к состоянию модуля из классов¶Module State Access from Classes

Если у вас есть объект типа, определенный с PyType_FromModuleAndSpec(), вы можете вызвать PyType_GetModule(), чтобы получить связанный модуль, а затем PyModule_GetState(), чтобы получить состояние модуля.

Чтобы избавиться от утомительного шаблонного кода обработки ошибок, вы можете объединить эти два шага с помощью PyType_GetModuleState(), получив:

my_struct *state = (my_struct*)PyType_GetModuleState(type);
if (state == NULL) {
    return NULL;
}

Доступ к состоянию модуля из обычных методов¶Module State Access from Regular Methods

Доступ к состоянию на уровне модуля из методов класса несколько сложнее, но возможен благодаря API, введенному в Python 3.9. Чтобы получить состояние, сначала нужно получить определяющий класс, а затем получить из него состояние модуля.

Самое большое препятствие – получение класса, в котором был определен метод, или, сокращенно, «определяющего класса» этого метода. Определяющий класс может содержать ссылку на модуль, частью которого он является.

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

class Base:
    def get_type_of_self(self):
        return type(self)

    def get_defining_class(self):
        return __class__

class Sub(Base):
    pass

Чтобы метод получил свой «определяющий класс», он должен использовать METH_METHOD | METH_FASTCALL | METH_KEYWORDS calling convention и соответствующую сигнатуру PyCMethod:

PyObject *PyCMethod(
    PyObject *self,               // объект, на котором вызван метод
    PyTypeObject *defining_class, // определяющий класс
    PyObject *const *args,        // C‑массив аргументов
    Py_ssize_t nargs,             // длина "args"
    PyObject *kwnames)            // NULL или словарь именованных аргументов

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

Например:

static PyObject *
example_method(PyObject *self,
        PyTypeObject *defining_class,
        PyObject *const *args,
        Py_ssize_t nargs,
        PyObject *kwnames)
{
    my_struct *state = (my_struct*)PyType_GetModuleState(defining_class);
    if (state == NULL) {
        return NULL;
    }
    ... // остальная логика
}

PyDoc_STRVAR(example_method_doc, "...");

static PyMethodDef my_methods[] = {
    {"example_method",
      (PyCFunction)(void(*)(void))example_method,
      METH_METHOD|METH_FASTCALL|METH_KEYWORDS,
      example_method_doc}
    {NULL},
}

Доступ к состоянию модуля из слотовых методов, геттеров и сеттеров¶Module State Access from Slot Methods, Getters and Setters

Слот-методы – быстрые C-эквиваленты специальных методов, такие как nb_add для __add__ или tp_new для инициализации – имеют очень простой API, который не позволяет передавать определяющий класс, в отличие от PyCMethod. То же самое относится к геттерам и сеттерам, определённым с помощью PyGetSetDef.

Чтобы получить состояние модуля в таких случаях, используйте функцию PyType_GetModuleByDef() и передайте определение модуля. Получив модуль, вызовите PyModule_GetState(), чтобы получить состояние:

PyObject *module = PyType_GetModuleByDef(Py_TYPE(self), &module_def);
my_struct *state = (my_struct*)PyModule_GetState(module);
if (state == NULL) {
    return NULL;
}

PyType_GetModuleByDef() работает путём поиска в порядке разрешения методов (то есть во всех суперклассах) первого суперкласса, у которого есть соответствующий модуль.

Время жизни состояния модуля¶Lifetime of the Module State

Когда объект модуля собирается сборщиком мусора, его состояние освобождается. Для каждого указателя на (часть) состояния модуля необходимо удерживать ссылку на объект модуля.

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

Область видимости для класса¶Per-Class Scope

На данный момент (начиная с Python 3.11) невозможно привязать состояние к отдельным типам, не полагаясь на детали реализации CPython (которые могут измениться в будущем – возможно, по иронии судьбы, чтобы обеспечить правильное решение для области видимости на класс).

Преобразование в кучевые типы без потерь¶Lossless Conversion to Heap Types

API кучевых типов не был разработан для «без потерь» преобразования из статических типов; то есть для создания типа, который работает точно так же, как заданный статический тип.