Đối tượng biến bối cảnh

Added in version 3.7.

Thay đổi trong phiên bản 3.7.1:

Ghi chú

Trong Python 3.7.1, chữ ký của tất cả các biến ngữ cảnh API C là changed để sử dụng con trỏ PyObject thay vì PyContext, PyContextVar và PyContextToken, ví dụ:

// trong 3.7.0:
PyContext *PyContext_New(void);

// trong 3.7.1+:
PyObject *PyContext_New(void);

Xem bpo-34762 để biết thêm chi tiết.

Phần này trình bày chi tiết về C API công khai cho mô-đun contextvars.

type PyContext

Cấu trúc C được sử dụng để biểu diễn đối tượng contextvars.Context.

type PyContextVar

Cấu trúc C được sử dụng để biểu diễn đối tượng contextvars.ContextVar.

type PyContextToken

Cấu trúc C được sử dụng để biểu diễn đối tượng contextvars.Token.

PyTypeObject PyContext_Type

Đối tượng kiểu đại diện cho kiểu context.

PyTypeObject PyContextVar_Type

Đối tượng kiểu đại diện cho kiểu context variable.

PyTypeObject PyContextToken_Type

Đối tượng kiểu đại diện cho kiểu context variable token.

Macro kiểm tra loại:

int PyContext_CheckExact(PyObject *o)

Trả về true nếu o thuộc loại PyContext_Type. o không được là NULL. Chức năng này luôn thành công.

int PyContextVar_CheckExact(PyObject *o)

Trả về true nếu o thuộc loại PyContextVar_Type. o không được là NULL. Chức năng này luôn thành công.

int PyContextToken_CheckExact(PyObject *o)

Trả về true nếu o thuộc loại PyContextToken_Type. o không được là NULL. Chức năng này luôn thành công.

Chức năng quản lý đối tượng bối cảnh:

PyObject *PyContext_New(void)
Giá trị trả về: Tham chiếu mới.

Tạo một đối tượng bối cảnh trống mới. Trả về NULL nếu xảy ra lỗi.

PyObject *PyContext_Copy(PyObject *ctx)
Giá trị trả về: Tham chiếu mới.

Tạo một bản sao nông của đối tượng ngữ cảnh ctx đã truyền. Trả về NULL nếu xảy ra lỗi.

PyObject *PyContext_CopyCurrent(void)
Giá trị trả về: Tham chiếu mới.

Tạo một bản sao nông của bối cảnh luồng hiện tại. Trả về NULL nếu xảy ra lỗi.

int PyContext_Enter(PyObject *ctx)

Đặt ctx làm bối cảnh hiện tại cho chuỗi hiện tại. Trả về 0 nếu thành công và -1 nếu có lỗi.

int PyContext_Exit(PyObject *ctx)

Vô hiệu hóa bối cảnh ctx và khôi phục bối cảnh trước đó làm bối cảnh hiện tại cho chuỗi hiện tại. Trả về 0 nếu thành công và -1 nếu có lỗi.

int PyContext_AddWatcher(PyContext_WatchCallback callback)

Đăng ký callback làm trình theo dõi đối tượng ngữ cảnh cho trình thông dịch hiện tại. Trả lại ID có thể được chuyển tới PyContext_ClearWatcher(). Trong trường hợp có lỗi (ví dụ: không còn ID người theo dõi), hãy trả về -1 và đặt ngoại lệ.

Added in version 3.14.

int PyContext_ClearWatcher(int watcher_id)

Trình theo dõi rõ ràng được xác định bởi watcher_id trước đây được trả về từ PyContext_AddWatcher() cho trình thông dịch hiện tại. Trả về 0 nếu thành công hoặc -1 và đặt ngoại lệ nếu có lỗi (ví dụ: nếu watcher_id đã cho chưa bao giờ được đăng ký.)

Added in version 3.14.

type PyContextEvent

Việc liệt kê các sự kiện theo dõi đối tượng ngữ cảnh có thể có:

  • Py_CONTEXT_SWITCHED: current context đã chuyển sang bối cảnh khác. Đối tượng được chuyển đến lệnh gọi lại đồng hồ là đối tượng contextvars.Context hiện tại hoặc Không có nếu không có ngữ cảnh hiện tại.

Added in version 3.14.

typedef int (*PyContext_WatchCallback)(PyContextEvent event, PyObject *obj)

Chức năng gọi lại của trình theo dõi đối tượng bối cảnh. Đối tượng được chuyển đến lệnh gọi lại là đối tượng dành riêng cho sự kiện; xem PyContextEvent để biết chi tiết.

Nếu lệnh gọi lại trả về với một bộ ngoại lệ, nó phải trả về -1; ngoại lệ này sẽ được in dưới dạng ngoại lệ không thể xử lý được bằng PyErr_FormatUnraisable(). Nếu không nó sẽ trả về 0.

Có thể đã có một ngoại lệ đang chờ xử lý được đặt khi truy cập lệnh gọi lại. Trong trường hợp này, lệnh gọi lại sẽ trả về 0 với cùng một ngoại lệ vẫn được đặt. Điều này có nghĩa là lệnh gọi lại không được gọi bất kỳ API nào khác có thể đặt ngoại lệ trừ khi nó lưu và xóa trạng thái ngoại lệ trước, đồng thời khôi phục nó trước khi quay lại.

Added in version 3.14.

Hàm biến ngữ cảnh:

PyObject *PyContextVar_New(const char *name, PyObject *def)
Giá trị trả về: Tham chiếu mới.

Tạo một đối tượng ContextVar mới. Tham số name được sử dụng cho mục đích xem xét nội tâm và gỡ lỗi. Tham số def chỉ định giá trị mặc định cho biến ngữ cảnh hoặc NULL không có giá trị mặc định. Nếu xảy ra lỗi, hàm này trả về NULL.

int PyContextVar_Get(PyObject *var, PyObject *default_value, PyObject **value)

Lấy giá trị của biến bối cảnh. Trả về -1 nếu xảy ra lỗi trong quá trình tra cứu và 0 nếu không xảy ra lỗi, cho dù có tìm thấy giá trị hay không.

Nếu biến bối cảnh được tìm thấy, value sẽ là con trỏ tới biến đó. Nếu biến bối cảnh được tìm thấy not, value sẽ trỏ đến:

  • default_value, nếu không phải là NULL;

  • giá trị mặc định của var, nếu không phải là NULL;

  • NULL

Ngoại trừ NULL, hàm trả về một tham chiếu mới.

PyObject *PyContextVar_Set(PyObject *var, PyObject *value)
Giá trị trả về: Tham chiếu mới.

Đặt giá trị của var thành value trong ngữ cảnh hiện tại. Trả về một đối tượng mã thông báo mới cho thay đổi này hoặc NULL nếu xảy ra lỗi.

int PyContextVar_Reset(PyObject *var, PyObject *token)

Đặt lại trạng thái của biến ngữ cảnh var về trạng thái trước khi PyContextVar_Set() trả về token được gọi. Hàm này trả về 0 nếu thành công và -1 nếu có lỗi.