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

### 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
    tsv — 多重実行薄片の間で共有されるデータの記述譜水準での取扱を許容している Tcl 多重実行薄片の拡張の役割 　　　　　　　Part of the Tcl threading extension allowing script level manipulation of data shared between threads .
  構文 SYNOPSIS
  説明DESCRIPTION
  要素命令ELEMENT COMMANDS
    tsv::names ?pattern?
    tsv::object varname element
    tsv::set varname element ?value?
    tsv::get varname element ?namedvar?
    tsv::unset varname ?element?
    tsv::exists varname element
    tsv::pop varname element
    tsv::move varname oldname newname
    tsv::incr varname element ?count?
    tsv::append varname element value ?value . . .?
    tsv::lock varname arg ?arg . . .?
    tsv::handlers
  リスト命令LIST COMMANDS
    tsv::lappend varname element value ?value . . .?
    tsv::linsert varname element index value ?value . . .?
    tsv::lreplace varname element first last ?value . . .?
    tsv::llength varname element
    tsv::lindex varname element ?index?
    tsv::lrange varname element from to
    tsv::lsearch varname element ?options? pattern
    tsv::lset varname element index ?index . . .? value
    tsv::lpop varname element ?index?
    tsv::lpush varname element ?index?
  ARRAY COMMANDS
    tsv::array set varname list
    tsv::array get varname ?pattern?
    tsv::array names varname ?pattern?
    tsv::array size varname
    tsv::array reset varname list
    tsv::array bind varname handle
    tsv::array unbind varname
    tsv::array isbound varname
  検索用語のあるリスト命令KEYED LIST COMMANDS
    tsv::keyldel varname keylist key
    tsv::keylget varname keylist key ?retvar?
    tsv::keylkeys varname keylist ?key?
    tsv::keylset varname keylist key value ?key value . .?
  議論DISCUSSION
  著作権表示CREDITS
  SEE ALSO
  KEYWORDS

### NAME

tsv — 多重実行薄片の間で共有されるデータの記述譜水準での取扱を許容している Tcl 多重実行薄片の拡張の役割 　　　　　　　Part of the Tcl threading extension allowing script level manipulation of data shared between threads .

### 構文 SYNOPSIS

package require Tcl 9 .0

package require thread ?3 .0?

tsv::names ?pattern?

tsv::object varname element

tsv::set varname element ?value?

tsv::get varname element ?namedvar?

tsv::unset varname ?element?

tsv::exists varname element

tsv::pop varname element

tsv::move varname oldname newname

tsv::incr varname element ?count?

tsv::append varname element value ?value . . .?

tsv::lock varname arg ?arg . . .?

tsv::handlers

tsv::lappend varname element value ?value . . .?

tsv::linsert varname element index value ?value . . .?

tsv::lreplace varname element first last ?value . . .?

tsv::llength varname element

tsv::lindex varname element ?index?

tsv::lrange varname element from to

tsv::lsearch varname element ?options? pattern

tsv::lset varname element index ?index . . .? value

tsv::lpop varname element ?index?

tsv::lpush varname element ?index?

tsv::array set varname list

tsv::array get varname ?pattern?

tsv::array names varname ?pattern?

tsv::array size varname

tsv::array reset varname list

tsv::array bind varname handle

tsv::array unbind varname

tsv::array isbound varname

tsv::keyldel varname keylist key

tsv::keylget varname keylist key ?retvar?

tsv::keylkeys varname keylist ?key?

tsv::keylset varname keylist key value ?key value . .?

### 説明DESCRIPTION

この節では､多重実行薄片共有変数を実装する命令を記述する｡ 多重実行薄片共有変数は Tcl 配列に非常に似ているが､ Tcl 配列とは対照的に共有記憶域内で生成され､同時に多くの多重実行薄片から利用できる｡ 多重実行薄片共有変数の重要な特性としての､実行薄片からのそれぞれの変数への利用の衝突は内部的に相互排他制御によって保護されているので､記述譜作成者は変数そのものへの施錠については註意を払う必要はない｡　　　　　　 This section describes commands implementing thread shared variables . A thread shared variable is very similar to a Tcl array but in contrast to a Tcl array it is created in shared memory and can be accessed from many threads at the same time . Important feature of thread shared variable is that each access to the variable is internally protected by a mutex so script programmer does not have to take care about locking the variable himself .

