# Thread-local storage support

The Python interpreter provides low-level support for thread-local storage (TLS) which wraps the underlying native TLS implementation to support the Python-level thread-local storage API (`threading.local`). The CPython C level APIs are similar to those offered by pthreads and Windows: use a thread key and functions to associate a void* value per thread.

A thread state does not need to be attached when calling these functions; they supply their own locking.

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

注釈

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

## Thread-specific storage API

The thread-specific storage (TSS) API was introduced to supersede the use of the existing TLS API within the CPython interpreter. This API uses a new type `Py_tss_t` instead of int to represent thread keys.

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 があるときは定義されません。

## Dynamic allocation

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

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

  Return a value which is the same state as a value initialized with `Py_tss_NEEDS_INIT`, or `NULL` in the case of dynamic allocation failure.

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

  Free the given key allocated by `PyThread_tss_alloc()`, after first calling `PyThread_tss_delete()` to ensure any associated thread locals have been unassigned. This is a no-op if the key argument is `NULL`.

  注釈

  A freed key becomes a dangling pointer. You should reset the key to `NULL`.

## メソッド

The parameter key of these functions must not be `NULL`. Moreover, the behaviors of `PyThread_tss_set()` and `PyThread_tss_get()` are undefined if the given `Py_tss_t` has not been initialized by `PyThread_tss_create()`.

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

  Return a non-zero value if the given `Py_tss_t` has been initialized by `PyThread_tss_create()`.

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

  Return a zero value on successful initialization of a TSS key. The behavior is undefined if the value pointed to by the key argument is not initialized by `Py_tss_NEEDS_INIT`. This function can be called repeatedly on the same key -- calling it on an already initialized key is a no-op and immediately returns success.

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

  Destroy a TSS key to forget the values associated with the key across all threads, and change the key's initialization state to uninitialized. A destroyed key is able to be initialized again by `PyThread_tss_create()`. This function can be called repeatedly on the same key -- calling it on an already destroyed key is a no-op.

int PyThread_tss_set(Py_tss_t *key, void *value)
  次に属します: Stable ABI (バージョン 3.7 より).

  Return a zero value to indicate successfully associating a void* value with a TSS key in the current thread. Each thread has a distinct mapping of the key to a void* value.

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

  Return the void* value associated with a TSS key in the current thread. This returns `NULL` if no value is associated with the key in the current thread.

## Legacy APIs

バージョン 3.7 で非推奨: This API is superseded by the thread-specific storage (TSS) API.

注釈

This version of the API does not support platforms where the native TLS key is defined in a way that cannot be safely cast to `int`. On such platforms, `PyThread_create_key()` will return immediately with a failure status, and the other TLS functions will all be no-ops on such platforms.

前述の互換性の問題により、このバージョンの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.