スレッド状態とグローバルインタープリタロック

CPython の フリースレッドビルド を除き、Python インタープリタは一般にスレッドセーフではありません。 マルチスレッドの Python プログラムをサポートするため、グローバルインタープリタロック、または GIL というグローバルなロックがあります。 スレッドは Python オブジェクトにアクセスする前に、このロックを保持していなければなりません。 ロックがなければ、マルチスレッドのプログラムでは単純な操作でも問題が起こりえます。 例えば、2 つのスレッドが同じオブジェクトの参照カウントを同時に増やすと、2 回ではなく 1 回しか増えない可能性があります。

このため、Python オブジェクトの操作や Python の C API の呼び出しを行えるのは、GIL を保持するスレッドだけです。

並行実行を模倣するため、インタープリタはバイトコード命令の間で定期的にスレッドの切り替えを試みます (sys.setswitchinterval() を参照)。 そのため、純粋な Python コードでもスレッドセーフにするにはロックが必要です。

また、ファイルの読み書きなどのブロッキング I/O 操作の間は、グローバルインタープリタロックが解放されます。 C API では スレッド状態をデタッチする ことで行います。

Python インタープリタは、スレッド状態 と呼ばれる PyThreadState データ構造に、スレッドごとの情報を保持します。 各スレッドには PyThreadState へのスレッドローカルなポインターがあります。 このポインターが参照するスレッド状態は、アタッチされている と見なされます。

1 つのスレッドが同時に持てる アタッチされたスレッド状態 は 1 つだけです。 フリースレッドビルドを除けば、スレッド状態がアタッチされていることは通常、GIL を保持していることに相当します。 GIL が有効なビルドでは、スレッド状態のアタッチは GIL を取得できるまでブロックします。 ただし、GIL が無効なビルドでも、スレッド状態をアタッチしておく必要があります。 インタープリタが、どのスレッドが Python オブジェクトにアクセスしうるかを把握するためです。

注釈

フリースレッドビルドでも、スレッド状態のアタッチがブロックすることがあります。 GIL が再び有効になる場合や、ガベージコレクション中などにスレッドが一時停止する場合があるためです。

一般に、Python の C API を使うときは、組み込みやメソッドの実装を含め、常にスレッド状態がアタッチされています。 そのため、自分でスレッド状態を用意する必要はほとんどありません。 スレッド状態がアタッチされていないのは、Py_BEGIN_ALLOW_THREADS ブロック内や新しく作られたスレッドなど、特定の場合だけです。 不確かな場合は、PyThreadState_GetUnchecked() が NULL を返すかどうかを確認してください。

If it turns out that you do need to create a thread state, call PyThreadState_New() followed by PyThreadState_Swap(), or use the dangerous PyGILState_Ensure() function.

拡張コードからのスレッド状態のデタッチ

スレッド状態 を操作する拡張コードの多くは、次の単純な構造を取ります。

// スレッド状態をローカル変数に保存する。
// ... ブロッキング I/O 操作を行う ...
// ローカル変数からスレッド状態を復元する。

この構造は非常に一般的なので、作業を単純にするために2つのマクロが用意されています:

Py_BEGIN_ALLOW_THREADS
... ブロッキング I/O 操作を行う ...
Py_END_ALLOW_THREADS

Py_BEGIN_ALLOW_THREADS マクロは新たなブロックを開始し、隠しローカル変数を宣言します; Py_END_ALLOW_THREADS はブロックを閉じます。

上のブロックは次のコードに展開されます:

PyThreadState *_save;

_save = PyEval_SaveThread();
... ブロッキング I/O 操作を行う ...
PyEval_RestoreThread(_save);

これらの関数は次のように動作します。

スレッド状態がアタッチされているということは、そのインタープリタの GIL を保持しているということです。 デタッチするには PyEval_SaveThread() を呼び出し、結果をローカル変数に保存します。

スレッド状態をデタッチすると GIL が解放され、現在のスレッドがブロッキング I/O を行っている間に、ほかのスレッドがインタープリタにアタッチして実行できるようになります。 I/O 操作が完了したら、PyEval_RestoreThread() を呼び出して元のスレッド状態を再びアタッチします。 この呼び出しは GIL を取得できるまで待機します。

注釈