多重実行薄片共有変数は明示的にはどの多重実行薄片にも束縛されていない｡ その意味は､どれかの多重実行薄片共有変数を生成した多重実行薄片が終了した時､変数とそれに 結合した記憶域は 消去/回収 されない｡ 使用者は､変数によって消費された記憶域を回収する為に､明示的に変数を消去する必要がある｡　　　　　　　 Thread shared variables are not bound to any thread explicitly . That means that when a thread which created any of thread shared variables exits, the variable and associated memory is not unset/reclaimed . User has to explicitly unset the variable to reclaim the memory consumed by the variable .

### 要素命令ELEMENT COMMANDS

tsv::names ?pattern?
  指示項目の ?pattern? と合致する共有変数の名前を返すか､紋様が省略された場合は全ての既知の変数が返される｡　　　　　　 Returns names of shared variables matching optional ?pattern? or all known variables if pattern is omitted .

tsv::object varname element
  共有変数 varname 内の element についての対象利用命令を生成する｡ この命令を使い､大多数の他の共有変数命令を要素対象命令の手段函数として適用する事ができる｡この対象命令は､この命令が指している要素が削除された時に自動的に削除される｡　　　　　　 Creates object accessor command for the element in the shared variable varname . Using this command, one can apply most of the other shared variable commands as method functions of the element object command . The object command is automatically deleted when the element which this command is pointing to is unset .

      % tsv::set foo bar "A shared string"
          % set string [tsv::object foo bar]
          % $string append " appended"
          => A shared string appended

tsv::set varname element ?value?
  共有変数 varname 内の element の値を value に設定し､値を呼出し側に返す｡value は省略されることがあり､その場合､この命令は要素の現在の値を返す｡ もし､要素が見付らない場合､不都合が起動される｡　　　　　　　 Sets the value of the element in the shared variable varname to value and returns the value to caller . The value may be omitted, in which case the command will return the current value of the element . If the element cannot be found, error is triggered .

tsv::get varname element ?namedvar?
  共有変数 varname から element の値を取出す｡ もし､追加引数 namedvar が与えられると､値はその名前の変数に保存される｡ 命令の返す値は追加引数 namedvar の有無に依存する｡ その引数が省略され､且つ､要求された要素を共有配列内に見付けることができない場合この命令は不都合を発する｡ その引数が命令行上に与えられた場合､要素が見付るとこの命令は真値(1)を返し､要素が見付らないと偽値(0)を返す｡　　　　　　　 Retrieves the value of the element from the shared variable varname . If the optional argument namedvar is given, the value is stored in the named variable . Return value of the command depends of the existence of the optional argument namedvar . If the argument is omitted and the requested element cannot be found in the shared array, the command triggers error . If, however, the optional argument is given on the command line, the command returns true (1) if the element is found or false (0) if the element is not found .

tsv::unset varname ?element?
  共有変数 varname から element を消去する｡ 指示項目の element が与えられない場合､変数を削除する｡　　　　　　 Unsets the element from the shared variable varname . If the optional element is not given, it deletes the variable .

tsv::exists varname element
  共有変数 varname の中に element が実在するか否かを確認し､実在すれば真値 (1)を､しなければ偽値 (0) を返す｡　　　　　　 Checks whether the element exists in the shared variable varname and returns true (1) if it does or false (0) if it doesn't .

tsv::pop varname element
  共有変数 varname の中の element の値を返し､element を消去する､全ては一つの不可分の操作である｡　　　　　　 Returns value of the element in the shared variable varname and unsets the element, all in one atomic operation .

tsv::move varname oldname newname
  varname の中の要素 oldname を newname に名前変更する｡ これは効果的に､ 取得/消去/設定 操作の並びを遂行するが､一個の不可分の操作である｡　　　　　　 Renames the element oldname to the newname in the shared variable varname . This effectively performs an get/unset/set sequence of operations but all in one atomic step .

tsv::incr varname element ?count?
  標準の Tcl incr 命令に似ているが､Tcl 変数ではなく､共有変数 varname 内の要素 element の値を増加する｡ Similar to standard Tcl incr command but increments the value of the element in shared variable varname instead of the Tcl variable .

tsv::append varname element value ?value . . .?
  標準のTcl append 命令に似ているが､Tcl 変数ではなく､共有変数 varname 内の要素 element に一つないしそれ以上の値を追加する｡　　　　　　 Similar to standard Tcl append command but appends one or more values to the element in shared variable varname instead of the Tcl variable .

