## Tcl9.0.3/Tk9.0.3 Documentation > Thread Package Commands, version 3.0.4 > tpool

### 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
    tpool — 多重実行薄片の処理担当員の予備集団を実装する Tcl 多重実行薄片の役割　　　　 Part of the Tcl threading extension implementing pools of worker threads .
  構文 SYNOPSIS
  説明DESCRIPTION
  諸命令 COMMANDS
    tpool::create ?options?
      -minworkers number
      -maxworkers number
      -idletime seconds
      -initcmd script
      -exitcmd script
    tpool::names
    この命令は､実行の為の目標 tpool 多重実行薄片の予備集団に記述譜 script を送る｡ その記述譜は最初の利用可能な空転している処理担当の多重実行薄片内で実行される｡ もし利用可能な空転している処理担当の多重実行薄片がない場合､この命令は新しいものを生成し､行事待ち巡回に入り､新しく生成された多重実行薄片が初期化されるまで､行事の処理を担当する｡ もし処理担当の多重実行薄片の現在の個数が､多重実行薄片の予備集団として生成の間に定義された処理担当の多重実行薄片の最大値に等しい場合､この命令は行事巡回に入り､処理担当の多重実行薄片の内の一つが空転になるのを待つ間､行事の処理を担当する｡
    tpool::wait tpool joblist ?varname?
    tpool::cancel tpool joblist ?varname?
    tpool::get tpool job
    tpool::preserve tpool
    tpool::release tpool
    tpool::suspend tpool
    tpool::resume tpool
  議論DISCUSSION
  SEE ALSO
  KEYWORDS

### NAME

tpool — 多重実行薄片の処理担当員の予備集団を実装する Tcl 多重実行薄片の役割　　　　 Part of the Tcl threading extension implementing pools of worker threads .

### 構文 SYNOPSIS

package require Tcl 9 .0

package require thread ?3 .0?

tpool::create ?options?

tpool::names

tpool::post ?-detached? ?-nowait? tpool script

tpool::wait tpool joblist ?varname?

tpool::cancel tpool joblist ?varname?

tpool::get tpool job

tpool::preserve tpool

tpool::release tpool

tpool::suspend tpool

tpool::resume tpool

### 説明DESCRIPTION

この梱包は､多重実行薄片の処理担当の予備集団を生成し管理する｡ それにより業務を多重実行薄片の処理担当に送付しその完了を待つことができる様になる｡ 多重実行薄片の予備集団の実装は Tcl 行事巡回待機の範疇である｡ これは､呼出し側が行事を待つ事(業務が完了したか､多重実行薄片の処理担当が空転化か初期化された)を強制される時は何時でも､実装は行事巡回に入り､他の保留されているファイルやタイマー(又は他の運営されている)行事の役務実行を許容することを意味する｡　　　　　　　 This package creates and manages pools of worker threads . It allows you to post jobs to worker threads and wait for their completion . The threadpool implementation is Tcl event-loop aware . That means that any time a caller is forced to wait for an event (job being completed or a worker thread becoming idle or initialized), the implementation will enter the event loop and allow for servicing of other pending file or timer (or any other supported) events .

### 諸命令 COMMANDS

