## Tcl9.0.3/Tk9.0.3 Documentation > Thread Package Commands, version 3.0.4 > 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
    thread — Tcl 多重実行薄片を利用する拡張　　　　Extension for script access to Tcl threading
  構文SYNOPSIS
  説明 DESCRIPTION
  諸命令 COMMANDS
    thread::create ?-joinable? ?-preserved? ?script?
    thread::preserve ?id?
    thread::release ?-wait? ?id?
    thread::id
    thread::errorproc ?procname?
    thread::cancel ?-unwind? id ?result?
    thread::unwind
    thread::exit ?status?
    thread::names
    thread::exists id
    thread::send ?-async? ?-head? id script ?varname?
    thread::broadcast script
    thread::wait
    thread::eval ?-lock mutex? arg ?arg . . .?
    thread::join id
    thread::configure id ?option? ?value? ? . . .?
    thread::transfer id channel
    thread::detach channel
    thread::attach channel
    thread::mutex
      thread::mutex create ?-recursive?
      thread::mutex destroy mutex
      thread::mutex lock mutex
      thread::mutex unlock mutex
    thread::rwmutex
      thread::rwmutex create
      thread::rwmutex destroy mutex
      thread::rwmutex rlock mutex
      thread::rwmutex wlock mutex
      thread::rwmutex unlock mutex
    thread::cond
      thread::cond create
      thread::cond destroy cond
      thread::cond notify cond
      thread::cond wait cond mutex ?ms?
  議論DISCUSSION
  SEE ALSO
  KEYWORDS

### NAME

thread — Tcl 多重実行薄片を利用する拡張　　　　Extension for script access to Tcl threading

### 構文SYNOPSIS

package require Tcl 9 .0

package require thread ?3 .0?

thread::create ?-joinable? ?-preserved? ?script?

thread::preserve ?id?

thread::release ?-wait? ?id?

thread::id

thread::errorproc ?procname?

thread::cancel ?-unwind? id ?result?

thread::unwind

thread::exit ?status?

thread::names

thread::exists id

thread::send ?-async? ?-head? id script ?varname?

thread::broadcast script

thread::wait

thread::eval ?-lock mutex? arg ?arg . . .?

thread::join id

thread::configure id ?option? ?value? ? . . .?

thread::transfer id channel

thread::detach channel

thread::attach channel

thread::mutex

thread::mutex create ?-recursive?

thread::mutex destroy mutex

thread::mutex lock mutex

thread::mutex unlock mutex

thread::rwmutex

thread::rwmutex create

thread::rwmutex destroy mutex

thread::rwmutex rlock mutex

thread::rwmutex wlock mutex

thread::rwmutex unlock mutex

thread::cond

thread::cond create

thread::cond destroy cond

thread::cond notify cond

thread::cond wait cond mutex ?ms?

### 説明 DESCRIPTION

thread 拡張は Tcl 解釈実行機能を含む多重実行薄片を創造し､評価の為にこのような多重実行薄片に記述譜を送るよう使用者に促す｡ 更に､それは､相互排他制御や条件変数の様な､記述譜水準での基本多重実行薄片の同期基本要素を利用する手立てを提供する｡　　　　　　 The thread extension creates threads that contain Tcl interpreters, and it lets you send scripts to those threads for evaluation . Additionally, it provides script-level access to basic thread synchronization primitives, like mutexes and condition variables .

### 諸命令 COMMANDS

この節では多重実行薄片を創造する為の命令と､破壊する為の命令と､評価の為に多重実行薄片に記述譜を送る命令を記述する｡ 　　　　　　 This section describes commands for creating and destroying threads and sending scripts to threads for evaluation .