スレッド状態をデタッチする最も一般的な用途はブロッキング I/O ですが、Python オブジェクトや Python の C API にアクセスしない、実行時間の長いネイティブコードでも有用です。 例えば、標準モジュールの zlib と hashlib は、データの圧縮やハッシュ計算中に スレッド状態 をデタッチします。

フリースレッドビルド では通常 GIL を考慮する必要はありませんが、スレッド状態のデタッチは依然として必要です。 インタープリタは、競合状態の危険なく Python オブジェクトの整合した状態を把握するため、定期的にすべてのスレッドをブロックする必要があるためです。 例えば、現在の CPython はガベージコレクターの実行中、すべてのスレッドを短時間停止します。

警告

スレッド状態のデタッチは、インタープリタの終了処理中に予期しない動作を引き起こす可能性があります。 詳しくは Cautions regarding runtime finalization を参照してください。

API

以下のマクロは、通常末尾にセミコロンを付けずに使います; Python ソース配布物内の使用例を見てください。

注釈

これらのマクロは、デッドロックを防ぐために フリースレッドビルド でも必要です。

Py_BEGIN_ALLOW_THREADS

This macro is available when compiling for the Stable ABI.

このマクロを展開すると { PyThreadState *_save; _save = PyEval_SaveThread(); になります。マクロに開き波括弧が入っていることに注意してください; この波括弧は後で Py_END_ALLOW_THREADS マクロと対応させなければなりません。マクロについての詳しい議論は上記を参照してください。

Py_END_ALLOW_THREADS

This macro is available when compiling for the Stable ABI.

このマクロを展開すると PyEval_RestoreThread(_save); } になります。 閉じ波括弧を含むため、事前の Py_BEGIN_ALLOW_THREADS マクロと対応させなければなりません。 このマクロについては上の説明を参照してください。

Py_BLOCK_THREADS

This macro is available when compiling for the Stable ABI.

このマクロを展開すると PyEval_RestoreThread(_save); になります: 閉じ波括弧のない Py_END_ALLOW_THREADS と同じです。

Py_UNBLOCK_THREADS

This macro is available when compiling for the Stable ABI.

このマクロを展開すると _save = PyEval_SaveThread(); になります: 開き波括弧のない Py_BEGIN_ALLOW_THREADS と同じです。

Non-Python created threads

threading モジュールなどの Python の専用 API でスレッドを作成すると、スレッド状態が自動的に関連付けられます。 一方、独自のスレッド管理を行うサードパーティーライブラリなど、ネイティブコードで作成されたスレッドには、アタッチされたスレッド状態がありません。

このようなスレッドから Python コードを呼び出す必要がある場合は、まずスレッド状態を新しく作成してアタッチし、スレッドをインタープリタに登録しなければなりません。 このような呼び出しは、前述のサードパーティーライブラリが提供するコールバック API の一部として行われることがよくあります。

The most robust way to do this is through PyThreadState_New() followed by PyThreadState_Swap().

注釈

PyThreadState_New requires an argument pointing to the desired interpreter; such a pointer can be acquired via a call to PyInterpreterState_Get() from the code where the thread was created.

例えば:

/* The return value of PyInterpreterState_Get() from the
   function that created this thread. */
PyInterpreterState *interp = thread_data->interp;

/* Create a new thread state for the interpreter. It does not start out
   attached. */
PyThreadState *tstate = PyThreadState_New(interp);

/* Attach the thread state, which will acquire the GIL. */
PyThreadState_Swap(tstate);

/* Perform Python actions here. */
result = CallSomeFunction();
/* evaluate result or handle exception */

/* Destroy the thread state. No Python API allowed beyond this point. */
PyThreadState_Clear(tstate);
PyThreadState_DeleteCurrent();

警告

If the interpreter finalized before PyThreadState_Swap was called, then interp will be a dangling pointer!

Legacy API

Another common pattern to call Python code from a non-Python thread is to use PyGILState_Ensure() followed by a call to PyGILState_Release().

These functions do not work well when multiple interpreters exist in the Python process. If no Python interpreter has ever been used in the current thread (which is common for threads created outside Python), PyGILState_Ensure will create and attach a thread state for the "main" interpreter (the first interpreter in the Python process).

Additionally, these functions have thread-safety issues during interpreter finalization. Using PyGILState_Ensure during finalization will likely crash the process.

Usage of these functions look like such:

PyGILState_STATE gstate;
gstate = PyGILState_Ensure();

/* Perform Python actions here. */
result = CallSomeFunction();
/* evaluate result or handle exception */

/* Release the thread. No Python API allowed beyond this point. */
PyGILState_Release(gstate);

fork() に関する注意

スレッドに関するもう 1 つの重要な注意点は、C の fork() 呼び出し時の動作です。 fork() を備えるほとんどのシステムでは、プロセスを fork した後には、fork を呼び出したスレッドだけが存在します。 これは、ロックの扱い方と CPython ランタイムに保存されたすべての状態の両方に、具体的な影響を及ぼします。

「現在の」スレッドだけが残るため、ほかのスレッドが保持していたロックは解放されなくなります。 Python は os.fork() で、内部で使うロックを fork の前に取得し、後で解放することで対処します。 さらに、子プロセスの Lock オブジェクト をすべてリセットします。 Python の拡張や組み込みでは、fork 前の取得や fork 後のリセットが必要な、Python 以外の追加のロックを Python に知らせる方法はありません。 同じ処理を行うには、pthread_atfork() などの OS の機能を使う必要があります。 また、Python の拡張や組み込みで os.fork() を経由せずに fork() を直接呼び出し、その後 Python に戻るか Python を呼び出すと、デッドロックが起こる可能性があります。 Python 内部のロックを保持していたスレッドが、fork 後には存在しなくなるためです。 PyOS_AfterFork_Child() は必要なロックのリセットを試みますが、常にできるとは限りません。

ほかのスレッドがすべて消えるため、それらに対応する CPython ランタイムの状態も適切に後始末する必要があります。 os.fork() はこの処理を行います。 具体的には、現在のインタープリタに属するほかのすべての PyThreadState オブジェクトと、ほかのすべての PyInterpreterState オブジェクトの終了処理を行います。 このことと メインインタープリタ の特殊な性質のため、fork() は、CPython のグローバルなランタイムを最初に初期化した、そのインタープリタの「メイン」スレッドでのみ呼び出すべきです。 直後に exec() を呼び出す場合だけは例外です。

高水準 API

マルチスレッドの C 拡張を書くときに最もよく使われる型と関数です。

type PyThreadState

次に属します: Limited API (不透明な構造体として).

このデータ構造は、1 つのスレッドの状態を表します。 公開されているデータメンバーは次のものだけです。

PyInterpreterState *interp

このスレッドのインタープリタ状態。

void PyEval_InitThreads()

次に属します: Stable ABI.

何も行わない非推奨の関数です。

Python 3.6 以前では、GIL が存在しなければ作成していました。

バージョン 3.9 で変更: この関数は何も行わなくなりました。

バージョン 3.7 で変更: この関数は Py_Initialize() から呼び出されるようになり、わざわざ呼び出す必要はもう無くなりました。

バージョン 3.2 で変更: この関数は Py_Initialize() より前に呼び出すことができなくなりました。

バージョン 3.9 で非推奨.

PyThreadState *PyEval_SaveThread()

次に属します: Stable ABI.

アタッチされたスレッド状態 をデタッチして返します。 戻るときには、スレッドに スレッド状態 はアタッチされていません。

void PyEval_RestoreThread(PyThreadState *tstate)

次に属します: Stable ABI.

アタッチされたスレッド状態 を tstate に設定します。 渡す スレッド状態 は アタッチされていてはなりません。 アタッチ済みの場合はデッドロックします。 戻るときには tstate がアタッチされています。

注釈

ランタイムの終了処理中にスレッドからこの関数を呼び出すと、そのスレッドはプログラムが終了するまで停止したままになります。 これは Python で作成したスレッドでなくても同じです。 詳しくは Cautions regarding runtime finalization を参照してください。

バージョン 3.14 で変更: インタープリタの終了処理中に呼び出された場合、現在のスレッドを終了させる代わりに、停止したままにするようになりました。

PyThreadState *PyThreadState_Get()

次に属します: Stable ABI.

アタッチされたスレッド状態 を返します。 Py_BEGIN_ALLOW_THREADS ブロック内など、スレッド状態がアタッチされていない場合は致命的エラーを発生させます (そのため、呼び出し元は NULL かどうかを調べる必要がありません)。

PyThreadState_GetUnchecked() も参照してください。