tpool::create ?options?
  この命令は新しい多重実行薄片の予備集団を生成する｡ それは幾つかの指示項目を､検索用語-値 対として､受け付ける｡ 指示項目は何かの多重実行薄片の予備集団の媒介変数の調整に使われる｡ この命令は新しく生成された多重実行薄片の予備集団の識別番号を返す｡　　　　　　　 This command creates new threadpool . It accepts several options as key-value pairs . Options are used to tune some threadpool parameters . The command returns the ID of the newly created threadpool .

  次の指示項目が運営されている　　　　　　　 Following options are supported:

  -minworkers number
    この多重実行薄片の予備集団の実体について必要とされる処理担当の多重実行薄片の最小値｡ 多重実行薄片の予備集団を生成する間､実装は同数の処理担当の多重実行薄片を前以て生成し､多重実行薄片の予備集団の実体の寿命がある間､その内の最小の数を活かして保有している｡ この媒介変数の無為設定は 0 (零)であり､その意味は､新しい多重実行薄片の予備集団は初期には処理担当の多重実行薄片を有していない｡ 全ての処理担当の多重実行薄片は呼出し側の要求によって始まり､tpool::post 命令を走らせ､業務待ち行列に業務を送付する｡　　　　　　　 Minimum number of worker threads needed for this threadpool instance . During threadpool creation, the implementation will create somany worker threads upfront and will keep at least number of them alive during the lifetime of the threadpool instance . Default value of this parameter is 0 (zero) . which means that a newly threadpool will have no worker threads initially . All worker threads will be started on demand by callers running tpool::post command and posting jobs to the job queue .

  -maxworkers number
    この多重実行薄片の予備集団の実体の為に許容される処理担当の多重実行薄片の最大値｡ もし､新しい業務が保留され､且つ､利用できる空転している処理担当の多重実行薄片がない場合､実装は新しい処理担当の多重実行薄片を生成しようと試みる｡ もし利用可能な処理担当の多重実行薄片の個数が与えられた個数より少ない場合､新しい処理担当の多重実行薄片が始まる｡ 呼出し側は､自動的に行事待ち巡回に入り､処理担当の多重実行薄片が初期化されるまで待つ｡ しかし､もし､利用可能な処理担当の多重実行薄片の個数が与えられた個数と等しい場合､呼出し側は､行事巡回に入り､最初の処理担当の多重実行薄片が空転になるのを待つ､そこで業務実行の準備ができる｡ この媒介変数の無為設定は 4(四っつ),この意味は､処理担当の多重実行薄片の実体は､業務を実行するか､業務待ち行列に送付される新しい業務を待って空転しているかの､処理担当の多重実行薄片､を最大４つ許容する｡　　　　　　　　 Maximum number of worker threads allowed for this threadpool instance . If a new job is pending and there are no idle worker threads available, the implementation will try to create new worker thread . If the number of available worker threads is lower than the given number, new worker thread will start . The caller will automatically enter the event loop and wait until the worker thread has initialized . If . however, the number of available worker threads is equal to the given number, the caller will enter the event loop and wait for the first worker thread to get idle, thus ready to run the job . Default value of this parameter is 4 (four), which means that the threadpool instance will allow maximum of 4 worker threads running jobs or being idle waiting for new jobs to get posted to the job queue .

  -idletime seconds
    空転している処理担当の多重実行薄片が業務待ち行列に送付される新しい業務を待つ秒単位の時間｡ もし､この期間の間に到着する業務がなく､且つ､時間が満了した場合､処理担当の多重実行薄片は､現在利用可能な処理担当の多重実行薄片の個数を確認し､個数が minthreads 指示項目により設定された数より多い場合､それは終了する｡ もし､ exitscript が定義されていた場合､既存の処理担当の多重実行薄片は始めに記述譜を実行しその後終了する｡終了した記述譜からの不都合はあっても無視される｡　　　　　　　 Time in seconds an idle worker thread waits for the job to get posted to the job queue . If no job arrives during this interval and the time expires, the worker thread will check the number of currently available worker threads and if the number is higher than the number set by the minthreads option, it will exit . If an exitscript has been defined, the exiting worker thread will first run the script and then exit . Errors from the exit script, if any, are ignored .

    空転している処理担当の多重実行薄片は行事待ち巡回を 担当していない｡ もし､vwait や他の関連した Tcl 命令を評価することによって､処理担当の多重実行薄片を行事待ち巡回に入れると､処理担当の多重実行薄片は､空転状態にならないので､空転タイマーは考慮されなくなる｡ この指示項目の無為設定の値は定めれていない｡　　　　　　　 The idle worker thread is not servicing the event loop . If you, however, put the worker thread into the event loop, by evaluating the vwait or other related Tcl commands, the worker thread will not be in the idle state, hence the idle timer will not be taken into account . Default value for this option is unspecified .

  -initcmd script
    新しい処理担当の多重実行薄片を初期化する為に使用する Tcl 記述譜を設定する｡ これは､通常､梱包と処理担当の命令の積込み､無為設定値の設定､名前空間の生成､等に使用される｡ もし渡された記述譜が Tcl 不都合を起こすと､処理担当は生成されず､初期化命令(tpool::create か tpool::post のどちらか)が不都合を発信する｡ この指示項目に対する無為設定の値は指定されていない､従って､処理担当の多重実行薄片の Tcl 解釈処理担当は Tcl 命令の初期設定を含むことになる｡　　　　　　　 Sets a Tcl script used to initialize new worker thread . This is usually used to load packages and commands in the worker, set default variables, create namespaces, and such . If the passed script runs into a Tcl error, the worker will not be created and the initiating command (either the tpool::create or tpool::post) will throw error . Default value for this option is unspecified, hence, the Tcl interpreter of the worker thread will contain just the initial set of Tcl commands .

  -exitcmd script
    空転している処理担当の多重実行薄片が実在する時に実行する Tcl 記述譜を設定する｡ 之は通常､処理担当の多重実行薄片の状態の解消､予約していた原資の解放､記憶域の解消､等に使われる｡ この指示項目に対する無為設定の値は指定されていない､従って､処理担当の多重実行薄片が実在するときに実行される Tcl 記述譜はない｡　　　　　　　 Sets a Tcl script run when the idle worker thread exits . This is normally used to cleanup the state of the worker thread, release reserved resources, cleanup memory and such . Default value for this option is unspecified, thus no Tcl script will run on the worker thread exit .

