Viên nang

Tham khảo Cung cấp C API cho Mô-đun mở rộng để biết thêm thông tin về cách sử dụng các đối tượng này.

Added in version 3.1.

type PyCapsule

Loại con này của PyObject đại diện cho một giá trị mờ, hữu ích cho các mô-đun mở rộng C cần chuyển một giá trị mờ (dưới dạng con trỏ void*) thông qua mã Python sang mã C khác. Nó thường được sử dụng để cung cấp một con trỏ hàm C được xác định trong một mô-đun cho các mô-đun khác, do đó, cơ chế nhập thông thường có thể được sử dụng để truy cập các API C được xác định trong các mô-đun được tải động.

PyTypeObject PyCapsule_Type

Một phần của ABI ổn định.

Đối tượng loại tương ứng với đối tượng viên nang. Đây là đối tượng tương tự như types.CapsuleType trong lớp Python.

type PyCapsule_Destructor

Một phần của ABI ổn định.

Kiểu gọi lại hàm hủy cho một viên nang. Được xác định là:

khoảng trống typedef (*PyCapsule_Destructor)(PyObject *);

Xem PyCapsule_New() để biết ngữ nghĩa của lệnh gọi lại PyCapsule_Destructor.

int PyCapsule_CheckExact(PyObject *p)

Thread safety: Atomic.

Trả về true nếu đối số của nó là PyCapsule. Chức năng này luôn thành công.

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

Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định. Thread safety: Atomic.

Tạo một PyCapsule đóng gói pointer. Đối số pointer có thể không phải là NULL.

Nếu thất bại, hãy đặt ngoại lệ và trả về NULL.

Chuỗi name có thể là NULL hoặc một con trỏ tới chuỗi C hợp lệ. Nếu không phải là NULL, chuỗi này phải tồn tại lâu hơn trong hộp. (Mặc dù được phép giải phóng nó bên trong destructor.)

Nếu đối số destructor không phải là NULL, nó sẽ được gọi với viên nang làm đối số khi nó bị hủy.

Nếu viên nang này sẽ được lưu trữ dưới dạng thuộc tính của mô-đun, thì name phải được chỉ định là modulename.attributename. Điều này sẽ cho phép các mô-đun khác nhập viên nang bằng PyCapsule_Import().

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

Một phần của ABI ổn định. Thread safety: Safe to call without external synchronization on distinct objects.

Lấy pointer được lưu trữ trong viên nang. Nếu thất bại, hãy đặt ngoại lệ và trả về NULL.

Tham số name phải so sánh chính xác với tên được lưu trong Capsule. Nếu tên được lưu trong hộp là NULL thì name được chuyển vào cũng phải là NULL. Python sử dụng hàm C strcmp() để so sánh tên viên nang.

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)

Một phần của ABI ổn định. Thread safety: Safe to call without external synchronization on distinct objects.

Trả về hàm hủy hiện tại được lưu trữ trong viên nang. Nếu thất bại, hãy đặt ngoại lệ và trả về NULL.

Việc một viên nang có bộ hủy NULL là hợp pháp. Điều này làm cho mã trả về NULL hơi mơ hồ; sử dụng PyCapsule_IsValid() hoặc PyErr_Occurred() để phân biệt.

void *PyCapsule_GetContext(PyObject *capsule)

Một phần của ABI ổn định. Thread safety: Safe to call without external synchronization on distinct objects.

Trả về bối cảnh hiện tại được lưu trữ trong viên nang. Nếu thất bại, hãy đặt ngoại lệ và trả về NULL.

Việc một viên nang có ngữ cảnh NULL là hợp pháp. Điều này làm cho mã trả về NULL hơi mơ hồ; sử dụng PyCapsule_IsValid() hoặc PyErr_Occurred() để phân biệt.

const char *PyCapsule_GetName(PyObject *capsule)

Một phần của ABI ổn định. Thread safety: Safe to call without external synchronization on distinct objects.

Trả lại tên hiện tại được lưu trong viên nang. Nếu thất bại, hãy đặt ngoại lệ và trả về NULL.

Việc một viên nang có tên NULL là hợp pháp. Điều này làm cho mã trả về NULL hơi mơ hồ; sử dụng PyCapsule_IsValid() hoặc PyErr_Occurred() để phân biệt.

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

Một phần của ABI ổn định. Thread safety: Safe to call from multiple threads with external synchronization only.

Nhập con trỏ tới đối tượng C từ thuộc tính Capsule trong mô-đun. Tham số name phải chỉ định tên đầy đủ cho thuộc tính, như trong module.attribute. Zz002zz được lưu trữ trong viên nang phải khớp chính xác với chuỗi này.

Hàm này tách name trên ký tự . và nhập phần tử đầu tiên. Sau đó nó xử lý các phần tử tiếp theo bằng cách sử dụng tra cứu thuộc tính.

Trả lại pointer bên trong của viên nang thành công. Nếu thất bại, hãy đặt ngoại lệ và trả về NULL.

Ghi chú

Nếu name trỏ đến một thuộc tính của một số mô hình con hoặc gói con, thì mô hình con hoặc gói con này trước đó phải được nhập bằng các phương tiện khác (ví dụ: bằng cách sử dụng PyImport_ImportModule()) để việc tra cứu thuộc tính thành công.

Thay đổi trong phiên bản 3.3: no_block không còn tác dụng nữa.

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

Một phần của ABI ổn định. Thread safety: Safe to call without external synchronization on distinct objects.

Xác định xem capsule có phải là viên nang hợp lệ hay không. Một viên hợp lệ không phải là NULL, vượt qua PyCapsule_CheckExact(), có một con trỏ không phải NULL được lưu trữ trong đó và tên bên trong của nó khớp với tham số name. (Xem PyCapsule_GetPointer() để biết thông tin về cách so sánh tên viên nang.)

Nói cách khác, nếu PyCapsule_IsValid() trả về giá trị thực, các lệnh gọi tới bất kỳ trình truy cập nào (bất kỳ hàm nào bắt đầu bằng PyCapsule_Get) đều được đảm bảo thành công.

Trả về giá trị khác 0 nếu đối tượng hợp lệ và khớp với tên được truyền vào. Ngược lại, trả về 0. Chức năng này sẽ không thất bại.

int PyCapsule_SetContext(PyObject *capsule, void *context)

Một phần của ABI ổn định. Thread safety: Safe to call without external synchronization on distinct objects.

Đặt con trỏ ngữ cảnh bên trong capsule thành context.

Trả về 0 khi thành công. Trả về giá trị khác 0 và đặt ngoại lệ khi thất bại.

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)

Một phần của ABI ổn định. Thread safety: Safe to call without external synchronization on distinct objects.

Đặt hàm hủy bên trong capsule thành destructor.

Trả về 0 khi thành công. Trả về giá trị khác 0 và đặt ngoại lệ khi thất bại.

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

Một phần của ABI ổn định. Thread safety: Safe to call without external synchronization on distinct objects.

Đặt tên bên trong capsule thành name. Nếu không phải là NULL, tên đó phải tồn tại lâu hơn trong hộp. Nếu name trước đó được lưu trữ trong viên nang không phải là NULL thì sẽ không có nỗ lực nào để giải phóng nó.

Trả về 0 khi thành công. Trả về giá trị khác 0 và đặt ngoại lệ khi thất bại.

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

Một phần của ABI ổn định. Thread safety: Safe to call without external synchronization on distinct objects.

Đặt con trỏ void bên trong capsule thành pointer. Con trỏ có thể không phải là NULL.

Trả về 0 khi thành công. Trả về giá trị khác 0 và đặt ngoại lệ khi thất bại.