PyThreadState *PyThreadState_GetUnchecked()

PyThreadState_Get() と同様ですが、スレッド状態が NULL でも致命的エラーでプロセスを終了させません。 結果が NULL かどうかは、呼び出し元が調べる必要があります。

Added in version 3.13: Python 3.5 から 3.12 では、この関数は非公開で、_PyThreadState_UncheckedGet() という名前でした。

PyThreadState *PyThreadState_Swap(PyThreadState *tstate)

次に属します: Stable ABI.

アタッチされたスレッド状態 を tstate に設定し、呼び出し前にアタッチされていた スレッド状態 を返します。

アタッチされたスレッド状態 がなくても安全に呼び出せます。 その場合は、以前のスレッド状態がなかったことを示す NULL を返すだけです。

参考

PyEval_ReleaseThread()

注釈

PyGILState_Ensure() と同様に、ランタイムの終了処理中にはスレッドが停止したままになります。

GIL 状態の API

The following functions use thread-local storage, and are not compatible with sub-interpreters:

type PyGILState_STATE

次に属します: Stable ABI.

PyGILState_Ensure() が返し、PyGILState_Release() に渡す値の型です。

enumerator PyGILState_LOCKED

PyGILState_Ensure() が呼び出された時点で、すでに GIL を保持していました。

enumerator PyGILState_UNLOCKED

PyGILState_Ensure() が呼び出された時点では、GIL を保持していませんでした。

PyGILState_STATE PyGILState_Ensure()

次に属します: Stable ABI.

Python や アタッチされたスレッド状態 の現在の状態にかかわらず、現在のスレッドで Python C API を呼び出せるようにします。 各呼び出しに対応する PyGILState_Release() を呼び出す限り、スレッドは何度でもこの関数を呼び出せます。 一般に、PyGILState_Ensure() と PyGILState_Release() の間では、Release() の前にスレッド状態を元に戻す限り、ほかのスレッド関連の API を使っても構いません。 例えば、Py_BEGIN_ALLOW_THREADS と Py_END_ALLOW_THREADS マクロは通常どおり使えます。

戻り値は、PyGILState_Ensure() を呼び出したときの アタッチされたスレッド状態 を表す不透明な「ハンドル」です。 Python を同じ状態に戻すため、PyGILState_Release() に渡さなければなりません。 再帰的な呼び出しは許可されていますが、ハンドルを共有することは できません。 PyGILState_Ensure() の呼び出しごとにハンドルを保存し、その呼び出しに対応する PyGILState_Release() に渡す必要があります。

When the function returns, there will be an attached thread state and the thread will be able to call arbitrary Python code. Failure is a fatal error.

警告

Calling this function when the runtime is finalizing is unsafe. Doing so will either hang the thread until the program ends, or fully crash the interpreter in rare cases. Refer to Cautions regarding runtime finalization for more details.

バージョン 3.14 で変更: インタープリタの終了処理中に呼び出された場合、現在のスレッドを終了させる代わりに、停止したままにするようになりました。

void PyGILState_Release(PyGILState_STATE)

次に属します: Stable ABI.

Release any resources previously acquired. After this call, Python's state will be the same as it was prior to the corresponding PyGILState_Ensure() call (but generally this state will be unknown to the caller, hence the use of the GILState API).

PyGILState_Ensure() を呼び出す場合は、必ず同一スレッド内で対応する PyGILState_Release() を呼び出してください。

PyThreadState *PyGILState_GetThisThreadState()

次に属します: Stable ABI.

Get the attached thread state for this thread. May return NULL if no GILState API has been used on the current thread. Note that the main thread always has such a thread-state, even if no auto-thread-state call has been made on the main thread. This is mainly a helper/diagnostic function.

注釈

This function may return non-NULL even when the thread state is detached. Prefer PyThreadState_Get() or PyThreadState_GetUnchecked() for most cases.

参考

PyThreadState_Get()

int PyGILState_Check()

Return 1 if the current thread is holding the GIL and 0 otherwise. This function can be called from any thread at any time. Only if it has had its thread state initialized via PyGILState_Ensure() will it return 1. This is mainly a helper/diagnostic function. It can be useful for example in callback contexts or memory allocation functions when knowing that the GIL is locked can allow the caller to perform sensitive actions or otherwise behave differently.

注釈

