## Tcl8.6.17/Tk8.6.17 Documentation > Tcl C API > Thread

### Tcl/Tk Applications | Tcl Commands | Tk Commands | [incr Tcl] Package Commands | SQLite3 Package Commands | TDBC Package Commands | tdbc::mysql Package Commands | tdbc::odbc Package Commands | tdbc::postgres Package Commands | tdbc::sqlite3 Package Commands | Thread Package Commands | Tcl C API | Tk C API | [incr Tcl] Package C API | TDBC Package C API

  NAME
    Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize, Tcl_CreateThread, Tcl_JoinThread — Tcl 多重実行の運営 Tcl thread support
  SYNOPSIS
    #include <tcl.h>
    void
    Tcl_ConditionNotify(condPtr)
    void
    Tcl_ConditionWait(condPtr, mutexPtr, timePtr)
    void
    Tcl_ConditionFinalize(condPtr)
    Void *
    Tcl_GetThreadData(keyPtr, size)
    void
    Tcl_MutexLock(mutexPtr)
    void
    Tcl_MutexUnlock(mutexPtr)
    void
    Tcl_MutexFinalize(mutexPtr)
    int
    Tcl_CreateThread(idPtr, proc, clientData, stackSize, flags)
    int
    Tcl_JoinThread(id, result)
  引数 ARGUMENTS
    Tcl_Condition *condPtr (入力in)
    Tcl_Mutex *mutexPtr (入力in)
    const Tcl_Time *timePtr (入力in)
    Tcl_ThreadDataKey *keyPtr (入力in)
    int *size (入力in)
    Tcl_ThreadId *idPtr (出力out)
    Tcl_ThreadId id (入力in)
    Tcl_ThreadCreateProc *proc (入力in)
    ClientData clientData (入力in)
    int stackSize (入力in)
    int flags (入力in)
    int *result (出力out)
  緒論 INTRODUCTION
  説明 DESCRIPTION
  同調と通信 SYNCHRONIZATION AND COMMUNICATION
  初期化 INITIALIZATION
  SCRIPT-LEVEL ACCESS TO THREADS
  用例 EXAMPLE
  SEE ALSO
  KEYWORDS

### NAME

Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize, Tcl_CreateThread, Tcl_JoinThread — Tcl 多重実行の運営 Tcl thread support

### SYNOPSIS

#include <tcl.h>
void
Tcl_ConditionNotify(condPtr)
void
Tcl_ConditionWait(condPtr, mutexPtr, timePtr)
void
Tcl_ConditionFinalize(condPtr)
Void *
Tcl_GetThreadData(keyPtr, size)
void
Tcl_MutexLock(mutexPtr)
void
Tcl_MutexUnlock(mutexPtr)
void
Tcl_MutexFinalize(mutexPtr)
int
Tcl_CreateThread(idPtr, proc, clientData, stackSize, flags)
int
Tcl_JoinThread(id, result)

### 引数 ARGUMENTS

Tcl_Condition *condPtr (入力in)
  条件変数､相互排除同期機構の錠に結合していなければならない｡ A condition variable, which must be associated with a mutex lock.

Tcl_Mutex *mutexPtr (入力in)
  相互排除同期機構の錠 A mutex lock.

const Tcl_Time *timePtr (入力in)
  条件を待つ時間間隔の限度｡NULL なら永久に待つ｡註意すべきは､訪問値 0 秒は意味をなさない｡　 A time limit on the condition wait. NULL to wait forever. Note that a polling value of 0 seconds does not make much sense.

Tcl_ThreadDataKey *keyPtr (入力in)
  これは実行細片局所貯蔵の区域を識別する｡この鍵は静的で手続函数志向であるべきであり､それでも各実行細片はこの鍵による異なった貯蔵の区域に関連して終了する｡　 This identifies a block of thread local storage. The key should be static and process-wide, yet each thread will end up associating a different block of storage with this key.

int *size (入力in)
  実行細片局所貯蔵の区域の寸法｡データのこの量は､割当てられ､且つ､各実行細片の最初の Tcl_GetThreadData 呼出し時には零に初期化される｡　 The size of the thread local storage block. This amount of data is allocated and initialized to zero the first time each thread calls Tcl_GetThreadData.

Tcl_ThreadId *idPtr (出力out)
  参照されている貯蔵はOSにより返される新しく生成された実行細片の識別子を含むことになる｡　 The referred storage will contain the id of the newly created thread as returned by the operating system.

Tcl_ThreadId id (入力in)
  待たれている実行細片の識別子｡　 Id of the thread waited upon.

