Изолирующие модули расширения¶

Ввод состояния для каждого модуля¶

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

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

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

Изолированные модульные объекты¶

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

>>> import sys
>>> import binascii
>>> old_binascii = binascii
>>> del sys.modules['binascii']
>>> import binascii  # create a new module object
>>> old_binascii == binascii
False

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

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

Неожиданные крайние случаи¶

Обратите внимание, что изолированные модули действительно создают некоторые неожиданные пограничные ситуации. Наиболее примечательно, что каждый объект module обычно не использует свои классы и исключения совместно с другими подобными модулями. Продолжая с example above, обратите внимание, что 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 «вручную» считается взломом.

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

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

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

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

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

Если необходимо использовать process-global state, самый простой способ избежать проблем с несколькими интерпретаторами — это явно запретить загрузку модуля более одного раза для каждого процесса - см. Opt-Out: Limiting to One Module Object per Process.

Управление состоянием каждого модуля¶

Чтобы использовать состояние для каждого модуля, используйте multi-phase extension module initialization. Это означает, что ваш модуль правильно поддерживает несколько интерпретаторов.

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

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

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

Отказ: Ограничение одним объектом модуля для каждого процесса¶

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

static int loaded = 0;

static int
exec_module(PyObject* module)
{
    if (loaded) {
        PyErr_SetString(PyExc_ImportError,
                        "cannot load module more than once per process");
        return -1;
    }
    loaded = 1;
    // ... rest of initialization
}

Доступ к состоянию модуля из функций¶

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

static PyObject *
func(PyObject *module, PyObject *args)
{
    my_struct *state = (my_struct*)PyModule_GetState(module);
    if (state == NULL) {
        return NULL;
    }
    // ... rest of logic
}

Изменение статических типов на типы кучи¶

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

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

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

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

Определение типов кучи¶

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

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

Протокол сбора мусора¶

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

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

• Имейте флаг 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) {
    // a heap type's tp_traverse already visited 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);
}

Доступ к состоянию модуля из классов¶

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

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

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

Доступ к состоянию модуля с помощью обычных методов¶

Доступ к состоянию на уровне модуля из методов класса несколько сложнее, но возможен благодаря 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,               // object the method was called on
    PyTypeObject *defining_class, // defining class
    PyObject *const *args,        // C array of arguments
    Py_ssize_t nargs,             // length of "args"
    PyObject *kwnames)            // NULL, or dict of keyword arguments

Как только у вас будет определяющий класс, вызовите 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;
    }
    ... // rest of logic
}

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

Доступ к состоянию модуля из методов Slot, получателей и установщиков¶

Методы Slot — быстрые эквиваленты 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() работает путем поиска в method resolution order (т.е. во всех суперклассах) первого суперкласса, у которого есть соответствующий модуль.

Время жизни состояния модуля¶

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

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

Область применения для каждого класса¶

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

Преобразование в типы кучи без потерь¶

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