If the current Python process has ever created a subinterpreter, this function will always return 1. Prefer PyThreadState_GetUnchecked() for most cases.

Added in version 3.4.

低水準 API

PyThreadState *PyThreadState_New(PyInterpreterState *interp)

次に属します: Stable ABI.

指定されたインタープリタオブジェクトに属するスレッド状態オブジェクトを新しく作成します。 アタッチされたスレッド状態 は必要ありません。

void PyThreadState_Clear(PyThreadState *tstate)

次に属します: Stable ABI.

スレッド状態 オブジェクトのすべての情報をリセットします。 tstate は アタッチされていなければなりません。

バージョン 3.9 で変更: この関数が PyThreadState.on_delete コールバックを呼び出すようになりました。 以前は PyThreadState_Delete() で呼び出していました。

バージョン 3.13 で変更: PyThreadState.on_delete コールバックが削除されました。

void PyThreadState_Delete(PyThreadState *tstate)

次に属します: Stable ABI.

スレッド状態 オブジェクトを破棄します。 tstate はどのスレッドにも アタッチされていてはなりません。 事前に PyThreadState_Clear() を呼び出して tstate をリセットしておく必要があります。

void PyThreadState_DeleteCurrent(void)

アタッチされたスレッド状態 をデタッチし、破棄します。 このスレッド状態は、事前に PyThreadState_Clear() を呼び出してリセットしておく必要があります。

戻るときには、アタッチされた スレッド状態 はありません。

PyFrameObject *PyThreadState_GetFrame(PyThreadState *tstate)

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

Python のスレッド状態 tstate の現在のフレームを取得します。

強参照 を返します。 現在実行中のフレームがなければ NULL を返します。

PyEval_GetFrame() も参照してください。

tstate は NULL であってはならず、アタッチされていなければなりません。

Added in version 3.9.

uint64_t PyThreadState_GetID(PyThreadState *tstate)

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

Python のスレッド状態 tstate の、一意な スレッド状態 識別子を取得します。

tstate は NULL であってはならず、アタッチされていなければなりません。

Added in version 3.9.

PyInterpreterState *PyThreadState_GetInterpreter(PyThreadState *tstate)

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

Python のスレッド状態 tstate のインタープリタを取得します。

tstate は NULL であってはならず、アタッチされていなければなりません。

Added in version 3.9.

void PyThreadState_EnterTracing(PyThreadState *tstate)

Python のスレッド状態 tstate でのトレースとプロファイリングを一時停止します。

再開するには PyThreadState_LeaveTracing() を使います。

Added in version 3.11.

void PyThreadState_LeaveTracing(PyThreadState *tstate)

PyThreadState_EnterTracing() によって一時停止した、Python のスレッド状態 tstate でのトレースとプロファイリングを再開します。

PyEval_SetTrace() と PyEval_SetProfile() も参照してください。

Added in version 3.11.

int PyUnstable_ThreadState_SetStackProtection(PyThreadState *tstate, void *stack_start_addr, size_t stack_size)

これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。

Python のスレッド状態の、スタック保護の開始アドレスとサイズを設定します。

成功時は 0 を返します。 失敗時は例外を設定して -1 を返します。

CPython は、マシンの実行スタックがオーバーフローに近づいていることを検出すると RecursionError を送出することで、C コードの 再帰を制御 します。 例えば Py_EnterRecursiveCall() を参照してください。 このため、現在のスレッドのスタックの位置を知る必要があり、通常は OS から取得します。 Boost ライブラリの boost::context のようなコンテキスト切り替え技法でスタックを変更する場合は、PyUnstable_ThreadState_SetStackProtection() を呼び出して CPython に変更を知らせなければなりません。

PyUnstable_ThreadState_SetStackProtection() は、スタックを変更する前か後に呼び出してください。 この呼び出しとスタックの変更の間に、ほかの Python C API を呼び出さないでください。

この操作を元に戻すには PyUnstable_ThreadState_ResetStackProtection() を参照してください。

Added in version 3.15.

void PyUnstable_ThreadState_ResetStackProtection(PyThreadState *tstate)

これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。

Python のスレッド状態の、スタック保護の開始アドレスとサイズを OS のデフォルト値に戻します。

説明は PyUnstable_ThreadState_SetStackProtection() を参照してください。

Added in version 3.15.

