スレッドローカルストレージのサポート

Python インタープリタは、基盤となるネイティブの TLS 実装をラップした低水準のスレッドローカルストレージ (TLS) を提供し、 Python レベルのスレッドローカルストレージ API (threading.local) を支えます。 CPython の C レベルの API は pthreads や Windows が提供するものと似ており、スレッドキーと関数を使って、スレッドごとに void* 値を関連付けます。

これらの関数は独自にロックを行うため、呼び出す際に スレッド状態 が アタッチされている 必要は ありません。

Python.h は TLS API の宣言を include せず、スレッドローカルストレージを使うには pythread.h を include する必要があることに注意してください。

注釈

この API 関数はどれも void* 値の代わりにメモリ管理を行うことはしません。 メモリの確保と解放は自前で行う必要があります。 void* 値がたまたま PyObject* だった場合は、 API 関数はそれぞれの値の参照カウントの操作は行いません。

スレッド固有ストレージ API

スレッド固有ストレージ (TSS) API は、CPython インタープリタ内で使われていた TLS API を置き換えるために導入されました。 スレッドキーの表現には int ではなく、新しい型 Py_tss_t を使います。

Added in version 3.7.

参考

"CPython のスレッドローカルストレージのための新しい C API" (PEP 539)

type Py_tss_t

このデータ構造体はスレッドキーの状態を表現しています。この構造体の定義は、根底の TLS 実装に依存し、キーの初期化状態を表現する内部フィールドを持ちます。 この構造体には公開 (public) のメンバはありません。

Py_LIMITED_API が定義されていないときは、この型の Py_tss_NEEDS_INIT による静的メモリ確保ができます。

Py_tss_NEEDS_INIT

このマクロは Py_tss_t 変数の初期化子に展開されます。 このマクロは Py_LIMITED_API があるときは定義されません。

動的なメモリ確保

動的な Py_tss_t のメモリ確保は Py_LIMITED_API でビルドされた拡張モジュールで必要になりますが、その実装がビルド時に不透明なために、この型の静的なメモリ確保は不可能です。

Py_tss_t *PyThread_tss_alloc()

次に属します: Stable ABI (バージョン 3.7 より).

Py_tss_NEEDS_INIT で初期化した値と同じ状態の値を返します。 動的なメモリ確保に失敗した場合は NULL を返します。

void PyThread_tss_free(Py_tss_t *key)

次に属します: Stable ABI (バージョン 3.7 より).

まず PyThread_tss_delete() を呼んで、関連付けられたスレッドローカルな値との対応を解除してから、 PyThread_tss_alloc() で確保した key を解放します。 key 引数が NULL の場合は何もしません。

注釈

解放したキーはダングリングポインタになります。 キーを NULL に設定し直してください。

メソッド

これらの関数の引数 key は NULL であってはなりません。 また、指定された Py_tss_t を PyThread_tss_create() で初期化していなければ、 PyThread_tss_set() と PyThread_tss_get() の動作は未定義です。

int PyThread_tss_is_created(Py_tss_t *key)

次に属します: Stable ABI (バージョン 3.7 より).

指定された Py_tss_t が PyThread_tss_create() で初期化されていれば、0 以外の値を返します。

int PyThread_tss_create(Py_tss_t *key)

次に属します: Stable ABI (バージョン 3.7 より).

TSS キーの初期化に成功すると 0 を返します。 key 引数が指す値を Py_tss_NEEDS_INIT で初期化していなければ、動作は未定義です。 同じキーに対して繰り返し呼び出せます。 初期化済みのキーに対しては何もせず、即座に成功を返します。

void PyThread_tss_delete(Py_tss_t *key)

次に属します: Stable ABI (バージョン 3.7 より).

TSS キーを破棄し、すべてのスレッドでそのキーに関連付けられた値との対応を解除して、キーを未初期化の状態にします。 破棄したキーは PyThread_tss_create() で再び初期化できます。 同じキーに対して繰り返し呼び出せます。 破棄済みのキーに対しては何もしません。

int PyThread_tss_set(Py_tss_t *key, void *value)

次に属します: Stable ABI (バージョン 3.7 より).

現在のスレッドで void* 値を TSS キーに関連付けることに成功すると、0 を返します。 キーから void* 値への対応付けは、スレッドごとに独立しています。

void *PyThread_tss_get(Py_tss_t *key)

次に属します: Stable ABI (バージョン 3.7 より).

現在のスレッドで TSS キーに関連付けられている void* 値を返します。 現在のスレッドでそのキーに値が関連付けられていなければ、NULL を返します。

従来の API

バージョン 3.7 で非推奨: この API は スレッド固有ストレージ (TSS) API に置き換えられました。

注釈

このバージョンの API は、ネイティブの TLS キーを安全に int へキャストできないプラットフォームをサポートしません。 そのようなプラットフォームでは、PyThread_create_key() は即座に失敗を示す値を返し、その他の TLS 関数はすべて何もしません。

前述の互換性の問題により、このバージョンのAPIは新規のコードで利用すべきではありません。

int PyThread_create_key()

次に属します: Stable ABI.

void PyThread_delete_key(int key)

次に属します: Stable ABI.

int PyThread_set_key_value(int key, void *value)

次に属します: Stable ABI.

void *PyThread_get_key_value(int key)

次に属します: Stable ABI.

void PyThread_delete_key_value(int key)

次に属します: Stable ABI.

void PyThread_ReInitTLS()

次に属します: Stable ABI.