tsv::lock varname arg ?arg . . .?
  この命令は渡された引数を鎖状に連結して､その結果の記述譜を､内部相互排他制御の保護の下で評価する｡ 記述譜を評価する間､共有変数全体が施錠される｡ 記述譜内部の共有変数の為に､内部施錠は､行き詰まりが起らない様に､無効にされる｡ 共有変数は､最初の施錠操作の時に実在しない場合は自動的に生成される｡　　　　　　 This command concatenates passed arguments and evaluates the resulting script under the internal mutex protection . During the script evaluation, the entire shared variable is locked . For shared variable commands within the script, internal locking is disabled so no deadlock can occur . It is also allowed to unset the shared variable from within the script . The shared variable is automatically created if it did not exists at the time of the first lock operation .

      % tsv::lock foo {
              tsv::lappend foo bar 1
              tsv::lappend foo bar 2
              puts stderr [tsv::set foo bar]
              tsv::unset foo
          }

tsv::handlers
  機械語翻訳時に利用可能な全ての持続的に保存された操作子の名前を返す｡詳細は ARRAY COMMANDS を参照されたい｡　　　　　　 Returns the names of all persistent storage handlers enabled at compile time . See ARRAY COMMANDS for details .

### リスト命令LIST COMMANDS

これ等の命令は同じ名前のTcl 命令と等価である｡違いは､これらが共有配列の要素に対して操作することである｡　　　　　　 Those command are similar to the equivalently named Tcl command . The difference is that they operate on elements of shared arrays .

tsv::lappend varname element value ?value . . .?
  標準の lappend Tcl 命令に似ているが､Tcl 変数ではなく共有変数 varname 内の要素 element に一つないしそれ以上の値を追加する｡　　　　　　 Similar to standard Tcl lappend command but appends one or more values to the element in shared variable varname instead of the Tcl variable .

tsv::linsert varname element index value ?value . . .?
  標準の linsert Tcl 命令に似ているが､Tcl 変数ではなく共有変数 varname 内の要素 element に一つないしそれ以上の値をリストの位置 index に挿入する｡　　　　　　 Similar to standard Tcl linsert command but inserts one or more values at the index list position in the element in the shared variable varname instead of the Tcl variable .

tsv::lreplace varname element first last ?value . . .?
  標準の lreplace Tcl 命令に似ているが､Tcl 変数ではなく共有変数 varname の要素 element 内の first と last 位置の間の一つないしそれ以上の値を入替える｡　　　　　　 Similar to standard Tcl lreplace command but replaces one or more values between the first and last position in the element of the shared variable varname instead of the Tcl variable .

tsv::llength varname element
  標準の llength Tcl 命令に似ているが､Tcl 変数ではなく共有変数 varname 内の要素 element の長さを返す｡ Similar to standard Tcl llength command but returns length of the element in the shared variable varname instead of the Tcl variable .

tsv::lindex varname element ?index?
  標準の lindex Tcl 命令に似ているが､Tcl 変数ではなく共有変数 varname 内の要素 element のリスト位置 index の値を返す｡　　　　　　 Similar to standard Tcl lindex command but returns the value at the index list position of the element from the shared variable varname instead of the Tcl variable .

tsv::lrange varname element from to
  標準の lrange Tcl 命令に似ているが､Tcl 変数ではなく共有変数 varname 内の要素からリスト位置が from と to の間の値を返す｡ Similar to standard Tcl lrange command but returns values between from and to list positions from the element in the shared variable varname instead of the Tcl variable .

tsv::lsearch varname element ?options? pattern
  標準の lsearch Tcl 命令に似ているが､Tcl 変数ではなく共有変数 varname 内の要素から element を捜す｡　　　　　　 Similar to standard Tcl lsearch command but searches the element in the shared variable varname instead of the Tcl variable .

tsv::lset varname element index ?index . . .? value
  標準の lset Tcl 命令に似ているが､Tcl 変数ではなく共有変数 varname 内の要素 element を設定する｡　　　　　　 Similar to standard Tcl lset command but sets the element in the shared variable varname instead of the Tcl variable .

tsv::lpop varname element ?index?
  標準の lindex Tcl 命令に似ているが､返すことに加えて､共有変数 varname から要素 element を出した値を接続することを､一つの不可分の操作で行う｡ Tcl lindex 命令とは異なり､この命令は呼出し側に値を持帰らない｡(訳註 校正上のミスがあるらしい)　　　　　　 Similar to the standard Tcl lindex command but in addition to returning, it also splices the value out of the element from the shared variable varname in one atomic operation . In contrast to the Tcl lindex command, this command returns no value to the caller .

tsv::lpush varname element ?index?
  この命令は tsv::lpop 命令の反対の操作を遂行する｡ 片割れと同じように､この命令は呼出し側に値を持帰らない｡　　　　　 This command performs the opposite of the tsv::lpop command . As its counterpart, it returns no value to the caller .

### ARRAY COMMANDS