tpool::names
  この命令は tpool::create 命令によって生成された多重実行薄片の予備集団の識別番号のリストを返す｡ もし､多重実行薄片の予備集団が見付らない場合､この命令は空リストを返す｡　　　　　　　 This command returns a list of IDs of threadpools created with the tpool::create command . If no threadpools were found, the command will return empty list .

この命令は､実行の為の目標 tpool 多重実行薄片の予備集団に記述譜 script を送る｡ その記述譜は最初の利用可能な空転している処理担当の多重実行薄片内で実行される｡ もし利用可能な空転している処理担当の多重実行薄片がない場合､この命令は新しいものを生成し､行事待ち巡回に入り､新しく生成された多重実行薄片が初期化されるまで､行事の処理を担当する｡ もし処理担当の多重実行薄片の現在の個数が､多重実行薄片の予備集団として生成の間に定義された処理担当の多重実行薄片の最大値に等しい場合､この命令は行事巡回に入り､処理担当の多重実行薄片の内の一つが空転になるのを待つ間､行事の処理を担当する｡
  もし､追加の ?-nowait? 引数が与えられると､ 本命令は､ 縦え処理集団に猶追加の実行薄片を保有する余裕があっても､ 閑な処理担当を待つことなく､又､新しい処理担当を生成せず､ 業務を､業務待ち行列に置く｡ tpool::post ?-detached? ?-nowait? tpool script This command sends a script to the target tpool threadpool for execution . The script will be executed in the first available idle worker thread . If there are no idle worker threads available, the command will create new one, enter the event loop and service events until the newly created thread is initialized . If the current number of worker threads is equal to the maximum number of worker threads, as defined during the threadpool creation, the command will enter the event loop and service events while waiting for one of the worker threads to become idle . If the optional ?-nowait? argument is given, the command just places the job in the pool's job queue without waiting for an idle worker or creating a new one, even if the pool would still have room for additional threads .

  この命令は送られた業務の識別番号を返す｡ この識別番号は､それぞれ､送付された記述譜の結果を取出すか､送付された業務を取消すかの為に待つ為に､引続く tpool::wait と tpool::get と tpool::cancel 命令に使われる｡ もし､追加の ?-detached? 引数が指定されていると､この命令は､引き剥がした業務を送付する｡引き剥がされた業務は予約解消も待つ事もできず､業務識別番号によっても識別できない｡　　　　　　　 The command returns the ID of the posted job . This ID is used for subsequent tpool::wait, tpool::get and tpool::cancel commands to wait for and retrieve result of the posted script, or cancel the posted job respectively . If the optional ?-detached? argument is specified, the command will post a detached job . A detached job can not be cancelled or waited upon and is not identified by the job ID .

  もし多重実行薄片の予備集団 tpool が活動中の多重実行薄片の予備集団のリスト内に見付らない場合､命令は不都合を発信する｡ 不都合は､もし新しく生成された処理担当の多重実行薄片が初期化に失敗した場合も､発動される｡　　　　　　　 If the threadpool tpool is not found in the list of active thread pools, the command will throw error . The error will also be triggered if the newly created worker thread fails to initialize .

