_thread --- 低水準なスレッド API

---

このモジュールはマルチスレッド (別名 軽量プロセス (light-weight processes)または タスク (tasks)) に用いられる低水準プリミティブを提供します --- グローバルデータ空間を共有するマルチスレッドを制御します。同期のための単純なロック (別名 mutexes またはバイナリセマフォ (binary semaphores))が提供されています。 threading モジュールは、このモジュール上で、より使い易く高級なスレッディングの API を提供します。

バージョン 3.7 で変更: このモジュールは以前はオプションでしたが、常に利用可能なモジュールとなりました。

このモジュールでは以下の定数および関数を定義しています:

exception _thread.error

スレッド固有の例外です。

バージョン 3.3 で変更: 現在は組み込みの RuntimeError の別名です。

_thread.start_new_thread(function, args[, kwargs])

新しいスレッドを開始して、そのIDを返します。スレッドは引数リスト args (タプルでなければなりません)の関数 function を実行します。オプション引数 kwargs はキーワード引数の辞書を指定します。

関数が戻るとき、スレッドは静かに終了します。

処理されない例外によって関数が終了すると、例外を処理するために sys.unraisablehook() が呼び出されます。 フックに渡される引数の object 属性は function です。 デフォルトではスタックトレースを表示してスレッドを終了します (他のスレッドは実行を続けます)。

関数が SystemExit 例外を送出した場合は、何も表示せずに無視します。

引数 function、args、kwargs を指定して、監査イベント _thread.start_new_thread を発生させます。

バージョン 3.8 で変更: 処理されない例外を扱うために sys.unraisablehook() を使うようになりました。

_thread.interrupt_main(signum=signal.SIGINT, /)

メインスレッドにシグナルが届いたときの効果を模倣します。 スレッドはこの関数でメインスレッドに割り込めますが、即座に割り込む保証はありません。

signum を指定した場合は、模倣するシグナルの番号になります。 signum を指定しない場合は、signal.SIGINT を模倣します。

指定したシグナルを Python が処理しない場合 (signal.SIG_DFL または signal.SIG_IGN に設定されている場合)、この関数は何もしません。

バージョン 3.10 で変更: シグナル番号を変更できるよう、signum 引数が追加されました。

注釈

この関数は実際にシグナルを発生させるのではなく、対応するハンドラーがあれば、その呼び出しを予約します。 実際にシグナルを発生させるには signal.raise_signal() を使ってください。

_thread.exit()

SystemExit を送出します。それが捕えられないときは、静かにスレッドを終了させます。

_thread.allocate_lock()

新しいロックオブジェクトを返します。ロックのメソッドはこの後に記述されます。ロックは初期状態としてアンロック状態です。

_thread.get_ident()

現在のスレッドの 'スレッドID' を返します。非ゼロの整数です。この値は直接の意味を持っていません; 例えばスレッド特有のデータの辞書に索引をつけるためのような、マジッククッキーとして意図されています。スレッドが終了し、他のスレッドが作られたとき、スレッド ID は再利用されるかもしれません。

_thread.get_native_id()

カーネルが割り当てた、現在のスレッドのネイティブなスレッド ID を整数で返します。 これは非負の整数です。 この値を使って、システム全体でそのスレッドを一意に識別できます (スレッドが終了するまで有効で、その後は OS が値を再利用する場合があります)。

利用可能な環境: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD, GNU/kFreeBSD, Solaris.

Added in version 3.8.

バージョン 3.13 で変更: GNU/kFreeBSD のサポートが追加されました。

バージョン 3.15 で変更: Solaris のサポートが追加されました。

_thread.stack_size([size])

新しいスレッドを作るときのスレッドスタックサイズを返します。オプションの size 引数にはこれ以降に作成するスレッドのスタックサイズを指定し、0 (プラットフォームのデフォルト値または設定されたデフォルト値) か、 32,768 (32 KiB) 以上の正の整数でなければなりません。size が指定されない場合 0 が使われます。スレッドのスタックサイズの変更がサポートされていない場合、 RuntimeError を送出します。不正なスタックサイズが指定された場合、 ValueError を送出して、スタックサイズは変更されません。32 KiB は現在のインタープリタ自身のために十分であると保証された最小のスタックサイズです。いくつかのプラットフォームではスタックサイズに対して制限があることに注意してください。例えば最小のスタックサイズが 32 KiB より大きかったり、システムのメモリページサイズ の整数倍の必要があるなどです。この制限についてはプラットフォームのドキュメントを参照してください (一般的なページサイズは 4 KiB なので、プラットフォームに関する情報がない場合は 4096 の整数倍のスタックサイズを選ぶといいかもしれません)。

利用可能な環境: Windows, pthreads.

POSIX スレッドをサポートする Unix プラットフォーム。

_thread.TIMEOUT_MAX

Lock.acquire の timeout パラメーターに指定できる最大値です。 この値を超えるタイムアウトを指定すると OverflowError が送出されます。

Added in version 3.2.

class _thread.LockType

これはロックオブジェクトのタイプです。

ロックオブジェクトは次のようなメソッドを持っています:

acquire(blocking=True, timeout=-1)

オプションの引数なしで使用すると、このメソッドは他のスレッドがロックしているかどうかにかかわらずロックを獲得します。ただし、他のスレッドがすでにロックしている場合には解除されるまで待ってからロックを獲得します (同時にロックを獲得できるスレッドはひとつだけであり、これこそがロックの存在理由です)。

blocking 引数を指定した場合、動作はその値によって変わります。 偽なら、待たずにすぐ獲得できる場合だけロックを獲得します。 真なら、上で説明したように無条件にロックを獲得します。

If the floating-point timeout argument is present and positive, it specifies the maximum wait time in seconds before returning. A negative timeout argument specifies an unbounded wait. You cannot specify a timeout if blocking is false.

なお、ロックを獲得できた場合は True、できなかった場合は False を返します。

バージョン 3.2 で変更: 新しい timeout 引数。

バージョン 3.2 で変更: POSIX ではロックの取得がシグナルに割り込まれるようになりました。

バージョン 3.14 で変更: Windows でのロックの獲得をシグナルで中断できるようになりました。

release()

ロックを解放します。そのロックは既に獲得されたものでなければなりませんが、しかし同じスレッドによって獲得されたものである必要はありません。

locked()

ロックの状態を返します。 いずれかのスレッドがロックを獲得していれば True、そうでなければ False を返します。

これらのメソッドに加えて、ロックオブジェクトは with 文を通じて以下の例のように使うこともできます。

import _thread

a_lock = _thread.allocate_lock()

with a_lock:
    print("a_lock is locked while this executes")

警告:

• 割り込みは常にメインスレッドに届きます (KeyboardInterrupt 例外を受け取るのはこのスレッドです)。

• sys.exit() を呼び出す、あるいは SystemExit 例外を送出することは、 _thread.exit() を呼び出すことと同じです。

• メインスレッドが終了したとき、他のスレッドが生き残るかどうかは、システムに依存します。多くのシステムでは、 try ... finally 節や、オブジェクトデストラクタを実行せずに終了されます。