thread::create ?-joinable? ?-preserved? ?script?
  この命令は Tcl 解釈実行機能を含む多重実行薄片を創造する｡Tcl 解釈実行機能は､指示項目の script が指定されていれば評価し､されてなければ､thread::send 命令経由で到達する記述譜を行事待ち巡回内で待機する｡ もしあれば､追加指示の記述譜の結果は呼出者には返されない｡ thread::create の結果は多重実行薄片の識別番号である｡それは他の全ての梱包命令についての新しく創造された多重実行薄片を識別する高度な操作子である｡その操作子は多重実行薄片が終了の印を附られると自動的に有効範囲から出て行く(下の thread::release 命令を参照されたい)｡　　 This command creates a thread that contains a Tcl interpreter . The Tcl interpreter either evaluates the optional script, if specified, or it waits in the event loop for scripts that arrive via the thread::send command . The result, if any, of the optional script is never returned to the caller . The result of thread::create is the ID of the thread . This is the opaque handle which identifies the newly created thread for all other package commands . The handle of the thread goes out of scope automatically when thread is marked for exit (see the thread::release command below) .

  もし指示項目の script 引数が thread::wait 命令を含んでいる場合､その多重実行薄片は行事待ち巡回に入る｡もしこのような命令が script 内に見付らない場合､多重実行薄片は script の末尾に向って実行し､終了する｡ この場合､操作子は安全に無視される､理由は､それが､命令が返った時には最早存在しない多重実行薄片を参照しているから｡　　 If the optional script argument contains the thread::wait command the thread will enter into the event loop . If such command is not found in the script the thread will run the script to the end and exit . In that case, the handle may be safely ignored since it refers to a thread which does not exists any more at the time when the command returns .

  旗印 -joinable を使って､接合可能な多重実行薄片を生成することができる､即ち､thread::join 命令を使ってその出口が待機されることができる｡註意すべきは､ -joinable 旗印と共に生成された多重実行薄片の接合の失敗は､原資と記憶域の漏洩を生じる｡　　　　　　 Using flag -joinable it is possible to create a joinable thread, i .e . one upon whose exit can be waited upon by using thread::join command . Note that failure to join a thread created with -joinable flag results in resource and memory leaks .

  thread::create によって生成された多重実行薄片は強制的に破壊する事はできない｡ 結果として､多重実行薄片の破壊に相当する命令は存在しない｡ 多重実行薄片は thread::release を使って放棄されるだけであるが､もし内部参照勘定が零に落込むとその多重実行薄片は終了の印が附けられる｡ これは多重実行薄片を行事待ち役務から蹴り出し､多重実行薄片は thread::wait 命令に引続く､script 引数内に渡された命令の実行を続ける｡もしこれが記述譜内の最後の命令である場合､通常の場合と同じ様に､多重実行薄片は終了する｡　　　　　　 Threads created by the thread::create cannot be destroyed forcefully . Consequently, there is no corresponding thread destroy command . A thread may only be released using the thread::release and if its internal reference count drops to zero, the thread is marked for exit . This kicks the thread out of the event loop servicing and the thread continues to execute commands passed in the script argument, following the thread::wait command . If this was the last command in the script, as usually the case, the thread will exit .

  多重実行薄片を完了させることができない状況を生み出すことは可能である､譬えば､ thread::wait の後に終りのない巡回を挿入するとか､vwait 型命令を行うことにより行事待ち巡回に再度入るとか｡ そうなるとその多重実行薄片は終了することはない｡ これは､悪しき実務と看做され､可能であれば避けるべきである｡ 次の例により説明する: 　　　　　　　 It is possible to create a situation in which it may be impossible to terminate the thread, for example by putting some endless loop after the thread::wait or entering the event loop again by doing an vwait-type of command . In such cases, the thread may never exit . This is considered to be a bad practice and should be avoided if possible . This is best illustrated by the example below:

      # 真似してはならない
          # You should never do 	.	.	.
          set tid [thread::create {
              package require Http
              thread::wait
              vwait forever ; # <-- this!
          }]

  上の実例内で生成された多重実行薄片は､決して終了する事ができない｡ 最後の合致 thread::release 呼出しにより解放された後､その多重実行薄片は､ thread::wait に飛んで行き､引続く命令の実行を続行する｡ それは vwait 命令に入り､行事の為に終ることなく待つ｡ このような多重実行薄片を完了させる方法はない､誰もその様な事を望んではいない! 　　　　　　 The thread created in the above example will never be able to exit . After it has been released with the last matching thread::release call, the thread will jump out of the thread::wait and continue to execute commands following . It will enter vwait command and wait endlessly for events . There is no way one can terminate such thread, so you wouldn't want to do this!

  新しく作成されたそれぞれは､ 0 (零) に設定された内部勘定を有する､即ち､予約されていない｡この勘定はthread::preserve への呼出しにより増加され､ thread::releaseの呼出しにより減少される｡ この二つの命令の実装は簡単であるが効果的な多重実行薄片予約系を実現し､予測可能な､制御可能な多重実行薄片の完了能力を提供する｡ 但し､thread::create 命令の -preserved 旗印を使うことにより､最初から保持された多重実行薄片を生成する事は可能である｡ この旗印を伴い生成された多重実行薄片は参照勘定の初期値に 1 (壱)を有し､従って､初期に予約が記されている｡　　　　　　　 Each newly created has its internal reference counter set to 0 (zero), i .e . it is unreserved . This counter gets incremented by a call to thread::preserve and decremented by a call to thread::release command . These two commands implement simple but effective thread reservation system and offer predictable and controllable thread termination capabilities . It is however possible to create initially preserved threads by using flag -preserved of the thread::create command . Threads created with this flag have the initial value of the reference counter of 1 (one), and are thus initially marked reserved .

thread::preserve ?id?
  この命令は多重実行薄片の参照勘定を増加させる｡この命令の呼出し毎に参照勘定を一つ (1)増加する｡ 命令は増加の後参照勘定の値を返す｡ もし､指示項目の多重実行薄片識別番号 id を伴って呼出されると､この命令は与えられた多重実行薄片を維持する｡ そうでない場合､現在の多重実行薄片を維持する｡　　　　　　　　 This command increments the thread reference counter . Each call to this command increments the reference counter by one (1) . Command returns the value of the reference counter after the increment . If called with the optional thread id, the command preserves the given thread . Otherwise the current thread is preserved .

  参照勘定により､共有された Tcl 多重実行薄片への制御された利用を実装できる｡ 参照勘定の増加により､呼び出し側は､彼/彼女､が多重実行薄片を長い期間使う事を望むことを､明確に示す｡参照勘定の減少により､呼び出し側は､彼/彼女､が多重実行薄片の使用を終了したことを､明確に示す｡　　　　　　 With reference counting, one can implement controlled access to a shared Tcl thread . By incrementing the reference counter, the caller signalizes that he/she wishes to use the thread for a longer period of time . By decrementing the counter, caller signalizes that he/she has finished using the thread .