tpool::wait tpool joblist ?varname?
  この命令は､処理担当の多重実行薄片によって処理されるべき joblist 内に与えられる認識番号を持つ一つ或は多数の業務を待つ｡ 指定された業務が準備されて無い場合､この命令は行事巡回に入り､行事の処理を担当し準備できた最初の業務を待つ｡　　　　　　　 This command waits for one or many jobs, whose job IDs are given in the joblist to get processed by the worker thread(s) . If none of the specified jobs are ready, the command will enter the event loop, service events and wait for the first job to get ready .

  この命令は､完了した業務識別番号のリストを返す｡ もし､追加的に変数 ?varname? が与えられると､それは､依然保留されている joblist 内の業務のリストを設定する｡ もし多重実行薄片の予備集団 tpool が活動中の多重実行薄片の予備集団のリスト内に見付らない場合､この命令は不都合を発信する｡　　　　　　 The command returns the list of completed job IDs . If the optional variable ?varname? is given, it will be set to the list of jobs in the joblist which are still pending . If the threadpool tpool is not found in the list of active thread pools, the command will throw error .

tpool::cancel tpool joblist ?varname?
  予備集団 tpool に宛て以前に送付された､joblist で与えられた業務を予約取消する｡ 業務の予約取消は依然処理を待っている業務についてのみ成功する｡ もし業務がどれか一つの処理担当の多重実行薄片によって既に実行されている場合､その業務は予約取消されない｡ この命令は予約取消された業務の識別番号のリストを返す｡ もし､追加変数 ?varname? が与えられると､それは､予約取消されない joblist 内の業務リストに設定される｡ もし多重実行薄片の予備集団 tpool が活動中の多重実行薄片の予備集団のリスト内に見付らない場合､命令は不都合を発信する｡　　　　　　 This command cancels the previously posted jobs given by the joblist to the pool tpool . Job cancellation succeeds only for job still waiting to be processed . If the job is already being executed by one of the worker threads, the job will not be cancelled . The command returns the list of cancelled job IDs . If the optional variable ?varname? is given, it will be set to the list of jobs in the joblist which were not cancelled . If the threadpool tpool is not found in the list of active thread pools, the command will throw error .

tpool::get tpool job
  この命令は､以前に送付された job の結果を取出す｡ tpool::wait 命令によって待たれていた業務の結果のみが取出せる｡ もし､記述譜の実行が不都合になっていた場合､この命令は不都合を発信し errorInfo と errorCode 変数をそれぞれ更新する｡ もし多重実行薄片の予備集団 tpool が活動中の多重実行薄片の予備集団のリスト内に見付らない場合､命令は不都合を発信する｡ もし､現在処理担当の多重実行薄片によって実行されている故に､業務 job が取出し準備できない場合､この命令は不都合を発信する｡　　　　　　　 This command retrieves the result of the previously posted job . Only results of jobs waited upon with the tpool::wait command can be retrieved . If the execution of the script resulted in error, the command will throw the error and update the errorInfo and errorCode variables correspondingly . If the pool tpool is not found in the list of threadpools, the command will throw error . If the job job is not ready for retrieval, because it is currently being executed by the worker thread, the command will throw error .

tpool::preserve tpool
  この命令の呼出し毎に多重実行薄片の予備集団 tpool の参照勘定が 一つ (1) 増加される｡ 参照勘定の増加によって､呼出し側は 彼/彼女 が長期の期間について原資を使うことを望んでいることを交信する｡　　　　　　　 Each call to this command increments the reference counter of the threadpool tpool by one (1) . Command returns the value of the reference counter after the increment . By incrementing the reference counter, the caller signalizes that he/she wishes to use the resource for a longer period of time .

tpool::release tpool
  この命令の呼出し毎に多重実行薄片の予備集団 tpool の参照勘定が 一つ (1) 減少する｡ 命令は参照勘定を減じた後に値を返す｡ 参照勘定が零 (0) に達した時､多重実行薄片の予備集団は完了の為の印が附けられる｡tpool::release 命令が零か負の整数を返した後はその多重実行薄片の予備集団を参照すべきではない｡ その tpool の操作子は有効範囲から出て行き､もはや使用できなくなる｡ それ以降の､同じ多重実行薄片の予備集団の操作子へのどの参照も Tcl 不都合になる｡　　　　　　　 Each call to this command decrements the reference counter of the threadpool tpool by one (1) .Command returns the value of the reference counter after the decrement . When the reference counter reaches zero (0), the threadpool tpool is marked for termination . You should not reference the threadpool after the tpool::release command returns zero . The tpool handle goes out of scope and should not be used any more . Any following reference to the same threadpool handle will result in Tcl error .

