コンテキスト変数オブジェクト¶
Added in version 3.7.
バージョン 3.7.1 で変更:
注釈
Python 3.7.1 で全てのコンテキスト変数の C API のシグネチャは、 PyContext, PyContextVar, PyContextToken の代わりに PyObject ポインタを使うように 変更 されました。例えば:
// 3.7.0 では:
PyContext *PyContext_New(void);
// 3.7.1 以降では:
PyObject *PyContext_New(void);
詳細は bpo-34762 を参照してください。
この節では、 contextvars モジュールの公開 C API の詳細について説明します。
-
type PyContext¶
contextvars.Contextオブジェクトを表現するための C 構造体。
-
type PyContextVar¶
contextvars.ContextVarオブジェクトを表現するための C 構造体。
-
type PyContextToken¶
contextvars.Tokenオブジェクトを表現するための C 構造体。
-
PyTypeObject PyContext_Type¶
コンテキスト 型を表現する型オブジェクト。
-
PyTypeObject PyContextVar_Type¶
コンテキスト変数 型を表現する型オブジェクト。
-
PyTypeObject PyContextToken_Type¶
コンテキスト変数トークン 型を表現する型オブジェクト。
型チェックマクロ:
-
int PyContext_CheckExact(PyObject *o)¶
o が
PyContext_Typeの場合に真を返します。 o はNULLであってはなりません。 この関数は常に成功します。
-
int PyContextVar_CheckExact(PyObject *o)¶
o が
PyContextVar_Typeの場合に真を返します。 o はNULLであってはなりません。 この関数は常に成功します。
-
int PyContextToken_CheckExact(PyObject *o)¶
o が
PyContextToken_Typeの場合に真を返します。 o はNULLであってはなりません。 この関数は常に成功します。
コンテキストオブジェクトを取り扱う関数:
-
PyObject *PyContext_Copy(PyObject *ctx)¶
- 戻り値: 新しい参照。
渡された ctx コンテキストオブジェクトの浅いコピーを作成します。 エラーが起きた場合は
NULLを返します。
-
PyObject *PyContext_CopyCurrent(void)¶
- 戻り値: 新しい参照。
現在のコンテキストオブジェクトの浅いコピーを作成します。 エラーが起きた場合は
NULLを返します。
-
int PyContext_Exit(PyObject *ctx)¶
ctx コンテキストを無効にし、1 つ前のコンテキストを現在のスレッドの現在のコンテキストに復元します。 成功したら
0を、失敗したら-1を返します。
-
int PyContext_AddWatcher(PyContext_WatchCallback callback)¶
callback を現在のインタープリタのコンテキストオブジェクトのウォッチャーとして登録します。
PyContext_ClearWatcher()に渡せる ID を返します。 利用できるウォッチャー ID が残っていない場合など、エラーの場合は例外を設定して-1を返します。Added in version 3.14.
-
int PyContext_ClearWatcher(int watcher_id)¶
現在のインタープリタについて、
PyContext_AddWatcher()が以前に返した watcher_id で識別されるウォッチャーを解除します。 成功すると0を返します。 指定した watcher_id が登録されていない場合など、エラーの場合は例外を設定して-1を返します。Added in version 3.14.
-
type PyContextEvent¶
コンテキストオブジェクトのウォッチャーが受け取るイベントの列挙:
Py_CONTEXT_SWITCHED: 現在のコンテキスト が別のコンテキストに切り替わりました。 ウォッチャーのコールバックに渡されるオブジェクトは、新たに現在のコンテキストとなったcontextvars.Contextオブジェクト、または現在のコンテキストがなければNoneです。
Added in version 3.14.
-
typedef int (*PyContext_WatchCallback)(PyContextEvent event, PyObject *obj)¶
コンテキストオブジェクトのウォッチャーのコールバック関数です。 コールバックに渡されるオブジェクトはイベントによって異なります。 詳しくは
PyContextEventを参照してください。コールバックが例外を設定して戻る場合、
-1を返さなければなりません。 この例外は、送出できない例外としてPyErr_FormatUnraisable()で表示されます。 それ以外の場合は0を返してください。コールバックに入る時点で、すでに保留中の例外が設定されている場合があります。 この場合、コールバックはその例外を設定したまま
0を返してください。 したがって、例外状態を最初に保存してクリアし、戻る前に復元するのでなければ、コールバックは例外を設定する可能性がある他の API を呼び出してはなりません。Added in version 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でなければ) default_value(
NULLでなければ) var のデフォルト値NULL
NULLを除けば、この関数は新しい参照を返します。
-
PyObject *PyContextVar_Set(PyObject *var, PyObject *value)¶
- 戻り値: 新しい参照。
現在のコンテキストにおいて var の値を value にセットします。この変更による新しいトークンオブジェクトか、エラーが起こった場合は
NULLを返します。
-
int PyContextVar_Reset(PyObject *var, PyObject *token)¶
var コンテキスト変数の状態をリセットし、 token を返した
PyContextVar_Set()が呼ばれる前の状態に戻します。 この関数は成功したら0、失敗したら-1を返します。