Tcl_ThreadCreateProc *proc (入力in)
  この手続きは､新しく生成された実行細片のmain() として活動することになる｡指定された clientData はその単独の引数である｡　 This procedure will act as the main() of the newly created thread. The specified clientData will be its sole argument.

ClientData clientData (入力in)
  任意の情報｡手続函数への単独の引数として渡される｡　 Arbitrary information. Passed as sole argument to the proc.

int stackSize (入力in)
  新しい実行細片に与える棚の寸法｡　 The size of the stack given to the new thread.

int flags (入力in)
  呼出し者に新しい細片の振る舞いを修正することを許容する旗印を含むビット櫛｡　 Bitmask containing flags allowing the caller to modify behavior of the new thread.

int *result (出力out)
  参照された貯蔵は実行細片の終了番号を､それを待っている処に､置く為に使用される｡　 The referred storage is used to place the exit code of the thread waited upon into it.

### 緒論 INTRODUCTION

8.1 版の配布開始から Tcl 核は安全な時分割処理になったので､Tcl 核を特別誂えすることなしに Tcl を多重時分割応用譜への組入れが許容される｡ 8.6 版の配布開始から､Tcl の多重分割の運営は無為設定になった｡Tcl の多重分割を不可能にする為には､ --disable-threads 選択肢を構成設定に含めて構成設定してから､Tcl 核の言語翻訳をしなければならない｡ Beginning with the 8.1 release, the Tcl core is thread safe, which allows you to incorporate Tcl into multithreaded applications without customizing the Tcl core. Starting with the 8.6 release, Tcl multithreading support is on by default. To disable Tcl multithreading support, you must include the --disable-threads option to configure when you configure and compile your Tcl core.

Tcl 多重分割実装の重要な制限は､Tcl 解釈実行機能が作成した分割は其の解釈実行機能内でのみ使える､ことである｡言換えると､多重分割は同じ Tcl 解釈実行機能のみ利用できる｡(しかし､単一の分割は安全に作成でき､多重の解釈実行機能を使用できる｡) An important constraint of the Tcl threads implementation is that only the thread that created a Tcl interpreter can use that interpreter. In other words, multiple threads can not access the same Tcl interpreter. (However, a single thread can safely create and use multiple interpreters.)

### 説明 DESCRIPTION

Tcl は時分割を作成する為に Tcl_CreateThread を提供する｡呼出し者は新しい時分割に与える棚の寸法を決定することができ､運営されている flags を通して動作を修正する｡ stackSize の為の値 TCL_THREAD_STACK_DEFAULT はOSにより指定された無為設定の寸法が新しい時分割の為に使われることを指し示す｡旗印の為としては現在､値 TCL_THREAD_NOFLAGS と TCL_THREAD_JOINABLE だけが定義されている｡其の最初のものは指定なしの無為設定の振舞いを起動する｡第二の値の利用は新しい時分割に joinable としての印を付ける｡その意味は､他の時分割はその様な時分割を終了或は合同する為に待つことができる｡ Tcl provides Tcl_CreateThread for creating threads. The caller can determine the size of the stack given to the new thread and modify the behavior through the supplied flags. The value TCL_THREAD_STACK_DEFAULT for the stackSize indicates that the default size as specified by the operating system is to be used for the new thread. As for the flags, currently only the values TCL_THREAD_NOFLAGS and TCL_THREAD_JOINABLE are defined. The first of them invokes the default behavior with no special settings. Using the second value marks the new thread as joinable. This means that another thread can wait for the such marked thread to exit and join it.

制限事項: ある種の UNIX 系は時分割外部函数群は時分割の棚の寸法を指定する機能を含まない｡このような系では､棚寸法の為に指定された値は無視される｡ Windows は現在の処､合同性時分割を運営していない｡従って､このOS上ではこの旗印は無視される｡ Restrictions: On some UNIX systems the pthread-library does not contain the functionality to specify the stack size of a thread. The specified value for the stack size is ignored on these systems. Windows currently does not support joinable threads. This flag value is therefore ignored on this platform.

Tcl は時分割の終了の為に Tcl_ExitThread と Tcl_FinalizeThread 機能を与え､そして選択的な超時分割終了処理を起動する｡この処理課程の更なる情報については Tcl_Exit の頁を参照されたい｡ Tcl provides the Tcl_ExitThread and Tcl_FinalizeThread functions for terminating threads and invoking optional per-thread exit handlers. See the Tcl_Exit page for more information on these procedures.

Tcl_JoinThread 機能は時分割に､その作成の間にTcl_CreateThread 経由で TCL_THREAD_JOINABLE-flag の使用を通して合同可能として印付けられた他の時分割の終了を待つことを許容する｡ The Tcl_JoinThread function is provided to allow threads to wait upon the exit of another thread, which must have been marked as joinable through usage of the TCL_THREAD_JOINABLE-flag during its creation via Tcl_CreateThread.