thread::release ?-wait? ?id?
  この命令は多重実行薄片の参照勘定を減少させる｡この命令の呼出し毎に参照勘定を一つ (1)減少する｡もし､指示項目の多重実行薄片 識別番号 id を伴って呼出されると､その命令は与えられた多重実行薄片を解放する｡そうでない場合､現在の多重実行薄片を解放する｡命令は参照勘定を減少した後に値を返す｡参照勘定が零 (0) に達した時､目標の多重実行薄片は完了の為の印が附けられる｡thread::release 命令が零か負の整数を返した後はその多重実行薄片を参照すべきではない｡その多重実行薄片の操作子は有効範囲から出て行き､もはや使用すべきではない｡それ以降の､同じ多重実行薄片の操作子へのどの参照も Tcl 不都合になる｡　　　　　　 This command decrements the thread reference counter . Each call to this command decrements the reference counter by one (1) . If called with the optional thread id, the command releases the given thread . Otherwise, the current thread is released . Command returns the value of the reference counter after the decrement . When the reference counter reaches zero (0), the target thread is marked for termination . You should not reference the thread after the thread::release command returns zero or negative integer . The handle of the thread goes out of scope and should not be used any more . Any following reference to the same thread handle will result in Tcl error .

  指示項目の -wait は､もし命令の効果が目標の多重実行薄片が完了の結果になる場合､即ち､もし返り結果が零 (0) になる場合､修了すべき目標の多重実行薄片を待つ呼出し側の多重実行薄片に伝える｡この旗印がないと､呼出し側の多重実行薄片は､目標の多重実行薄片が終了するのを待たない｡ -wait を使う場合は註意を払う必要がある､理由は､これにより､呼出し側の多重実行薄片を､無制限に抑制するかも知れないから｡この指示項目は､拡張の､ある特殊な使用の為に実装され､正規の使用には批判されるものである｡正規の使用者は thread::create 命令の -joinable 指示項目と thread::join を使用して接合可能な多重実行薄片を生成して､多重実行薄片が終了する事を待つべきである｡　　　　 Optional flag -wait instructs the caller thread to wait for the target thread to exit, if the effect of the command would result in termination of the target thread, i .e . if the return result would be zero (0) . Without the flag, the caller thread does not wait for the target thread to exit . Care must be taken when using the -wait, since this may block the caller thread indefinitely . This option has been implemented for some special uses of the extension and is deprecated for regular use . Regular users should create joinable threads by using the -joinable option of the thread::create command and the thread::join to wait for thread to exit .

thread::id
  この命令は現在の多重実行薄片の識別番号を返す｡　　　　　　 This command returns the ID of the current thread .

thread::errorproc ?procname?
  この命令は､他の多重実行薄片に thread::send 命令の -async 旗印を使って､非同期的に送られた記述譜内で生じた不都合の為の操作子を設定する｡ もし､操作子が指定されていない場合､現在の操作子が返される｡ 空文字列は操作子を無為設定(指定されない)値に再設定する｡ 多重実行薄片内での捕捉不能の不都合は標準不都合通信路に送られる不都合伝言文を惹き起こす｡この無為設定の報告の仕組みは､不都合を報告する為に呼ばれた手続函数に登録することにより変更する事ができる｡ procname は thread::errorproc 命令を起動した解釈実行機能内で呼ばれる｡ procname はこのように呼ばれる: 　　　　　　 This command sets a handler for errors that occur in scripts sent asynchronously, using the -async flag of the thread::send command, to other threads . If no handler is specified, the current handler is returned . The empty string resets the handler to default (unspecified) value . An uncaught error in a thread causes an error message to be sent to the standard error channel . This default reporting scheme can be changed by registering a procedure which is called to report the error . The procname is called in the interpreter that invoked the thread::errorproc command . The procname is called like this:

      myerrorproc thread_id errorInfo

thread::cancel ?-unwind? id ?result?
  この命令はTcl 8.6版以上を要する｡(訳註 8.6.6から追加された)　　　　　　 This command requires Tcl version 8 .6 or higher .

  id 媒介変数によって与えられた多重実行薄片内での記述譜の評価を解消する｡-unwind 切替え子なしでは解釈実行機能の評価棚は､包み込んでいる catch 命令が見出されるか､呼出し棚上に更なる解釈実行機能の発動が残らない迄､巻戻される｡-unwind 切替え子がある場合､解釈実行機能の評価棚は､呼出し棚上に更なる解釈実行機能の発動が残らなくなる迄､挟まっているどのような catch 命令も考慮することなく巻き戻す｡result がある場合､それは不都合伝言文として使用されることになり､そうでない場合､無為設定の不都合伝言文が使用される｡ 　　　　　　　 Cancels the script being evaluated in the thread given by the id parameter . Without the -unwind switch the evaluation stack for the interpreter is unwound until an enclosing catch command is found or there are no further invocations of the interpreter left on the call stack . With the -unwind switch the evaluation stack for the interpreter is unwound without regard to any intervening catch command until there are no further invocations of the interpreter left on the call stack . If result is present, it will be used as the error message string; otherwise, a default error message string will be used .

thread::unwind
  この命令の使用は､ thread::preserve と thread::release 命令を使って実装された､より改良された多重実行薄片の予約システムからは批判されている｡ thread::unwind 命令の運営は､近い将来の拡張の主要出版では消失するであろう｡　　　　　　　 Use of this command is deprecated in favour of more advanced thread reservation system implemented with thread::preserve and thread::release commands . Support for thread::unwind command will disappear in some future major release of the extension .

  この命令は先立つ thread::wait 命令を停止する｡ 新しく生成された多重実行薄片に渡された記述譜の実行は thread::wait 命令から続けられる｡ もし､ thread::wait が記述譜の最後の命令の場合､その多重実行薄片は終了する｡ この命令は空の結果を返すが､ある状況では､伝言文 "target thread died" を伴う不都合を惹き起こすことがある｡　　　　　　　 This command stops a prior thread::wait command . Execution of the script passed to newly created thread will continue from the thread::wait command . If thread::wait was the last command in the script, the thread will exit . The command returns empty result but may trigger Tcl error with the message "target thread died" in some situations .

