上下文變數物件¶

在 3.7 版本加入。

3.7.1 版中的變更

備註

在 Python 3.7.1 中，所有上下文變數 C API 的簽名都已更改，以使用 PyObject 指標，而不是 PyContext、PyContextVar 和 PyContextToken，例如。

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

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

有關更多詳細資訊，請參閱 bpo-34762。

本節詳細介紹了 contextvars 模組的公共 C API。

型別檢查宏

int PyContext_CheckExact(PyObject *o)¶: 如果 o 的型別為 PyContext_Type，則返回 true。 o 不得為 NULL。此函式總是成功。

int PyContextVar_CheckExact(PyObject *o)¶: 如果 o 的型別為 PyContextVar_Type，則返回 true。 o 不得為 NULL。此函式總是成功。

int PyContextToken_CheckExact(PyObject *o)¶: 如果 o 的型別為 PyContextToken_Type，則返回 true。 o 不得為 NULL。此函式總是成功。

上下文物件管理函式

PyObject *PyContext_Copy(PyObject *ctx)¶: 返回值：新引用。
建立傳入的 ctx 上下文物件的淺複製。如果發生錯誤，則返回 NULL。

PyObject *PyContext_CopyCurrent(void)¶: 返回值：新引用。
建立當前執行緒上下文的淺複製。如果發生錯誤，則返回 NULL。

int PyContext_Enter(PyObject *ctx)¶: 將 ctx 設定為當前執行緒的當前上下文。成功時返回 0，錯誤時返回 -1。

int PyContext_Exit(PyObject *ctx)¶: 停用 ctx 上下文並將上一個上下文恢復為當前執行緒的當前上下文。成功時返回 0，錯誤時返回 -1。

int PyContext_AddWatcher(PyContext_WatchCallback callback)¶: 將 callback 註冊為當前直譯器的上下文物件監視器。返回一個 ID，該 ID 可以傳遞給 PyContext_ClearWatcher()。如果發生錯誤（例如，沒有更多的監視器 ID 可用），則返回 -1 並設定異常。

在 3.14 版本加入。

int PyContext_ClearWatcher(int watcher_id)¶: 清除由 watcher_id 標識的監視器，該 ID 先前從 PyContext_AddWatcher() 返回，用於當前直譯器。成功時返回 0，如果發生錯誤（例如，如果給定的 watcher_id 從未註冊過），則返回 -1 並設定異常。

在 3.14 版本加入。

type PyContextEvent¶

可能的上下文物件監視器事件的列舉

Py_CONTEXT_SWITCHED: 當前上下文已切換到不同的上下文。傳遞給監視回撥的物件是當前活動的 contextvars.Context 物件，如果沒有上下文是當前活動的，則為 None。

在 3.14 版本加入。

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

上下文物件監視器回撥函式。傳遞給回撥的物件是特定於事件的；有關詳細資訊，請參閱 PyContextEvent。

如果回撥返回時設定了異常，則必須返回 -1；此異常將使用 PyErr_FormatUnraisable() 作為不可引發的異常列印。否則應返回 0。

進入回撥時可能已經設定了掛起異常。在這種情況下，回撥應返回 0，並保持相同的異常設定。這意味著回撥不能呼叫任何其他可能設定異常的 API，除非它首先儲存並清除異常狀態，並在返回之前恢復它。

在 3.14 版本加入。

上下文變數函式

PyObject *PyContextVar_New(const char *name, PyObject *def)¶: 返回值：新引用。
建立一個新的 ContextVar 物件。 name 引數用於自省和除錯。 def 引數指定上下文變數的預設值，如果沒有預設值，則為 NULL。如果發生錯誤，此函式返回 NULL。

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

獲取上下文變數的值。如果查詢過程中發生錯誤，則返回 -1，如果沒有發生錯誤，無論是否找到值，都返回 0。

如果找到上下文變數，value 將是指向它的指標。如果未找到上下文變數，value 將指向

除了 NULL 之外，該函式返回一個新引用。

PyObject *PyContextVar_Set(PyObject *var, PyObject *value)¶: 返回值：新引用。
在當前上下文中將 var 的值設定為 value。返回此更改的新令牌物件，如果發生錯誤，則返回 NULL。

int PyContextVar_Reset(PyObject *var, PyObject *token)¶: 將 var 上下文變數的狀態重置為呼叫返回 token 的 PyContextVar_Set() 之前它所處的狀態。此函式在成功時返回 0，在錯誤時返回 -1。