この命令は､標準 Tcl array 命令の大部分の指示項目を運営する｡ それに加えて､共有変数をどれかの永続的貯蔵基礎データへの結合を許容する｡ 現在の所､運営されている永続的指示項目は有名な GNU Gdbm と LMDB である｡ この指示項目は梱包の機械語総翻訳の時に選択されなければならない｡ その実装は､必要なら他の永続的階層の定義の為の鈎を提供する｡　　　　　　 This command supports most of the options of the standard Tcl array command . In addition to those, it allows binding a shared variable to some persistent storage databases . Currently the persistent options supported are the famous GNU Gdbm and LMDB . These options have to be selected during the package compilation time . The implementation provides hooks for defining other persistency layers, if needed .

tsv::array set varname list
  標準 Tcl array set と同じことをする｡　　　　　　 Does the same as standard Tcl array set .

tsv::array get varname ?pattern?
  標準 Tcl array get と同じことをする｡　　　　　　 Does the same as standard Tcl array get .

tsv::array names varname ?pattern?
  標準 Tcl array names と同じことをする｡　　　　　　 Does the same as standard Tcl array names .

tsv::array size varname
  標準 Tcl array size と同じことをする｡　　　　　　 Does the same as standard Tcl array size .

tsv::array reset varname list
  標準 Tcl array set と同じことをする､但し､ varname を解消し､リストから新しい値を自動的に設定する｡　　　　　　 Does the same as standard Tcl array set but it clears the varname and sets new values from the list atomically .

tsv::array bind varname handle
  varname を永続的貯蔵 handle に束縛する｡ handle の書式は <handler>:<address> である､ 此処で <handler> は GNU Gdbm を表す "gdbm" か LMDB を表す "lmdb" であり､<address> は基礎データファイルへの経路である｡　　　　　　　 Binds the varname to the persistent storage handle . The format of the handle is <handler>:<address>, where <handler> is "gdbm" for GNU Gdbm and "lmdb" for LMDB and <address> is the path to the database file .

tsv::array unbind varname
  束縛された永続的貯蔵から共有 array の束縛を解く｡　　　　　 Unbinds the shared array from its bound persistent storage .

tsv::array isbound varname
  共有 varname が何かの永続的貯蔵に束縛されていれば真値 (1) を､そうでなければ偽値 (0) を返す｡　　　　　　　 Returns true (1) if the shared varname is bound to some persistent storage or zero (0) if not .

### 検索用語のあるリスト命令KEYED LIST COMMANDS

検索用語のあるリスト命令は TclX 梱包から借用された｡検索用語のあるリストは標準 Tcl リスト上に構築された構造型データ型を提供する｡ これは C 算譜言語内の構造に似た機能である｡　　　　　　　 Keyed list commands are borrowed from the TclX package . Keyed lists provide a structured data type built upon standard Tcl lists . This is a functionality similar to structs in the C programming language .

検索用語のあるリストは､その中のそれぞれの要素が検索用語と値の対を含むリストである｡ この要素対が､リストそのものとして保存され､そこでは､検索用語がリストの第一要素､値が第二要素である｡検索用語-値対は欄として参照される｡これは検索用語のあるリストの例である:　　　　　　 A keyed list is a list in which each element contains a key and value pair . These element pairs are stored as lists themselves, where the key is the first element of the list, and the value is the second . The key-value pairs are referred to as fields . This is an example of a keyed list:

    {{NAME  {Frank  Zappa}} {JOB {musician and composer}}}

欄は副欄を有しても好い; `.' が区切り記号である｡ 副欄は実際は欄であり､そこでは値は別の検索用語リストである｡ 従って､次のリストは頂上水準欄識別子と名前 NAME と副欄の名前.初め NAME.FIRST と名前.末尾 NAME.LAST を有する:　　　　　　　 Fields may contain subfields; ` .' is the separator character . Subfields are actually fields where the value is another keyed list . Thus the following list has the top level fields ID and NAME, and subfields NAME .FIRST and NAME .LAST:

    {ID 106} {NAME {{FIRST Frank} {LAST Zappa}}}

副欄の再帰的深さに限界はなく､複雑なデータ構造の構築を許容している｡ 検索用語付きリストは､多くの命令経由で構築され利用されている｡ 全ての検索用語つきリストの管理命令は､リストを直接渡されるのではなく､引数として､検索用語付きリストを含む変数の名前を取る｡　　　　　　 There is no limit to the recursive depth of subfields, allowing one to build complex data structures . Keyed lists are constructed and accessed via a number of commands . All keyed list management commands take the name of the variable containing the keyed list as an argument (i .e . passed by reference), rather than passing the list directly .