thread::exit ?status?
  この命令の使用は､ thread::preserve と thread::release 命令を使って実装された､より改良された多重実行薄片の予約システムからは批判されている｡ thread::exit 命令の運営は､近い将来の拡張の主要出版では消失するであろう｡　　　　　　　 Use of this command is deprecated in favour of more advanced thread reservation system implemented with thread::preserve and thread::release commands . Support for thread::exit command will disappear in some future major release of the extension .

  この命令は､thread::wait 命令内の多重実行薄片棚を無条件に終了させる｡ 多重実行薄片の終了状態は無為設定の 666 になるが､指示項目の status 引数を使って指定することが可能である｡(訳註 666：Unixの使用権限) thread::exit 命令の実行は､算譜記憶領域を矛盾した状態に留めることを保障し､記憶域漏洩を発生し､そうでない場合､予想できない方法で Tcl 応用譜の他の副システムに影響を及ぼす｡その命令は空の結果を返すが､ある状況では､伝言文 "target thread died" を伴う不都合を惹き起こすことがある｡　　　　　　　 This command forces a thread stuck in the thread::wait command to unconditionally exit . The thread's exit status defaults to 666 and can be specified using the optional status argument . The execution of thread::exit command is guaranteed to leave the program memory in the inconsistent state, produce memory leaks and otherwise affect other subsystem(s) of the Tcl application in an unpredictable manner . The command returns empty result but may trigger Tcl error with the message "target thread died" in some situations .

thread::names
  この命令は多重実行薄片の識別場号のリストを返す｡ それらは､thread::create 命令経由で生成された多重実行薄片についてのみのものである｡ もし使用者の応用譜が C 言語水準に於いて他の多重実行薄片を生成していた場合､それらはこの命令によっては報告されない｡　　　　　　　 This command returns a list of thread IDs . These are only for threads that have been created via thread::create command . If your application creates other threads at the C level, they are not reported by this command .

thread::exists id
  もし 識別番号id によって与えられた多重実行薄片が実在する場合は真値 (1) を返し､そうでない場合は偽値 (0) を返す｡ これは thread::create 命令経由で生成された多重実行薄片にのみ適用される｡　　　　　　　 Returns true (1) if thread given by the id parameter exists, false (0) otherwise . This applies only for threads that have been created via thread::create command .

thread::send ?-async? ?-head? id script ?varname?
  この命令は 記述譜 script を他の多重実行薄片に渡し､指定すれば結果を待つ｡もし､-async 旗印が指定されていると､この命令は結果を待たずに空文字列を返す｡目標の多重実行薄片は､この命令経由で送られる記述譜を受取る為にその行事巡回に入らなければならない｡このことは､開始記述譜なしで生成された多重実行薄片については､無為設定でなされる｡多重実行薄片は､明示的な thread::wait 呼出しか､ update や vwait 等の様な､何か適切な Tcl/Tk 命令を呼ぶことにより行事巡回に入ることができる｡　　　　　　 This command passes a script to another thread and, optionally, waits for the result . If the -async flag is specified, the command does not wait for the result and it returns empty string . The target thread must enter it's event loop in order to receive scripts sent via this command . This is done by default for threads created without a startup script . Threads can enter the event loop explicitly by calling thread::wait or any other relevant Tcl/Tk command, like update, vwait, etc .

  指示項目の varname は､記述譜 script の結果を保存する為の変数の名前を指定する｡ -async 旗印が無い場合､この命令は､標準 Tcl catch 命令を模擬した評価符号番号を返す｡但し､-async 旗印が指定されている場合､この命令はすぐさま帰り､そして､呼び出し側は渡した記述譜 script の結果を得る為に後に､?varname? 上で vwait 呼出しすることができる｡　　　　　　　　　　　 Optional varname specifies name of the variable to store the result of the script . Without the -async flag, the command returns the evaluation code, similarly to the standard Tcl catch command . If, however, the -async flag is specified, the command returns immediately and caller can later vwait on ?varname? to get the result of the passed script

      set t1 [thread::create]
          set t2 [thread::create]
          thread::send -async $t1 "set a 1" result
          thread::send -async $t2 "set b 2" result
          for {set i 0} {$i < 2} {incr i} {
              vwait result
          }

  上の実施例の中で､二つの多重実行薄片が仕事を宛がわれ､その両方が､呼出している多重実行薄片内で同じ変数 "result" を交信することを指示されている｡ 呼出し側は､両方の結果を得る為に二度行事巡回に入る｡ 註意､但し､受取る結果の順序は､現在の系の負荷､行った業務の型､等､等に依存して変化する｡　　　　　　 In the above example, two threads were fed work and both of them were instructed to signalize the same variable "result" in the calling thread . The caller entered the event loop twice to get both results . Note, however, that the order of the received results may vary, depending on the current system load, type of work done, etc, etc .

  多くの多重実行薄片が､実行の為に､同時に記述譜を目標多重実行薄片に送るかもしれない｡ その全てが目標多重実行薄片の行事待ち行列に入り､目標多重実行薄片の行事待ち行列内に保留中の指示された他の行事に混ぜられ､先入先出し基準で実行される｡ 追加の ?-head? 切替えを使うと､多重実行薄片の行事待ち行列に送られる記述譜は､待ち行列の末尾ではなく､先頭に置く事ができる､従って後入先出し方式で実行される｡　　　　　　　 Many threads can simultaneously send scripts to the target thread for execution . All of them are entered into the event queue of the target thread and executed on the FIFO basis, intermingled with optional other events pending in the event queue of the target thread . Using the optional ?-head? switch, scripts posted to the thread's event queue can be placed on the head, instead on the tail of the queue, thus being executed in the LIFO fashion .