PyObject *PyThreadState_GetDict()

戻り値: 借用参照。 次に属します: Stable ABI.

拡張がスレッド固有の状態情報を保存するための辞書を返します。 各拡張は、一意なキーを使って辞書に状態を保存するべきです。 スレッド状態 が アタッチされていない 場合も呼び出せます。 NULL が返った場合、例外は送出されておらず、呼び出し元はスレッド状態がアタッチされていないと判断するべきです。

void PyEval_AcquireThread(PyThreadState *tstate)

次に属します: Stable ABI.

tstate を現在のスレッドに アタッチ します。 tstate は NULL であってはならず、すでに アタッチされていてもなりません。

呼び出し元のスレッドに、すでに アタッチされたスレッド状態 があってはなりません。

注釈

ランタイムの終了処理中にスレッドからこの関数を呼び出すと、そのスレッドはプログラムが終了するまで停止したままになります。 これは Python で作成したスレッドでなくても同じです。 詳しくは Cautions regarding runtime finalization を参照してください。

バージョン 3.8 で変更: PyEval_RestoreThread()、Py_END_ALLOW_THREADS()、PyGILState_Ensure() と動作を揃え、インタープリタの終了処理中に呼び出された場合は、現在のスレッドを終了させるようになりました。

バージョン 3.14 で変更: インタープリタの終了処理中に呼び出された場合、現在のスレッドを終了させる代わりに、停止したままにするようになりました。

PyEval_RestoreThread() はいつでも (スレッドが初期化されたいないときでも) 利用可能な高レベル関数です。

void PyEval_ReleaseThread(PyThreadState *tstate)

次に属します: Stable ABI.

アタッチされたスレッド状態 をデタッチします。 tstate 引数は NULL であってはならず、アタッチされたスレッド状態 を表しているかどうかの確認にのみ使われます。 一致しなければ致命的エラーを報告します。

PyEval_SaveThread() はより高レベルな関数で常に (スレッドが初期化されていないときでも) 利用できます。

非同期通知

インタプリタのメインスレッドに非同期な通知を行うために提供されている仕組みです。これらの通知は関数ポインタと void ポインタ引数という形態を取ります。

int Py_AddPendingCall(int (*func)(void*), void *arg)

次に属します: Stable ABI.

インタプリタのメインスレッドから関数が呼び出される予定を組みます。成功すると 0 が返り、func はメインスレッドの呼び出しキューに詰められます。失敗すると、例外をセットせずに -1 が返ります。

無事にキューに詰められると、func は いつかは必ず インタプリタのメインスレッドから、arg を引数として呼び出されます。この関数は、通常の実行中の Python コードに対して非同期に呼び出されますが、次の両方の条件に合致したときに呼び出されます:

• bytecode 境界上にいるとき、

• メインスレッドに スレッド状態がアタッチされている こと (したがって func はすべての C API を使えます)。

func は成功時に 0 を返し、失敗時には例外を設定して -1 を返さなければなりません。 別の非同期通知を再帰的に処理するために func が中断されることはありませんが、スレッド状態 がデタッチされると、スレッドの切り替えのために中断されることはあります。

This function doesn't need an attached thread state. However, to call this function in a subinterpreter, the caller must have an attached thread state. Otherwise, the function func can be scheduled to be called from the wrong interpreter.

警告

This is a low-level function, only useful for very special cases. There is no guarantee that func will be called as quick as possible. If the main thread is busy executing a system call, func won't be called before the system call returns. This function is generally not suitable for calling Python code from arbitrary C threads. Instead, use the PyGILState API.

Added in version 3.1.

バージョン 3.9 で変更: サブインタープリタでこの関数を呼び出すと、func はメインインタープリタではなく、そのサブインタープリタで呼び出されるようになりました。 サブインタープリタごとに、呼び出しを予定した関数のリストを持つようになりました。

バージョン 3.12 で変更: func は常にメインインタープリタで実行されるようになりました。

int Py_MakePendingCalls(void)

次に属します: Stable ABI.

保留中の呼び出しをすべて実行します。 通常、インタープリタが自動的に実行します。

成功時は 0 を返し、失敗時は例外を設定して -1 を返します。

メインインタープリタのメインスレッドで呼び出されなければ、何もせず 0 を返します。 呼び出し元には スレッド状態がアタッチされていなければなりません。