tpool::suspend tpool
  この待ち行列上の業務の処理を一時保留する｡全ての予備集団の処理担当は休止されるが､追加の業務は予備集団に追加可能である｡註意すべきは､追加業務の追加は動的には処理担当の数を増加させない､理由は予備集団の処理が一時停止しているから｡処理担当の数は一時休止する以前に処理担当が活動して見られた数が維持される｡もし特定の数の処理担当の多重実行薄片を確保する必要であれば､tpool::create 命令の minworkers 指示項目を使用されたい｡　　　　　　　 Suspends processing work on this queue . All pool workers are paused but additional work can be added to the pool . Note that adding the additional work will not increase the number of workers dynamically as the pool processing is suspended . Number of workers is maintained to the count that was found prior suspending worker activity . If you need to assure certain number of worker threads, use the minworkers option of the tpool::create command .

tpool::resume tpool
  この待ち行列上の処理機能を再開する｡全ての停止した(保留された)処理担当は予備集団から業務の取得が自由になる｡註意すべきは､予備集団の操作再開は既に生成されている処理担当に処理をさせるだけである｡処理担当の業務待ち行列に送られる業務を処理する追加の処理担当多重実行薄片を生成することはない｡　　　　　　　 Resume processing work on this queue . All paused (suspended) workers are free to get work from the pool . Note that resuming pool operation will just let already created workers to proceed . It will not create additional worker threads to handle the work posted to the pool's work queue .

### 議論DISCUSSION

多くの個数の比較的小さな業務を取扱う中央集中処理応用譜にいたる時､多重実行薄片の予備集団は最も普通の多重実行薄片の模範の内の一つである｡中央集中処理応用譜を形成する為の非常に簡素化した模型は､要求が届く度に新しい多重実行薄片を生成し､そしてその新しい多重実行薄片内でその要求を担当する､ものであろう｡このやり方の不利な点の一つは､それぞれの要求の為の新しい多重実行薄片の生成の負担が大きいことである; それぞれの要求毎に新しく生成された多重実行薄片の中央集中処理装置は､実際に使用者の要求を処理することよりも､多重実行薄片の生成と破壊に､多くの時間を費やし､多くの系の原資を費やす｡多重実行薄片の生成と破壊の負担に加え活動中多重実行薄片は系の原資を消費する｡余りに多くの多重実行薄片の生成は､系に記憶域外への飛出しや記憶域消費による破壊をさせるかもしれない｡　　　　　　　　 Threadpool is one of the most common threading paradigm when it comes to server applications handling a large number of relatively small tasks . A very simplistic model for building a server application would be to create a new thread each time a request arrives and service the request in the new thread . One of the disadvantages of this approach is that the overhead of creating a new thread for each request is significant; a server that created a new thread for each request would spend more time and consume more system resources in creating and destroying threads than in processing actual user requests . In addition to the overhead of creating and destroying threads, active threads consume system resources . Creating too many threads can cause the system to run out of memory or trash due to excessive memory consumption .

多重実行薄片の予備集団は多重実行薄片の寿命循環の負担による問題と､原資の破壊の問題の両方の解決策を提供する｡ 多重化業務の為の多重実行薄片の再使用により､多重実行薄片生成の負担は多くの業務に分散される｡ おまけとして､多重実行薄片が既に実在している為に､要求が到達した時､多重実行薄片生成によりもたらされた遅延が取除かれる｡ 従って､要求はすぐさま取扱われる｡ 更に､多重実行薄片の予備集団内の多重実行薄片の個数を適切に調整することにより､どのような要求もそれを処理する為に多重実行薄片が利用できるまで待つことを強制することにより､原資の毀損も取除かれる｡　　　　　　　 A thread pool offers a solution to both the problem of thread life-cycle overhead and the problem of resource trashing . By reusing threads for multiple tasks, the thread-creation overhead is spread over many tasks . As a bonus, because the thread already exists when a request arrives, the delay introduced by thread creation is eliminated . Thus, the request can be serviced immediately . Furthermore, by properly tuning the number of threads in the thread pool, resource thrashing may also be eliminated by forcing any request to wait until a thread is available to process it .

### SEE ALSO

thread, tsv, ttrace

### KEYWORDS

thread, threadpool