thread::broadcast script
  この命令は､実行の為､梱包により生成された全ての多重実行薄片に記述譜 script を渡す｡ そして､どの多重実行薄片からの応答をも待つことはしない｡　　　　　 This command passes a script to all threads created by the package for execution . It does not wait for response from any of the threads .

  実行薄片の送付(thread::broadcast命令の実行)は､記述譜を自己には送らない｡ The sending thread (the one executing the thread::broadcast command) does not send the script to itself .

  それぞれの受取り実行薄片は その行事待ち行列の冒頭に於て 送られた記述譜の評価場所を指示され､ 処理を待っている他のどの行事の先頭も踏み進む Each receiving thread is directed to place evaluation of the send script at the head of its event queue, stepping in front of any other events awaiting processing .

thread::wait
  この命令は待ち行列巡回に入るので､多重実行薄片が thread::send 命令から伝言文を受取る事ができる様になる｡ この命令は thread::create に渡された記述譜の内部でのみ使われるべきである｡ 又､記述譜内の最後尾の命令であるべきでもある｡ もしそうでない場合､退出する多重実行薄片が thread::wait に渡された記述譜行の実行を続ける､通常は､それは使用者が望んだり期待したものではない｡　　　　　　　 This enters the event loop so a thread can receive messages from the thread::send command . This command should only be used within the script passed to the thread::create . It should be the very last command in the script . If this is not the case, the exiting thread will continue executing the script lines past the thread::wait which is usually not what you want and/or expect .

      set t1 [thread::create {
              #
              # 此処で何か初期化する
              # Do some initialization work here
              #
              thread::wait ; # Enter the event loop
          }]

thread::eval ?-lock mutex? arg ?arg . . .?
  この命令は､渡された引数を鎖状に接続して得られた記述譜を相互排他管理保護の下で評価する｡ ?-lock mutex? 追加指定引数を使用して相互排他管理なしが指定されている場合､内部静的相互排他管理が使われる｡　　　　　　 This command concatenates passed arguments and evaluates the resulting script under the mutex protection . If no mutex is specified by using the ?-lock mutex? optional argument, the internal static mutex is used .

thread::join id
  この命令は識別番号 id の多重実行薄片が終了する事を待ち､その終了符号番号を返す｡ 接続可能でないか既に他の多重実行薄片によって待たれている多重実行薄片については不都合が返る｡ 接合の上､多重実行薄片の操作子は有効範囲から出て行き､そして最早使われることはない｡　　　　　　 This command waits for the thread with ID id to exit and then returns it's exit code . Errors will be returned for threads which are not joinable or already waited upon by another thread . Upon the join the handle of the thread has gone out of scope and should not be used any more .

thread::configure id ?option? ?value? ? . . .?
  この命令は､標準 Tcl 命令 fconfigure が幾つかの Tcl 通信路指示項目を構成設定設定するのと似た方法により､識別番号 id の多重実行薄片の種々の低水準特性を構成設定設定する｡ 現在の処､運営している指示項目は: -eventmark と -unwindonerror である｡　 This command configures various low-level aspects of the thread with ID id in the similar way as the standard Tcl command fconfigure configures some Tcl channel options . Options currently supported are: -eventmark and -unwindonerror .

  -eventmark が 0 (零)より大きな値と伴に提供されると､その値は非同期に送られ､多重実行薄片について仕掛りになり得る記述譜の､最高値になる｡ thread::send -async は行事巡回内の仕掛りの数が -eventmark value より下に落ちる迄抑制する｡ When -eventmark is provided with a value greater than 0 (zero), that value is the maximum number of asynchronously posted scripts that may be pending for the thread . thread::send -async blocks until the number of pending scripts in the event loop drops below the -eventmark value .

  -unwindonerror が論理真値と伴に提供されると､記述譜内の不都合の結果が多重実行薄片に巻き戻しを起こさせ､更なる記述譜の評価を利用できなくする｡ When -unwindonerror is provided with a value of true, an error result in a script causes the thread to unwind, making it unavailable to evaluate additional scripts .