非合同可能の時分割又は､既に待たれている時分割の待合せは不都合の結果になる｡既に終了した合同可能な時分割の待合せは可能である､系はTcl_JoinThread への呼出しの後まで必要な情報を保つ｡これが意味する事は合同可能な時分割の為のTcl_JoinThread の呼出しをしないことは､記憶漏れ出しを引起す｡ Trying to wait for the exit of a non-joinable thread or a thread which is already waited upon will result in an error. Waiting for a joinable thread which already exited is possible, the system will retain the necessary information until after the call to Tcl_JoinThread. This means that not calling Tcl_JoinThread for a joinable thread will cause a memory leak.

Tcl_GetThreadData の呼出は時分割の内密のデータの区域へのポインタを返す｡その引数は全ての時分割に共有された鍵であり､又貯蔵の区域の寸法である｡その貯蔵は自動的に割当てられ､それぞれの時分割に最初に求められた時に零に初期化される｡貯蔵は自動的に Tcl_FinalizeThread によって再割り当てされる｡ The Tcl_GetThreadData call returns a pointer to a block of thread-private data. Its argument is a key that is shared by all threads and a size for the block of storage. The storage is automatically allocated and initialized to all zeros the first time each thread asks for it. The storage is automatically deallocated by Tcl_FinalizeThread.

#### 同調と通信 SYNCHRONIZATION AND COMMUNICATION

Tcl は多重時分割応用譜内の行事待ち行列の為の Tcl_ThreadQueueEvent と Tcl_ThreadAlert を提供する｡この手続函数の更なる情報は Notifier の取扱い説明書の頁を参照されたい｡ Tcl provides Tcl_ThreadQueueEvent and Tcl_ThreadAlert for handling event queuing in multithreaded applications. See the Notifier manual page for more information on these procedures.

相互排除同期機構は Tcl_MutexLock と Tcl_MutexUnlock を呼出して､全ての時分割の符号の断片を直列化する為に使う錠である｡もし一つの時分割片が同期機構を保有すると､他のどの Tcl_MutexLock を呼ぶ時分割片も Tcl_MutexUnlock が呼ばれる迄抑制される｡相互排除同期機構は使用した後に Tcl_MutexFinalize を呼出して壊され得る｡同じ時分割から二度の相互排除同期機構を掛けた結果は定義されていない｡あるOS上ではその結果は暗礁に乗り上げる｡ Tcl_MutexLock と Tcl_MutexUnlock と Tcl_MutexFinalize 手続函数は､時分割が不能の言語翻訳の場合､空マクロとして定義されている｡相互排除同期機構の宣言の為には TCL_DECLARE_MUTEX マクロを使うべきである｡そのマクロは､時分割が不能の言語翻訳の場合でさえも正しく相互排除同期機構を処理する事を保障する｡ A mutex is a lock that is used to serialize all threads through a piece of code by calling Tcl_MutexLock and Tcl_MutexUnlock. If one thread holds a mutex, any other thread calling Tcl_MutexLock will block until Tcl_MutexUnlock is called. A mutex can be destroyed after its use by calling Tcl_MutexFinalize. The result of locking a mutex twice from the same thread is undefined. On some platforms it will result in a deadlock. The Tcl_MutexLock, Tcl_MutexUnlock and Tcl_MutexFinalize procedures are defined as empty macros if not compiling with threads enabled. For declaration of mutexes the TCL_DECLARE_MUTEX macro should be used. This macro assures correct mutex handling even when the core is compiled without threads enabled.

条件変数は信号の仕組みとして使われる: 時分割片は相互排除同期機構に施錠することができ､そこで Tcl_ConditionWait により条件変数を待つ｡これは自動的に相互排除同期機構の錠を開錠し他の時分割片が Tcl_ConditionNotify を呼ぶ迄､待っている時分割片を抑制する｡ Tcl_ConditionNotify の呼出し側は､それ以前の Tcl_MutexLock 呼出しにより保持された相互排除同期機構の結合を有するべきであるが､強制はされない｡条件変数の通知は条件変数を待っている全ての時分割片を開錠するが､それらは Tcl_MutexUnlock によって相互排除同期機構が解放されるまで処理されない｡ Tcl_ConditionWait の実装は戻る前に相互排除同期機構を自動的に施錠する｡ A condition variable is used as a signaling mechanism: a thread can lock a mutex and then wait on a condition variable with Tcl_ConditionWait. This atomically releases the mutex lock and blocks the waiting thread until another thread calls Tcl_ConditionNotify. The caller of Tcl_ConditionNotify should have the associated mutex held by previously calling Tcl_MutexLock, but this is not enforced. Notifying the condition variable unblocks all threads waiting on the condition variable, but they do not proceed until the mutex is released with Tcl_MutexUnlock. The implementation of Tcl_ConditionWait automatically locks the mutex before returning.