Added in version 3.1.

バージョン 3.12 で変更: メインインタープリタの保留中の呼び出しだけを実行するようになりました。

int PyThreadState_SetAsyncExc(unsigned long id, PyObject *exc)

次に属します: Stable ABI.

Asynchronously raise an exception in a thread. The id argument is the thread id of the target thread; exc is the exception object to be raised. This function does not steal any references to exc. To prevent naive misuse, you must write your own C extension to call this. Must be called with an attached thread state. Returns the number of thread states modified; this is normally one, but will be zero if the thread id isn't found. If exc is NULL, the pending exception (if any) for the thread is cleared. This raises no exceptions.

バージョン 3.7 で変更: id 引数の型が long から unsigned long へ変更されました。

OS スレッドの API

PYTHREAD_INVALID_THREAD_ID

無効なスレッド ID を表す番兵値。

現在は (unsigned long)-1 と等価です。

unsigned long PyThread_start_new_thread(void (*func)(void*), void *arg)

次に属します: Stable ABI.

新しいスレッドで関数 func を引数 arg とともに開始します。 作成したスレッドは join することを想定していません。

func は NULL であってはなりませんが、arg は NULL でも構いません。

成功時は新しいスレッドの識別子を返し、失敗時は PYTHREAD_INVALID_THREAD_ID を返します。

呼び出し元に スレッド状態がアタッチされている 必要はありません。

unsigned long PyThread_get_thread_ident(void)

次に属します: Stable ABI.

現在のスレッドの識別子を返します。 ゼロになることはありません。

この関数は失敗せず、呼び出し元に スレッド状態がアタッチされている 必要もありません。

参考

threading.get_ident()

PyObject *PyThread_GetInfo(void)

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

Get general information about the current thread in the form of a struct sequence object. This information is accessible as sys.thread_info in Python.

成功時はスレッド情報への新しい 強参照 を返します。 失敗時は例外を設定して NULL を返します。

呼び出し元には スレッド状態がアタッチされていなければなりません。

PY_HAVE_THREAD_NATIVE_ID

システムがネイティブスレッド ID をサポートしている場合に定義されるマクロです。

unsigned long PyThread_get_thread_native_id(void)

次に属します: Stable ABI on platforms with native thread IDs.

OS のカーネルが割り当てた、現在のスレッドのネイティブ識別子を取得します。 ゼロ未満になることはありません。

PY_HAVE_THREAD_NATIVE_ID が定義されている場合にのみ利用できます。

この関数は失敗せず、呼び出し元に スレッド状態がアタッチされている 必要もありません。

参考

threading.get_native_id()

void PyThread_exit_thread(void)

次に属します: Stable ABI.

現在のスレッドを終了させます。 一般に安全ではないとされており、使用を避けるべきです。 後方互換性のためだけに残されています。

呼び出しスタックにあるすべての関数が、この呼び出しを安全に許容できるように書かれている場合にのみ、安全に呼び出せます。

警告

POSIX スレッド (pthreads とも呼ばれます) を使うシステムでは、pthread_exit(3) を呼び出します。 一部の libc 実装では、この関数はスタックを巻き戻して C++ のデストラクターを呼び出そうとします。 ただし、noexcept 関数に到達すると、プロセスを終了させる可能性があります。 macOS など、ほかのシステムでは巻き戻しが行われます。

Windows では _endthreadex() を呼び出し、C++ のデストラクターを呼び出さずにスレッドを終了させます。

どの場合も、スレッドのスタックが破損する危険があります。

バージョン 3.14 で非推奨.

void PyThread_init_thread(void)

次に属します: Stable ABI.

PyThread* API を初期化します。 Python が自動的に実行するため、拡張モジュールから呼び出す必要はほとんどありません。

int PyThread_set_stacksize(size_t size)

次に属します: Stable ABI.

Set the stack size of the current thread to size bytes.

成功時は 0、size が無効な場合は -1、システムがスタックサイズの変更に対応していない場合は -2 を返します。 例外は設定しません。

呼び出し元に スレッド状態がアタッチされている 必要はありません。

size_t PyThread_get_stacksize(void)

次に属します: Stable ABI.

Return the stack size of the current thread in bytes, or 0 if the system's default stack size is in use.

呼び出し元に スレッド状態がアタッチされている 必要はありません。