util/src/TclTk/tcl8.6.12/pkgs/thread2.8.7/doc/html/tsv.html

   1
   2 <html><head>
   3 <title>tsv - Tcl Threading</title>
   4 <style type="text/css"><!--
   5     HTML {
   6         background:     #FFFFFF;
   7         color:          black;
   8     }
   9     BODY {
  10         background:     #FFFFFF;
  11         color:          black;
  12     }
  13     DIV.doctools {
  14         margin-left:    10%;
  15         margin-right:   10%;
  16     }
  17     DIV.doctools H1,DIV.doctools H2 {
  18         margin-left:    -5%;
  19     }
  20     H1, H2, H3, H4 {
  21         margin-top:     1em;
  22         font-family:    sans-serif;
  23         font-size:      large;
  24         color:          #005A9C;
  25         background:     transparent;
  26         text-align:             left;
  27     }
  28     H1.doctools_title {
  29         text-align: center;
  30     }
  31     UL,OL {
  32         margin-right: 0em;
  33         margin-top: 3pt;
  34         margin-bottom: 3pt;
  35     }
  36     UL LI {
  37         list-style: disc;
  38     }
  39     OL LI {
  40         list-style: decimal;
  41     }
  42     DT {
  43         padding-top:    1ex;
  44     }
  45     UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
  46         font:           normal 12pt/14pt sans-serif;
  47         list-style:     none;
  48     }
  49     LI.doctools_section, LI.doctools_subsection {
  50         list-style:     none;
  51         margin-left:    0em;
  52         text-indent:    0em;
  53         padding:        0em;
  54     }
  55     PRE {
  56         display:        block;
  57         font-family:    monospace;
  58         white-space:    pre;
  59         margin:         0%;
  60         padding-top:    0.5ex;
  61         padding-bottom: 0.5ex;
  62         padding-left:   1ex;
  63         padding-right:  1ex;
  64         width:          100%;
  65     }
  66     PRE.doctools_example {
  67         color:          black;
  68         background:     #f5dcb3;
  69         border:         1px solid black;
  70     }
  71     UL.doctools_requirements LI, UL.doctools_syntax LI {
  72         list-style:     none;
  73         margin-left:    0em;
  74         text-indent:    0em;
  75         padding:        0em;
  76     }
  77     DIV.doctools_synopsis {
  78         color:          black;
  79         background:     #80ffff;
  80         border:         1px solid black;
  81         font-family:    serif;
  82         margin-top:     1em;
  83         margin-bottom:  1em;
  84     }
  85     UL.doctools_syntax {
  86         margin-top:     1em;
  87         border-top:     1px solid black;
  88     }
  89     UL.doctools_requirements {
  90         margin-bottom:  1em;
  91         border-bottom:  1px solid black;
  92     }
  93 --></style>
  94 </head>
  95 <! -- Generated from file '' by tcllib/doctools with format 'html'
  96    -->
  97 <! -- tsv.n
  98    -->
  99 <body><div class="doctools">
 100 <h1 class="doctools_title">tsv(n) 2.8  &quot;Tcl Threading&quot;</h1>
 101 <div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
 102 <p>tsv - Part of the Tcl threading extension allowing script level manipulation of data shared between threads.</p>
 103 </div>
 104 <div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
 105 <ul class="doctools_toc">
 106 <li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
 107 <li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
 108 <li class="doctools_section"><a href="#section1">Description</a></li>
 109 <li class="doctools_section"><a href="#section2">ELEMENT COMMANDS</a></li>
 110 <li class="doctools_section"><a href="#section3">LIST COMMANDS</a></li>
 111 <li class="doctools_section"><a href="#section4">ARRAY COMMANDS</a></li>
 112 <li class="doctools_section"><a href="#section5">KEYED LIST COMMANDS</a></li>
 113 <li class="doctools_section"><a href="#section6">DISCUSSION</a></li>
 114 <li class="doctools_section"><a href="#section7">CREDITS</a></li>
 115 <li class="doctools_section"><a href="#see-also">See Also</a></li>
 116 <li class="doctools_section"><a href="#keywords">Keywords</a></li>
 117 </ul>
 118 </div>
 119 <div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
 120 <div class="doctools_synopsis">
 121 <ul class="doctools_requirements">
 122 <li>package require <b class="pkgname">Tcl 8.4</b></li>
 123 <li>package require <b class="pkgname">Thread <span class="opt">?2.8?</span></b></li>
 124 </ul>
 125 <ul class="doctools_syntax">
 126 <li><a href="#1"><b class="cmd">tsv::names</b> <span class="opt">?pattern?</span></a></li>
 127 <li><a href="#2"><b class="cmd">tsv::object</b> <i class="arg">varname</i> <i class="arg">element</i></a></li>
 128 <li><a href="#3"><b class="cmd">tsv::set</b> <i class="arg">varname</i> <i class="arg">element</i> <span class="opt">?value?</span></a></li>
 129 <li><a href="#4"><b class="cmd">tsv::get</b> <i class="arg">varname</i> <i class="arg">element</i> <span class="opt">?namedvar?</span></a></li>
 130 <li><a href="#5"><b class="cmd">tsv::unset</b> <i class="arg">varname</i> <span class="opt">?element?</span></a></li>
 131 <li><a href="#6"><b class="cmd">tsv::exists</b> <i class="arg">varname</i> <i class="arg">element</i></a></li>
 132 <li><a href="#7"><b class="cmd">tsv::pop</b> <i class="arg">varname</i> <i class="arg">element</i></a></li>
 133 <li><a href="#8"><b class="cmd">tsv::move</b> <i class="arg">varname</i> <i class="arg">oldname</i> <i class="arg">newname</i></a></li>
 134 <li><a href="#9"><b class="cmd">tsv::incr</b> <i class="arg">varname</i> <i class="arg">element</i> <span class="opt">?count?</span></a></li>
 135 <li><a href="#10"><b class="cmd">tsv::append</b> <i class="arg">varname</i> <i class="arg">element</i> <i class="arg">value</i> <span class="opt">?value ...?</span></a></li>
 136 <li><a href="#11"><b class="cmd">tsv::lock</b> <i class="arg">varname</i> <i class="arg">arg</i> <span class="opt">?arg ...?</span></a></li>
 137 <li><a href="#12"><b class="cmd">tsv::handlers</b></a></li>
 138 <li><a href="#13"><b class="cmd">tsv::lappend</b> <i class="arg">varname</i> <i class="arg">element</i> <i class="arg">value</i> <span class="opt">?value ...?</span></a></li>
 139 <li><a href="#14"><b class="cmd">tsv::linsert</b> <i class="arg">varname</i> <i class="arg">element</i> <i class="arg">index</i> <i class="arg">value</i> <span class="opt">?value ...?</span></a></li>
 140 <li><a href="#15"><b class="cmd">tsv::lreplace</b> <i class="arg">varname</i> <i class="arg">element</i> <i class="arg">first</i> <i class="arg">last</i> <span class="opt">?value ...?</span></a></li>
 141 <li><a href="#16"><b class="cmd">tsv::llength</b> <i class="arg">varname</i> <i class="arg">element</i></a></li>
 142 <li><a href="#17"><b class="cmd">tsv::lindex</b> <i class="arg">varname</i> <i class="arg">element</i> <span class="opt">?index?</span></a></li>
 143 <li><a href="#18"><b class="cmd">tsv::lrange</b> <i class="arg">varname</i> <i class="arg">element</i> <i class="arg">from</i> <i class="arg">to</i></a></li>
 144 <li><a href="#19"><b class="cmd">tsv::lsearch</b> <i class="arg">varname</i> <i class="arg">element</i> <span class="opt">?options?</span> <i class="arg">pattern</i></a></li>
 145 <li><a href="#20"><b class="cmd">tsv::lset</b> <i class="arg">varname</i> <i class="arg">element</i> <i class="arg">index</i> <span class="opt">?index ...?</span> <i class="arg">value</i></a></li>
 146 <li><a href="#21"><b class="cmd">tsv::lpop</b> <i class="arg">varname</i> <i class="arg">element</i> <span class="opt">?index?</span></a></li>
 147 <li><a href="#22"><b class="cmd">tsv::lpush</b> <i class="arg">varname</i> <i class="arg">element</i> <span class="opt">?index?</span></a></li>
 148 <li><a href="#23"><b class="cmd">tsv::array set</b> <i class="arg">varname</i> <i class="arg">list</i></a></li>
 149 <li><a href="#24"><b class="cmd">tsv::array get</b> <i class="arg">varname</i> <span class="opt">?pattern?</span></a></li>
 150 <li><a href="#25"><b class="cmd">tsv::array names</b> <i class="arg">varname</i> <span class="opt">?pattern?</span></a></li>
 151 <li><a href="#26"><b class="cmd">tsv::array size</b> <i class="arg">varname</i></a></li>
 152 <li><a href="#27"><b class="cmd">tsv::array reset</b> <i class="arg">varname</i> <i class="arg">list</i></a></li>
 153 <li><a href="#28"><b class="cmd">tsv::array bind</b> <i class="arg">varname</i> <i class="arg">handle</i></a></li>
 154 <li><a href="#29"><b class="cmd">tsv::array unbind</b> <i class="arg">varname</i></a></li>
 155 <li><a href="#30"><b class="cmd">tsv::array isbound</b> <i class="arg">varname</i></a></li>
 156 <li><a href="#31"><b class="cmd">tsv::keyldel</b> <i class="arg">varname</i> <i class="arg">keylist</i> <i class="arg">key</i></a></li>
 157 <li><a href="#32"><b class="cmd">tsv::keylget</b> <i class="arg">varname</i> <i class="arg">keylist</i> <i class="arg">key</i> <span class="opt">?retvar?</span></a></li>
 158 <li><a href="#33"><b class="cmd">tsv::keylkeys</b> <i class="arg">varname</i> <i class="arg">keylist</i> <span class="opt">?key?</span></a></li>
 159 <li><a href="#34"><b class="cmd">tsv::keylset</b> <i class="arg">varname</i> <i class="arg">keylist</i> <i class="arg">key</i> <i class="arg">value</i> <span class="opt">?key value..?</span></a></li>
 160 </ul>
 161 </div>
 162 </div>
 163 <div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
 164 <p>This section describes commands implementing thread shared variables.
 165 A thread shared variable is very similar to a Tcl array but in
 166 contrast to a Tcl array it is created in shared memory and can
 167 be accessed from many threads at the same time. Important feature of
 168 thread shared variable is that each access to the variable is internaly
 169 protected by a mutex so script programmer does not have to take care
 170 about locking the variable himself.</p>
 171 <p>Thread shared variables are not bound to any thread explicitly. That
 172 means that when a thread which created any of thread shared variables
 173 exits, the variable and associated memory is not unset/reclaimed.
 174 User has to explicitly unset the variable to reclaim the memory
 175 consumed by the variable.</p>
 176 </div>
 177 <div id="section2" class="doctools_section"><h2><a name="section2">ELEMENT COMMANDS</a></h2>
 178 <dl class="doctools_definitions">
 179 <dt><a name="1"><b class="cmd">tsv::names</b> <span class="opt">?pattern?</span></a></dt>
 180 <dd><p>Returns names of shared variables matching optional <span class="opt">?pattern?</span>
 181 or all known variables if pattern is ommited.</p></dd>
 182 <dt><a name="2"><b class="cmd">tsv::object</b> <i class="arg">varname</i> <i class="arg">element</i></a></dt>
 183 <dd><p>Creates object accessor command for the <i class="arg">element</i> in the
 184 shared variable <i class="arg">varname</i>. Using this command, one can apply most
 185 of the other shared variable commands as method functions of
 186 the element object command. The object command is automatically
 187 deleted when the element which this command is pointing to is unset.</p>
 188 <pre class="doctools_example">
 189     % tsv::set foo bar &quot;A shared string&quot;
 190     % set string [tsv::object foo bar]
 191     % $string append &quot; appended&quot;
 192     =&gt; A shared string appended
 193 </pre>
 194 </dd>
 195 <dt><a name="3"><b class="cmd">tsv::set</b> <i class="arg">varname</i> <i class="arg">element</i> <span class="opt">?value?</span></a></dt>
 196 <dd><p>Sets the value of the <i class="arg">element</i> in the shared variable <i class="arg">varname</i>
 197 to <i class="arg">value</i> and returns the value to caller. The <i class="arg">value</i>
 198 may be ommited, in which case the command will return the current
 199 value of the element. If the element cannot be found, error is triggered.</p></dd>
 200 <dt><a name="4"><b class="cmd">tsv::get</b> <i class="arg">varname</i> <i class="arg">element</i> <span class="opt">?namedvar?</span></a></dt>
 201 <dd><p>Retrieves the value of the <i class="arg">element</i> from the shared variable <i class="arg">varname</i>.
 202 If the optional argument <i class="arg">namedvar</i> is given, the value is
 203 stored in the named variable. Return value of the command depends
 204 of the existence of the optional argument <i class="arg">namedvar</i>.
 205 If the argument is ommited and the requested element cannot be found
 206 in the shared array, the command triggers error. If, however, the
 207 optional argument is given on the command line, the command returns
 208 true (1) if the element is found or false (0) if the element is not found.</p></dd>
 209 <dt><a name="5"><b class="cmd">tsv::unset</b> <i class="arg">varname</i> <span class="opt">?element?</span></a></dt>
 210 <dd><p>Unsets the <i class="arg">element</i> from the shared variable <i class="arg">varname</i>.
 211 If the optional element is not given, it deletes the variable.</p></dd>
 212 <dt><a name="6"><b class="cmd">tsv::exists</b> <i class="arg">varname</i> <i class="arg">element</i></a></dt>
 213 <dd><p>Checks wether the <i class="arg">element</i> exists in the shared variable <i class="arg">varname</i>
 214 and returns true (1) if it does or false (0) if it doesn't.</p></dd>
 215 <dt><a name="7"><b class="cmd">tsv::pop</b> <i class="arg">varname</i> <i class="arg">element</i></a></dt>
 216 <dd><p>Returns value of the <i class="arg">element</i> in the shared variable <i class="arg">varname</i>
 217 and unsets the element, all in one atomic operation.</p></dd>
 218 <dt><a name="8"><b class="cmd">tsv::move</b> <i class="arg">varname</i> <i class="arg">oldname</i> <i class="arg">newname</i></a></dt>
 219 <dd><p>Renames the element <i class="arg">oldname</i> to the <i class="arg">newname</i> in the
 220 shared variable <i class="arg">varname</i>. This effectively performs an get/unset/set
 221 sequence of operations but all in one atomic step.</p></dd>
 222 <dt><a name="9"><b class="cmd">tsv::incr</b> <i class="arg">varname</i> <i class="arg">element</i> <span class="opt">?count?</span></a></dt>
 223 <dd><p>Similar to standard Tcl <b class="cmd">incr</b> command but increments the value
 224 of the <i class="arg">element</i> in shared variaboe <i class="arg">varname</i> instead of
 225 the Tcl variable.</p></dd>
 226 <dt><a name="10"><b class="cmd">tsv::append</b> <i class="arg">varname</i> <i class="arg">element</i> <i class="arg">value</i> <span class="opt">?value ...?</span></a></dt>
 227 <dd><p>Similar to standard Tcl <b class="cmd">append</b> command but appends one or more
 228 values to the <i class="arg">element</i> in shared variable <i class="arg">varname</i> instead of the
 229 Tcl variable.</p></dd>
 230 <dt><a name="11"><b class="cmd">tsv::lock</b> <i class="arg">varname</i> <i class="arg">arg</i> <span class="opt">?arg ...?</span></a></dt>
 231 <dd><p>This command concatenates passed arguments and evaluates the
 232 resulting script under the internal mutex protection. During the
 233 script evaluation, the entire shared variable is locked. For shared
 234 variable commands within the script, internal locking is disabled
 235 so no deadlock can occur. It is also allowed to unset the shared
 236 variable from within the script. The shared variable is automatically
 237 created if it did not exists at the time of the first lock operation.</p>
 238 <pre class="doctools_example">
 239     % tsv::lock foo {
 240         tsv::lappend foo bar 1
 241         tsv::lappend foo bar 2
 242         puts stderr [tsv::set foo bar]
 243         tsv::unset foo
 244     }
 245 </pre>
 246 </dd>
 247 <dt><a name="12"><b class="cmd">tsv::handlers</b></a></dt>
 248 <dd><p>Returns the names of all persistent storage handlers enabled at compile time.
 249 See <span class="sectref"><a href="#section4">ARRAY COMMANDS</a></span> for details.</p></dd>
 250 </dl>
 251 </div>
 252 <div id="section3" class="doctools_section"><h2><a name="section3">LIST COMMANDS</a></h2>
 253 <p>Those command are similar to the equivalently named Tcl command. The difference
 254 is that they operate on elements of shared arrays.</p>
 255 <dl class="doctools_definitions">
 256 <dt><a name="13"><b class="cmd">tsv::lappend</b> <i class="arg">varname</i> <i class="arg">element</i> <i class="arg">value</i> <span class="opt">?value ...?</span></a></dt>
 257 <dd><p>Similar to standard Tcl <b class="cmd">lappend</b> command but appends one
 258 or more values to the <i class="arg">element</i> in shared variable <i class="arg">varname</i>
 259 instead of the Tcl variable.</p></dd>
 260 <dt><a name="14"><b class="cmd">tsv::linsert</b> <i class="arg">varname</i> <i class="arg">element</i> <i class="arg">index</i> <i class="arg">value</i> <span class="opt">?value ...?</span></a></dt>
 261 <dd><p>Similar to standard Tcl <b class="cmd">linsert</b> command but inserts one
 262 or more values at the <i class="arg">index</i> list position in the
 263 <i class="arg">element</i> in the shared variable <i class="arg">varname</i> instead of the Tcl variable.</p></dd>
 264 <dt><a name="15"><b class="cmd">tsv::lreplace</b> <i class="arg">varname</i> <i class="arg">element</i> <i class="arg">first</i> <i class="arg">last</i> <span class="opt">?value ...?</span></a></dt>
 265 <dd><p>Similar to standard Tcl <b class="cmd">lreplace</b> command but replaces one
 266 or more values between the <i class="arg">first</i> and <i class="arg">last</i> position
 267 in the <i class="arg">element</i> of the shared variable <i class="arg">varname</i> instead of
 268 the Tcl variable.</p></dd>
 269 <dt><a name="16"><b class="cmd">tsv::llength</b> <i class="arg">varname</i> <i class="arg">element</i></a></dt>
 270 <dd><p>Similar to standard Tcl <b class="cmd">llength</b> command but returns length
 271 of the <i class="arg">element</i> in the shared variable <i class="arg">varname</i> instead of the Tcl
 272 variable.</p></dd>
 273 <dt><a name="17"><b class="cmd">tsv::lindex</b> <i class="arg">varname</i> <i class="arg">element</i> <span class="opt">?index?</span></a></dt>
 274 <dd><p>Similar to standard Tcl <b class="cmd">lindex</b> command but returns the value
 275 at the <i class="arg">index</i> list position of the <i class="arg">element</i> from
 276 the shared variable <i class="arg">varname</i> instead of the Tcl variable.</p></dd>
 277 <dt><a name="18"><b class="cmd">tsv::lrange</b> <i class="arg">varname</i> <i class="arg">element</i> <i class="arg">from</i> <i class="arg">to</i></a></dt>
 278 <dd><p>Similar to standard Tcl <b class="cmd">lrange</b> command but returns values
 279 between <i class="arg">from</i> and <i class="arg">to</i> list positions from the
 280 <i class="arg">element</i> in the shared variable <i class="arg">varname</i> instead of the Tcl variable.</p></dd>
 281 <dt><a name="19"><b class="cmd">tsv::lsearch</b> <i class="arg">varname</i> <i class="arg">element</i> <span class="opt">?options?</span> <i class="arg">pattern</i></a></dt>
 282 <dd><p>Similar to standard Tcl <b class="cmd">lsearch</b> command but searches the <i class="arg">element</i>
 283 in the shared variable <i class="arg">varname</i> instead of the Tcl variable.</p></dd>
 284 <dt><a name="20"><b class="cmd">tsv::lset</b> <i class="arg">varname</i> <i class="arg">element</i> <i class="arg">index</i> <span class="opt">?index ...?</span> <i class="arg">value</i></a></dt>
 285 <dd><p>Similar to standard Tcl <b class="cmd">lset</b> command but sets the <i class="arg">element</i>
 286 in the shared variable <i class="arg">varname</i> instead of the Tcl variable.</p></dd>
 287 <dt><a name="21"><b class="cmd">tsv::lpop</b> <i class="arg">varname</i> <i class="arg">element</i> <span class="opt">?index?</span></a></dt>
 288 <dd><p>Similar to the standard Tcl <b class="cmd">lindex</b> command but in addition to
 289 returning, it also splices the value out of the <i class="arg">element</i>
 290 from the shared variable <i class="arg">varname</i> in one atomic operation.
 291 In contrast to the Tcl <b class="cmd">lindex</b> command, this command returns
 292 no value to the caller.</p></dd>
 293 <dt><a name="22"><b class="cmd">tsv::lpush</b> <i class="arg">varname</i> <i class="arg">element</i> <span class="opt">?index?</span></a></dt>
 294 <dd><p>This command performes the opposite of the <b class="cmd">tsv::lpop</b> command.
 295 As its counterpart, it returns no value to the caller.</p></dd>
 296 </dl>
 297 </div>
 298 <div id="section4" class="doctools_section"><h2><a name="section4">ARRAY COMMANDS</a></h2>
 299 <p>This command supports most of the options of the standard Tcl
 300 <b class="cmd">array</b> command. In addition to those, it allows binding
 301 a shared variable to some persisten storage databases. Currently the persistent
 302 options supported are the famous GNU Gdbm and LMDB. These options have to be
 303 selected during the package compilation time.
 304 The implementation provides hooks for defining other persistency layers, if
 305 needed.</p>
 306 <dl class="doctools_definitions">
 307 <dt><a name="23"><b class="cmd">tsv::array set</b> <i class="arg">varname</i> <i class="arg">list</i></a></dt>
 308 <dd><p>Does the same as standard Tcl <b class="cmd">array set</b>.</p></dd>
 309 <dt><a name="24"><b class="cmd">tsv::array get</b> <i class="arg">varname</i> <span class="opt">?pattern?</span></a></dt>
 310 <dd><p>Does the same as standard Tcl <b class="cmd">array get</b>.</p></dd>
 311 <dt><a name="25"><b class="cmd">tsv::array names</b> <i class="arg">varname</i> <span class="opt">?pattern?</span></a></dt>
 312 <dd><p>Does the same as standard Tcl <b class="cmd">array names</b>.</p></dd>
 313 <dt><a name="26"><b class="cmd">tsv::array size</b> <i class="arg">varname</i></a></dt>
 314 <dd><p>Does the same as standard Tcl <b class="cmd">array size</b>.</p></dd>
 315 <dt><a name="27"><b class="cmd">tsv::array reset</b> <i class="arg">varname</i> <i class="arg">list</i></a></dt>
 316 <dd><p>Does the same as standard Tcl <b class="cmd">array set</b> but it clears
 317 the <i class="arg">varname</i> and sets new values from the list atomically.</p></dd>
 318 <dt><a name="28"><b class="cmd">tsv::array bind</b> <i class="arg">varname</i> <i class="arg">handle</i></a></dt>
 319 <dd><p>Binds the <i class="arg">varname</i> to the persistent storage <i class="arg">handle</i>.
 320 The format of the <i class="arg">handle</i> is &lt;handler&gt;:&lt;address&gt;, where &lt;handler&gt; is
 321 &quot;gdbm&quot; for GNU Gdbm and &quot;lmdb&quot; for LMDB and &lt;address&gt; is the path to the
 322 database file.</p></dd>
 323 <dt><a name="29"><b class="cmd">tsv::array unbind</b> <i class="arg">varname</i></a></dt>
 324 <dd><p>Unbinds the shared <i class="arg">array</i> from its bound persistent storage.</p></dd>
 325 <dt><a name="30"><b class="cmd">tsv::array isbound</b> <i class="arg">varname</i></a></dt>
 326 <dd><p>Returns true (1) if the shared <i class="arg">varname</i> is bound to some
 327 persistent storage or zero (0) if not.</p></dd>
 328 </dl>
 329 </div>
 330 <div id="section5" class="doctools_section"><h2><a name="section5">KEYED LIST COMMANDS</a></h2>
 331 <p>Keyed list commands are borrowed from the TclX package. Keyed lists provide
 332 a structured data type built upon standard Tcl lists. This is a functionality
 333 similar to structs in the C programming language.</p>
 334 <p>A keyed list is a list in which each element contains a key and value
 335 pair. These element pairs are stored as lists themselves, where the key
 336 is the first element of the list, and the value is the second. The
 337 key-value pairs are referred to as fields.  This is an example of a
 338 keyed list:</p>
 339 <pre class="doctools_example">
 340     {{NAME  {Frank  Zappa}} {JOB {musician and composer}}}
 341 </pre>
 342 <p>Fields may contain subfields; `.' is the separator character. Subfields
 343 are actually fields  where the value is another keyed list. Thus the
 344 following list has the top level fields ID and NAME, and subfields
 345 NAME.FIRST and NAME.LAST:</p>
 346 <pre class="doctools_example">
 347     {ID 106} {NAME {{FIRST Frank} {LAST Zappa}}}
 348 </pre>
 349 <p>There is no limit to the recursive depth of subfields,
 350 allowing one to build complex data structures. Keyed lists are constructed
 351 and accessed via a number of commands. All  keyed  list management
 352 commands take the name of the variable containing the keyed list as an
 353 argument (i.e. passed by reference), rather than passing the list directly.</p>
 354 <dl class="doctools_definitions">
 355 <dt><a name="31"><b class="cmd">tsv::keyldel</b> <i class="arg">varname</i> <i class="arg">keylist</i> <i class="arg">key</i></a></dt>
 356 <dd><p>Delete the field specified by <i class="arg">key</i> from the keyed list <i class="arg">keylist</i>
 357 in the shared variable <i class="arg">varname</i>.
 358 This removes both the key and the value from the keyed list.</p></dd>
 359 <dt><a name="32"><b class="cmd">tsv::keylget</b> <i class="arg">varname</i> <i class="arg">keylist</i> <i class="arg">key</i> <span class="opt">?retvar?</span></a></dt>
 360 <dd><p>Return the value associated with <i class="arg">key</i> from the keyed list <i class="arg">keylist</i>
 361 in the shared variable <i class="arg">varname</i>.
 362 If the optional <i class="arg">retvar</i> is not specified, then the value will be
 363 returned as the result of the command. In this case, if key is not found
 364 in the list, an error will result.</p>
 365 <p>If <i class="arg">retvar</i> is specified and <i class="arg">key</i> is in the list, then the value
 366 is returned in the variable <i class="arg">retvar</i> and the command returns 1 if the
 367 key was present within the list. If <i class="arg">key</i> isn't in the list, the
 368 command will return 0, and <i class="arg">retvar</i> will be left unchanged. If {} is
 369 specified for <i class="arg">retvar</i>, the value is not returned, allowing the Tcl
 370 programmer to determine if a <i class="arg">key</i> is present in a keyed list without
 371 setting a variable as a side-effect.</p></dd>
 372 <dt><a name="33"><b class="cmd">tsv::keylkeys</b> <i class="arg">varname</i> <i class="arg">keylist</i> <span class="opt">?key?</span></a></dt>
 373 <dd><p>Return  the a list of the keys in the keyed list <i class="arg">keylist</i> in the
 374 shared variable <i class="arg">varname</i>. If <i class="arg">key</i> is specified, then it is
 375 the name of a key field who's subfield keys are to be retrieved.</p></dd>
 376 <dt><a name="34"><b class="cmd">tsv::keylset</b> <i class="arg">varname</i> <i class="arg">keylist</i> <i class="arg">key</i> <i class="arg">value</i> <span class="opt">?key value..?</span></a></dt>
 377 <dd><p>Set the value associated with <i class="arg">key</i>, in the keyed list <i class="arg">keylist</i>
 378 to <i class="arg">value</i>. If the <i class="arg">keylist</i> does not exists, it is created.
 379 If <i class="arg">key</i> is not currently in the list, it will be added. If it already
 380 exists, <i class="arg">value</i> replaces the existing value. Multiple keywords and
 381 values may be specified, if desired.</p></dd>
 382 </dl>
 383 </div>
 384 <div id="section6" class="doctools_section"><h2><a name="section6">DISCUSSION</a></h2>
 385 <p>The current implementation of thread shared variables allows for easy and
 386 convenient access to data shared between different threads.
 387 Internally, the data is stored in Tcl objects and all package commands
 388 operate on internal data representation, thus minimizing shimmering and
 389 improving performance. Special care has been taken to assure that all
 390 object data is properly locked and deep-copied when moving objects between
 391 threads.</p>
 392 <p>Due to the internal design of the Tcl core, there is no provision of full
 393 integration of shared variables within the Tcl syntax, unfortunately. All
 394 access to shared data must be performed with the supplied package commands.
 395 Also, variable traces are not supported. But even so, benefits of easy,
 396 simple and safe shared data manipulation outweights imposed limitations.</p>
 397 </div>
 398 <div id="section7" class="doctools_section"><h2><a name="section7">CREDITS</a></h2>
 399 <p>Thread shared variables are inspired by the nsv interface found in
 400 AOLserver, a highly scalable Web server from America Online.</p>
 401 </div>
 402 <div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
 403 <p>thread, tpool, ttrace</p>
 404 </div>
 405 <div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
 406 <p>locking, synchronization, thread shared data, threads</p>
 407 </div>
 408 </div></body></html>
 409