Капсулы

Дополнительную информацию об использовании этих объектов см. в разделе Предоставление API на C для модуля расширения.

type PyCapsule

Этот подтип PyObject представляет непрозрачное значение. Он полезен для модулей расширения на C, которым необходимо передавать непрозрачное значение (в виде указателя void*) через код Python в другой код на C. Его часто используют, чтобы сделать указатель на функцию C, определённую в одном модуле, доступным другим модулям, позволяя применять обычный механизм импорта для доступа к API на C, определённым в динамически загружаемых модулях.

PyTypeObject PyCapsule_Type

Часть стабильного ABI.

Объект типа, соответствующий объектам capsule. В слое Python это тот же объект, что и types.CapsuleType.

type PyCapsule_Destructor

Часть стабильного ABI.

Тип функции обратного вызова-деструктора для capsule. Определён следующим образом:

typedef void (*PyCapsule_Destructor)(PyObject *);

Семантику функций обратного вызова PyCapsule_Destructor см. в разделе PyCapsule_New().

int PyCapsule_CheckExact(PyObject *p)

Потокобезопасность: Атомарная.

Возвращает true, если аргумент является объектом PyCapsule. Эта функция всегда завершается успешно.

PyObject *PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)

Возвращаемое значение: новая ссылка. Часть стабильного ABI. Потокобезопасность: Атомарная.

Создаёт PyCapsule, содержащую указатель. Аргумент pointer не может быть NULL.

В случае ошибки устанавливает исключение и возвращает NULL.

Строка name может быть NULL или указателем на допустимую строку C. Если она не NULL, эта строка должна существовать дольше capsule. (Однако её разрешается освободить внутри деструктора.)

Если аргумент destructor не равен NULL, при уничтожении capsule он будет вызван с этой capsule в качестве аргумента.

Если эта capsule будет сохранена в качестве атрибута модуля, следует указать name как modulename.attributename. Это позволит другим модулям импортировать capsule с помощью PyCapsule_Import().

void *PyCapsule_GetPointer(PyObject *capsule, const char *name)

Часть стабильного ABI. Потокобезопасность: Безопасно вызывать для разных объектов без внешней синхронизации.

Извлекает указатель, хранящийся в capsule. В случае ошибки устанавливает исключение и возвращает NULL.

Параметр name должен в точности совпадать с именем, сохранённым в capsule. Если сохранённое в capsule имя равно NULL, переданный параметр name также должен быть NULL. Для сравнения имён capsule Python использует функцию C strcmp().

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)

Часть стабильного ABI. Потокобезопасность: Безопасно вызывать для разных объектов без внешней синхронизации.

Возвращает текущий деструктор, сохранённый в capsule. В случае ошибки устанавливает исключение и возвращает NULL.

Capsule может иметь деструктор NULL. Поэтому возвращаемое значение NULL может быть неоднозначным; для уточнения используйте PyCapsule_IsValid() или PyErr_Occurred().

void *PyCapsule_GetContext(PyObject *capsule)

Часть стабильного ABI. Потокобезопасность: Безопасно вызывать для разных объектов без внешней синхронизации.

Возвращает текущий контекст, сохранённый в capsule. В случае ошибки устанавливает исключение и возвращает NULL.

У capsule может быть контекст NULL. Поэтому возвращаемое значение NULL может быть неоднозначным; для уточнения используйте PyCapsule_IsValid() или PyErr_Occurred().

const char *PyCapsule_GetName(PyObject *capsule)

Часть стабильного ABI. Потокобезопасность: Безопасно вызывать для разных объектов без внешней синхронизации.

Возвращает текущее имя, сохранённое в capsule. В случае ошибки устанавливает исключение и возвращает NULL.

У capsule может быть имя NULL. Поэтому возвращаемое значение NULL может быть неоднозначным; для уточнения используйте PyCapsule_IsValid() или PyErr_Occurred().

void *PyCapsule_Import(const char *name, int no_block)

Часть стабильного ABI. Потокобезопасность: Безопасно вызывать из нескольких потоков только при наличии внешней синхронизации.

Импортирует указатель на объект C из атрибута capsule в модуле. Параметр name должен задавать полное имя атрибута, например module.attribute. Имя, сохранённое в capsule, должно в точности совпадать с этой строкой.

Эта функция разбивает name по символу . и импортирует первый элемент. Затем она обрабатывает остальные элементы с помощью поиска атрибутов.

В случае успеха возвращает внутренний указатель capsule. В случае ошибки устанавливает исключение и возвращает NULL.

Примечание

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

Изменено в версии 3.3: Параметр no_block больше не действует.

int PyCapsule_IsValid(PyObject *capsule, const char *name)

Часть стабильного ABI. Потокобезопасность: Безопасно вызывать для разных объектов без внешней синхронизации.

Определяет, является ли capsule допустимой capsule. Допустимая capsule не равна NULL, проходит проверку PyCapsule_CheckExact(), содержит указатель, отличный от NULL, а её внутреннее имя совпадает с параметром name. (Информацию о сравнении имён capsule см. в разделе PyCapsule_GetPointer().)

Иными словами, если PyCapsule_IsValid() возвращает истинное значение, вызовы любых функций доступа (функций, начинающихся с PyCapsule_Get) гарантированно завершатся успешно.

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

int PyCapsule_SetContext(PyObject *capsule, void *context)

Часть стабильного ABI. Потокобезопасность: Безопасно вызывать для разных объектов без внешней синхронизации.

Устанавливает указатель контекста внутри capsule равным context.

В случае успеха возвращает 0. В случае ошибки возвращает ненулевое значение и устанавливает исключение.

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)

Часть стабильного ABI. Потокобезопасность: Безопасно вызывать для разных объектов без внешней синхронизации.

Устанавливает деструктор внутри capsule равным destructor.

В случае успеха возвращает 0. В случае ошибки возвращает ненулевое значение и устанавливает исключение.

int PyCapsule_SetName(PyObject *capsule, const char *name)

Часть стабильного ABI. Потокобезопасность: Безопасно вызывать для разных объектов без внешней синхронизации.

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

В случае успеха возвращает 0. В случае ошибки возвращает ненулевое значение и устанавливает исключение.

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

Часть стабильного ABI. Потокобезопасность: Безопасно вызывать для разных объектов без внешней синхронизации.

Устанавливает указатель void внутри capsule равным pointer. Указатель не может быть NULL.

В случае успеха возвращает 0. В случае ошибки возвращает ненулевое значение и устанавливает исключение.