コンテキスト変数オブジェクト
****************************

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_New(void)
    *戻り値: 新しい参照。*

   新しい空のコンテキストオブジェクトを作成します。 エラーが起きた場合
   は "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* コンテキストを無効にし、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" を返します。