thread::transfer id channel
  これは､現在の多重実行薄片と解釈実行機能から､与えれた識別番号 id を持つ多重実行薄片の主解釈実行機能に､指定された通信路 channel を移動する｡ 移動の後は､現在の解釈実行機能からはその通信路はもはや利用できなくなるが､今以降､目標の多重実行薄片の主解釈実行機能は､それを使える様になる｡ この命令は他の多重実行薄片が通信路を組み込む迄待つ｡ それ故､ thread::send 同期を通して我々に通信路を移転させるように､相手を命令することにより､参加している多重実行薄片を自縛させることができる｡ この安易な拡張が､多重実行薄片を､互に相手を待ちあう長い巡回に導いている｡ それ以外の制限: くだんの通信路は､多重実行薄片を送付中の多重の解釈実行機能間で共有する事はできない｡ この命令は､標準入力と標準出力と標準不都合出力の為の特定の通信路を自動的に遮断する｡　　　　　　　　 This moves the specified channel from the current thread and interpreter to the main interpreter of the thread with the given id . After the move the current interpreter has no access to the channel any more, but the main interpreter of the target thread will be able to use it from now on . The command waits until the other thread has incorporated the channel . Because of this it is possible to deadlock the participating threads by commanding the other through a synchronous thread::send to transfer a channel to us . This easily extends into longer loops of threads waiting for each other . Other restrictions: the channel in question must not be shared among multiple interpreters running in the sending thread . This automatically excludes the special channels for standard input, output and error .

  内部の Tcl 中核実装と共有通信路の転送上の制限のために､ socket 命令の呼出し手続函数以外で接続を受入れることによって創造された授受口通信路の転送には､特別の対策を講じなければならない｡　　　　　　　 Due to the internal Tcl core implementation and the restriction on transferring shared channels, one has to take extra measures when transferring socket channels created by accepting the connection out of the socket commands callback procedures:

      socket -server _Accept 2200
          proc _Accept {s ipaddr port} {
              after idle [list Accept $s $ipaddr $port]
          }
          proc Accept {s ipaddr port} {
              set tid [thread::create]
              thread::transfer $tid $s
          }

thread::detach channel
  指定した channel を現在の多重実行薄片と解釈実行機能から切離す｡ その後､現在の解釈実行機能は最早､通信路を利用できない｡ 通信路は､何か他の(または､同じ)多重実行薄片がthread::attach を使って接触する迄､駐在状態である｡ 制限事項: thread::transfer 命令による共有された通信路の転換と同じ制限｡ This detaches the specified channel from the current thread and interpreter . After that, the current interpreter has no access to the channel any more . The channel is in the parked state until some other (or the same) thread attaches the channel again with thread::attach . Restrictions: same as for transferring shared channels with the thread::transfer command .

thread::attach channel
  現在の 多重実行薄片/解釈実行機能 内で以前引離された channel を接続する｡ 既存の通信路については､この命令は何もしない､即ち､同じ通信路を再度接続する事は不都合ではない｡ 最初の操作は実際に操作を遂行するが､引続く操作は全て何もしない｡ もし､通信路 channel が引離された通信路のリスト 及び/又は 現在の解釈実行機能 内に見付からない場合､命令は不都合を発信す｡ 　　　　　　　　　 This attaches the previously detached channel in the current thread/interpreter . For already existing channels, the command does nothing, i .e . it is not an error to attach the same channel more than once . The first operation will actually perform the operation, while all subsequent operation will just do nothing . Command throws error if the channel cannot be found in the list of detached channels and/or in the current interpreter .

thread::mutex
  相互排他制御は最も普通の多重実行薄片の同期化の原初的機能である｡ それらは､二つ或はそれ以上の多重実行薄片から､一つ或はそれ以上の共有された原資への､利用の同期をとることに使われる｡ この命令は､排他的 且つ/又は 再帰的相互排他制御 記述譜水準の利用を提供する｡ 排他的な相互排他制御は､唯一度だけ一つの多重実行薄片に施錠されるが､再帰的な相互排他制御は､多数回､同じ多重実行薄片に施錠されることができる｡ 再帰的な相互排他制御について､施錠と解錠の操作の回数は合致しなければならない､さもないと､相互排他制御は､解放されることがなくなり､それは様々な自縛状態に導く｡　　　　　　　 Mutexes are most common thread synchronization primitives . They are used to synchronize access from two or more threads to one or more shared resources . This command provides script-level access to exclusive and/or recursive mutexes . Exclusive mutexes can be locked only once by one thread, while recursive mutexes can be locked many times by the same thread . For recursive mutexes, number of lock and unlock operations must match, otherwise, the mutex will never be released, which would lead to various deadlock situations .

  多重の多重実行薄片の算譜内で相互排他制御を使う時は註意が必要である｡ 多重実行薄片の不適切な使用､特に排他的な相互排他制御の使用は､色々な自縛状態に導くかもしれない｡　　　　　　　　 Care has to be taken when using mutexes in an multithreading program . Improper use of mutexes may lead to various deadlock situations, especially when using exclusive mutexes .

  thread::mutex 命令は次の副命令と指示項目を運営する: 　　　　　　 The thread::mutex command supports following subcommands and options:

  thread::mutex create ?-recursive?
    相互排他制御を生成し不透明な操作子を返す｡この操作子は､新しく生成された相互排他制御へのどのような将来の参照にも使われるべきものである｡もし追加の ?-recursive? 引数が全く指定されない場合､この命令は相互的な相互排他制御を生成する｡ ?-recursive? 引数を付けると､この命令は､再帰的な相互排他制御を生成する｡　　　　　　 Creates the mutex and returns it's opaque handle . This handle should be used for any future reference to the newly created mutex . If no optional ?-recursive? argument was specified, the command creates the exclusive mutex . With the ?-recursive? argument, the command creates a recursive mutex .

  thread::mutex destroy mutex
    相互排他制御 mutex を破壊する｡ 相互排他制御は破壊を試みる前に解錠状態であるべきである｡もし相互排他制御が施錠されていると､この命令は不都合を発信する｡　　　　　　　 Destroys the mutex . Mutex should be in unlocked state before the destroy attempt . If the mutex is locked, the command will throw Tcl error .

  thread::mutex lock mutex
    相互排他制御 mutex を施錠する｡相互排他制御を施錠すると､もし同じ多重実行薄片から同じ相互排他制御に二度施錠しようと試みると､Tcl 不都合を発信する｡もし､使用者の算譜の論理が､同じ多重実行薄片から､同じ相互排他制御を二度或はそれ以上施錠することを強いる場合(これは再帰的手続函数の起動で起り得る)､再起的な相互排他制御の使用を考慮すべきである｡　　　　　　　　 Locks the mutex . Locking the exclusive mutex may throw Tcl error if on attempt to lock the same mutex twice from the same thread . If your program logic forces you to lock the same mutex twice or more from the same thread (this may happen in recursive procedure invocations) you should consider using the recursive mutexes .

  thread::mutex unlock mutex
    mutex を解錠し､どれかの他の多重実行薄片が再度施錠できる様にする｡ 既に解錠された相互排他制御を解錠しようとすると Tcl 不都合を発信する｡　　　　　　　 Unlocks the mutex so some other thread may lock it again . Attempt to unlock the already unlocked mutex will throw Tcl error .