tsv::keyldel varname keylist key
  共有変数 varname 内の検索用語付きリスト keylist から検索用語 key によって指定された欄を削除する｡ これは､検索用語付きリストから検索用語と値の両方を取去る｡　　　　　 Delete the field specified by key from the keyed list keylist in the shared variable varname . This removes both the key and the value from the keyed list .

tsv::keylget varname keylist key ?retvar?
  共有変数 varname 内の検索用語付きリスト keylist から検索用語 key に結合した値を返す｡ もし､指示項目の retvar が指定されない場合､値は命令の結果として返される｡ この場合､もしリスト内に検索用語が見つからないと不都合が結果になる｡　　　　　　　 Return the value associated with key from the keyed list keylist in the shared variable varname . If the optional retvar is not specified, then the value will be returned as the result of the command . In this case, if key is not found in the list, an error will result .

  もし retvar が指定され且つリスト中に key がある場合､値は変数 retvar 内に返され､検索用語がリスト内部に存在する時は命令は 1 を返す｡ もし検索用語がリスト内にない場合､命令は 0 を返し変数 retvar は変更されずに残る｡ もし､ retvar として {} が指定されると､値は取出されず､Tcl 算譜作成者に､副作用として変数を設定することなく､検索用語付きリスト内に検索用語 key が存在するかを決定できるようにする｡　　　　　　　 If retvar is specified and key is in the list, then the value is returned in the variable retvar and the command returns 1 if the key was present within the list . If key isn't in the list, the command will return 0, and retvar will be left unchanged . If {} is specified for retvar, the value is not returned, allowing the Tcl programmer to determine if a key is present in a keyed list without setting a variable as a side-effect .

tsv::keylkeys varname keylist ?key?
  共有変数 varname 内の検索用語付きリスト keylist から検索用語のリストを返す｡ もし検索用語 key が指定されると､それは､その副欄の検索用語が取出される検索用語欄の名前である｡　　　　　　 Return the a list of the keys in the keyed list keylist in the shared variable varname . If key is specified, then it is the name of a key field whose subfield keys are to be retrieved .

tsv::keylset varname keylist key value ?key value . .?
  検索用語付きリスト keylist 内の検索用語 key に結合した値を value に設定する｡ keylist が実在しない場合は生成される｡ 検索用語 key が現在リスト中にない場合は追加される｡ もしそれが既に実在する場合､値 value が既存の値に置き換えられる｡ 望む場合には､多重の検索用語語と値を指定できる｡　　　　　　　 Set the value associated with key, in the keyed list keylist to value . If the keylist does not exists, it is created . If key is not currently in the list, it will be added . If it already exists, value replaces the existing value . Multiple keywords and values may be specified, if desired .

### 議論DISCUSSION

多重実行薄片に共有された変数の現在の実装は､異なる多重実行薄片間で共有されたデータへの容易で便利な利用を可能にする｡ 内部的に､データは Tcl 対象内に保存され､全ての梱包命令は内部データ表現上で操作する､従って揺らめきを最小化し出来栄えを推進している｡ 多重実行薄片の間で対象が移動する時は､全てのデータは適切に施錠され､深い複写がなされることを保証する為に特別な注意が払われている｡　　　　　　　 The current implementation of thread shared variables allows for easy and convenient access to data shared between different threads . Internally, the data is stored in Tcl objects and all package commands operate on internal data representation, thus minimizing shimmering and improving performance . Special care has been taken to assure that all object data is properly locked and deep-copied when moving objects between threads .

Tcl 核の内部設計の故に､ Tcl 構文の内部に共有変数の充分な統合の準備ができない｡ 共有変数への全ての接触は供給された梱包命令により遂行されなければならない｡ 又､変数の追跡も運営されない｡ それでも､安易さ､簡易で安全な共有データの取扱は移入された制限を跳ね除ける｡　　　　　　　 Due to the internal design of the Tcl core, there is no provision of full integration of shared variables within the Tcl syntax, unfortunately . All access to shared data must be performed with the supplied package commands . Also, variable traces are not supported . But even so, benefits of easy, simple and safe shared data manipulation outweighs imposed limitations .

### 著作権表示CREDITS

Thread shared variables は､AOL社による 拡張可能な Web 集中処理装置 の AOLserver 註にみられる nsv 対話機能により触発された｡ Thread shared variables are inspired by the nsv interface found in AOLserver, a highly scalable Web server from America Online .

### SEE ALSO

thread, tpool, ttrace

### KEYWORDS

locking, synchronization, thread shared data, threads