Tcl_ConditionWait の呼出し側は､不変量を検査する while 繰返し[訳註 無限 while 繰返]内部での Tcl_ConditionWait 呼出しによる偽の通知の為に用意すべきである｡ The caller of Tcl_ConditionWait should be prepared for spurious notifications by calling Tcl_ConditionWait within a while loop that tests some invariant.

条件変数は使用した後､Tcl_ConditionFinalize の呼出しにより破壊される｡ A condition variable can be destroyed after its use by calling Tcl_ConditionFinalize.

Tcl_ConditionNotify と Tcl_ConditionWait と Tcl_ConditionFinalize 手続函数は､時分割不能で言語翻訳された場合､空マクロとして定義される｡ The Tcl_ConditionNotify, Tcl_ConditionWait and Tcl_ConditionFinalize procedures are defined as empty macros if not compiling with threads enabled.

#### 初期化 INITIALIZATION

これ等の同調対象の全ては自己初期化である｡それらは最初の使用では NULL になっているような不透明なポインターとして実装される｡相互排除同期機構と条件変数は共に､課程終了処理機能､或は Tcl_MutexFinalize か Tcl_ConditionFinalize.の呼出しにより一掃される｡時分割局部記憶は Tcl_FinalizeThread.の間に再宣言される｡ All of these synchronization objects are self-initializing. They are implemented as opaque pointers that should be NULL upon first use. The mutexes and condition variables are either cleaned up by process exit handlers (if living that long) or explicitly by calls to Tcl_MutexFinalize or Tcl_ConditionFinalize. Thread local storage is reclaimed during Tcl_FinalizeThread.

### SCRIPT-LEVEL ACCESS TO THREADS

Tcl は時分割の使用､生成､管理､合併する為に使う記述譜に関する組込み関数を提供していないし､どの様な記述譜水準からの相互排除同期機構や条件変数の利用も提供しない｡提供しているのはこのような C 言語相互作用経由の機能のみであるが､記述譜の水準へのこのような事項を開示する為の梱包迄は残している｡この様な梱包の一つは Thread 梱包である｡ Tcl provides no built-in commands for scripts to use to create, manage, or join threads, nor any script-level access to mutex or condition variables. It provides such facilities only via C interfaces, and leaves it up to packages to expose these matters to the script level. One such package is the Thread package.

### 用例 EXAMPLE

移植可能な時分割命令符号を作成する為に､その実装函数は次の様に宣言されるべきである: To create a thread with portable code, its implementation function should be declared as follows:

    static Tcl_ThreadCreateProc MyThreadImplFunc;

それはこの例の様に定義される､そこでは､与えられた値を数えて終了する｡ It should then be defined like this example, which just counts up to a given value and then finishes.

    static Tcl_ThreadCreateType
    MyThreadImplFunc(
        ClientData clientData)
    {
        int i, limit = (int) clientData;
        for (i=0 ; i<limit ; i++) {
            /* doing nothing at all here */
        }
        TCL_THREAD_CREATE_RETURN;
    }

上述の時分割片を作成し､実行させ､終了を待つために､こうする: To create the above thread, make it execute, and wait for it to finish, we would do this:

    int limit = 1000000000;
    ClientData limitData = (void*)((intptr_t) limit);
    Tcl_ThreadId id;    /* holds identity of thread created */
    int result;

    if (Tcl_CreateThread(&id, MyThreadImplFunc, limitData,
            TCL_THREAD_STACK_DEFAULT,
            TCL_THREAD_JOINABLE) != TCL_OK) {
        /* Thread did not create correctly */
        return;
    }
    /* Do something else for a while here */
    if (Tcl_JoinThread(id, &result) != TCL_OK) {
        /* Thread did not finish properly */
        return;
    }
    /* All cleaned up nicely */

### SEE ALSO

Tcl_GetCurrentThread, Tcl_ThreadQueueEvent, Tcl_ThreadAlert, Tcl_ExitThread, Tcl_FinalizeThread, Tcl_CreateThreadExitHandler, Tcl_DeleteThreadExitHandler, Thread

### KEYWORDS

thread, mutex, condition variable, thread local storage
Copyright © 1999 Scriptics Corporation
Copyright © 1998 Sun Microsystems, Inc.