thread::rwmutex
  この命令は 多数読者/単一者記入者 相互排他制御を生成する｡ 読者/記入者 相互排他制御は､より好適に､共有された原資を順番に利用することを可能にする｡ 殆どが読出しで､稀に修正がされる様な共有原資を得るには､排他的や､再帰的の相互排他制御の代わりに読者/記入者 相互排他制御を使用することにより､何がしかの実績が得られるかもしれない｡　　　　　 This command creates many-readers/single-writer mutexes . Reader/writer mutexes allow you to serialize access to a shared resource more optimally . In situations where a shared resource gets mostly read and seldom modified, you might gain some performance by using reader/writer mutexes instead of exclusive or recursive mutexes .

  原資の読出しについては､多重実行薄片は原資上に読出し錠を得ることになる｡ 読出し錠は排他的ではない､その意味は､一つより多くの多重実行薄片が同じ原資に対して読出し錠を得ることができ､他の読者を待つことはない｡ 原資の変更には､しかし､多重実行薄片は､排他的記入錠を得なければならない｡ この錠は､記入者の多重実行薄片により原資が修正される間､全ての多重実行薄片からの読出し錠の取得を､効果的に抑制する｡ 記入施錠が解放された後にのみ､原資は再度､読出し施錠がなされる｡　　　　　　　 For reading the resource, thread should obtain a read lock on the resource . Read lock is non-exclusive, meaning that more than one thread can obtain a read lock to the same resource, without waiting on other readers . For changing the resource, however, a thread must obtain a exclusive write lock . This lock effectively blocks all threads from gaining the read-lock while the resource is been modified by the writer thread . Only after the write lock has been released, the resource may be read-locked again .

  thread::rwmutex 命令は次の副命令と指示項目を運営する: 　　　　　　 The thread::rwmutex command supports following subcommands and options:

  thread::rwmutex create
    読み手/書き手 相互排他制御を生成しその不透明な操作子を返す｡ この操作子は､新しく生成される相互排他制御へのどのような将来の参照にも使われるべきものである｡　　　　　　　 Creates the reader/writer mutex and returns it's opaque handle . This handle should be used for any future reference to the newly created mutex .

  thread::rwmutex destroy mutex
    読み手/書き手相互排他制御 mutex を破壊する｡ もし相互排他制御が既に施錠されていると､破壊の試みは Tcl 不都合を発信する｡　　　　　　 Destroys the reader/writer mutex . If the mutex is already locked, attempt to destroy it will throw Tcl error .

  thread::rwmutex rlock mutex
    読出しの為の相互排他制御 mutex を施錠する｡一つ以上の多重実行薄片が､同じmutex を同時に読出し施錠してもよい｡　　　　　　 Locks the mutex for reading . More than one thread may read-lock the same mutex at the same time .

  thread::rwmutex wlock mutex
    書込みの為に相互排他制御 mutex を施錠する｡一つだけの多重実行薄片が､同じmutex を同時に書込み施錠してよい｡ 同じmutexに､同じ多重実行薄片から二度書込み施錠する試みは Tcl 不都合を発信する｡　　　　　　　 Locks the mutex for writing . Only one thread may write-lock the same mutex at the same time . Attempt to write-lock same mutex twice from the same thread will throw Tcl error .

  thread::rwmutex unlock mutex
    相互排他制御 mutex を解錠し､どれかの他の多重実行薄片が再度施錠できる様にする｡ 既に解錠された相互排他制御を解錠しようとすると Tcl 不都合を発信する｡　　　　　　　 Unlocks the mutex so some other thread may lock it again . Attempt to unlock already unlocked mutex will throw Tcl error .

thread::cond
  Tこの命令は条件変数への記述譜水準の利用を提供する｡ 条件変数は､ある条件に於いて偽値の時に眠り､真値になったかもしれない時に起きることを試験する為の算譜に就いて､安全な環境を生成する｡ 条件変数は常に､排他的な相互排他制御と一緒に使用される｡ もし､使用者が他の型の相互排他制御と一緒に条件変数を使用しようと試みると Tcl 不都合が発信されることになる｡　　　　　　　 his command provides script-level access to condition variables . A condition variable creates a safe environment for the program to test some condition, sleep on it when false and be awakened when it might have become true . A condition variable is always used in the conjunction with an exclusive mutex . If you attempt to use other type of mutex in conjunction with the condition variable, a Tcl error will be thrown .

  この命令は次の副命令と指示項目を運営する: 　　　　　　 The command supports following subcommands and options:

  thread::cond create
    条件変数を生成し不透明な操作子を返す｡ この操作子は､新しく生成される条件変数へのどのような将来の参照にも使われるべきものである｡　　　　　　　 Creates the condition variable and returns it's opaque handle . This handle should be used for any future reference to newly created condition variable .

  thread::cond destroy cond
    条件変数 cond を破壊する｡ 誰もその条件変数を使わない(即ち､それを待ち受けない)様に特別に註意しなければならない､さもないと予想されない不都合が生じる｡　　　　　　 Destroys condition variable cond . Extreme care has to be taken that nobody is using (i .e . waiting on) the condition variable, otherwise unexpected errors may happen .

  thread::cond notify cond
    条件変数 cond を待っている全ての多重実行薄片を呼び起こす｡　　　　　　 Wakes up all threads waiting on the condition variable cond .

  thread::cond wait cond mutex ?ms?
    この命令は､条件変数 cond が交信されるか指示項目タイマーが満了するまで､算譜の実行を保留する為に使われる｡ 排他的な相互排他制御 mutex はこの命令への入口上の多重実行薄片呼出しによって施錠されなければならない｡ もし相互排他制御が施錠されていない場合､ Tcl 不都合が発信される｡ cond を待つ間､この命令は､相互排他制御 mutex を解放する｡ 呼ばれた多重実行薄片に帰る前に､この命令は再度､mutex を再獲得する｡ mutex の解錠と条件変数 cond の待ち受けは自動的に行われる｡　　　　　　 This command is used to suspend program execution until the condition variable cond has been signalled or the optional timer has expired . The exclusive mutex must be locked by the calling thread on entrance to this command . If the mutex is not locked, Tcl error is thrown . While waiting on the cond, the command releases mutex . Before returning to the calling thread, the command re-acquires the mutex again . Unlocking the mutex and waiting on the condition variable cond is done atomically .

    ms 命令指示項目は､もし与えられると､命令が交信されることを待つ千分の１秒単位の時間間隔を指示する整数でなければならない｡ 与えられないと､この命令は条件の通知を永遠に待つ｡　　　　　　　 The ms command option, if given, must be an integer specifying time interval in milliseconds the command waits to be signalled . Otherwise the command waits on condition notify forever .

    多重実行薄片の算譜内では､多重実行薄片が､処理を許容される迄､何かの行事を待たされる､という多くの状態がある｡ これは通常､相互排他制御の保護下で繰返して条件を試験をし､条件評価が真値になる迄条件変数を待つ事により達成される: 　　　　　　　 In multithreading programs, there are many situations where a thread has to wait for some event to happen until it is allowed to proceed . This is usually accomplished by repeatedly testing a condition under the mutex protection and waiting on the condition variable until the condition evaluates to true:

        set mutex [thread::mutex create]
            set cond  [thread::cond  create]

            thread::mutex lock $mutex
            while {<some_condition_is_true>} {
                thread::cond wait $cond $mutex
            }
            # 相互排他制御の保護下で事を為す
            # Do some work under mutex protection
            thread::mutex unlock $mutex

    条件の繰り返し試験は必要である､理由は､実際に条件の変更なしに条件変数が交信を得るかもしれないから(譬えば､偽造の多重実行薄片の覚醒)｡　　　　　　　 Repeated testing of the condition is needed since the condition variable may get signalled without the condition being actually changed (spurious thread wake-ups, for example) .

### 議論DISCUSSION

Tcl 内の基本的な多重実行薄片化模型は､多重実行薄片に一つあるいはそれ以上の Tcl 解釈実行機能が存在することができるが､それぞれのTcl 解釈実行機能はそれが生成された一つの多重実行薄片にのみ使用されるべきである｡ "共有された記憶域" の概念は Tcl 内に提供するには扱い難い､理由は､ Tcl は変数とデータについて所有権を仮定しているから｡ 従って､拡張は､主の多重実行薄片が幾つかの背景処理又は "処理機能 worker" を管理できる様な､単純な多重実行薄片化を運営している｡ 譬えば､行事駆動の中央集中処理装置は要求を処理機能実行薄片に渡すことができ､次いで､処理機能実行薄片の応答か､新しい依頼者の要求を待つ｡ 全ての事柄が通常の Tcl 行事巡回を通り過ぎ､そこで､ 行事駆動入出力､変数上の vwait ､等により､伝言文が処理機能実行薄片間を自然に渡される｡ 巨大な情報の転送の為に､実行薄片間を通信路が移動する事が可能である｡　　　　　　 The fundamental threading model in Tcl is that there can be one or more Tcl interpreters per thread, but each Tcl interpreter should only be used by a single thread which created it . A "shared memory" abstraction is awkward to provide in Tcl because Tcl makes assumptions about variable and data ownership . Therefore this extension supports a simple form of threading where the main thread can manage several background, or "worker" threads . For example, an event-driven server can pass requests to worker threads, and then await responses from worker threads or new client requests . Everything goes through the common Tcl event loop, so message passing between threads works naturally with event-driven I/O, vwait on variables, and so forth . For the transfer of bulk information it is possible to move channels between the threads .

高度な多重の多重実行薄片の記述譜の為に､二つの基本的同期化基本機能の記述譜水準の利用､相互排他制御と条件変数も運営されている｡　　　　　　　 For advanced multithreading scripts, script-level access to two basic synchronization primitives, mutex and condition variables, is also supported .

### SEE ALSO

http://www .tcl .tk/doc/howto/thread_model .html, tpool, tsv, ttrace

### KEYWORDS

events, message passing, mutex, synchronization, thread