util/X86LINUX64/man/mann/tsv.n

   1 '\"
   2 '\" Generated from file '' by tcllib/doctools with format 'nroff'
   3 '\"
   4 '\" -*- tcl -*- doctools manpage
   5 '\" The definitions below are for supplemental macros used in Tcl/Tk
   6 '\" manual entries.
   7 '\"
   8 '\" .AP type name in/out ?indent?
   9 '\"     Start paragraph describing an argument to a library procedure.
  10 '\"     type is type of argument (int, etc.), in/out is either "in", "out",
  11 '\"     or "in/out" to describe whether procedure reads or modifies arg,
  12 '\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  13 '\"     needed;  use .AS below instead)
  14 '\"
  15 '\" .AS ?type? ?name?
  16 '\"     Give maximum sizes of arguments for setting tab stops.  Type and
  17 '\"     name are examples of largest possible arguments that will be passed
  18 '\"     to .AP later.  If args are omitted, default tab stops are used.
  19 '\"
  20 '\" .BS
  21 '\"     Start box enclosure.  From here until next .BE, everything will be
  22 '\"     enclosed in one large box.
  23 '\"
  24 '\" .BE
  25 '\"     End of box enclosure.
  26 '\"
  27 '\" .CS
  28 '\"     Begin code excerpt.
  29 '\"
  30 '\" .CE
  31 '\"     End code excerpt.
  32 '\"
  33 '\" .VS ?version? ?br?
  34 '\"     Begin vertical sidebar, for use in marking newly-changed parts
  35 '\"     of man pages.  The first argument is ignored and used for recording
  36 '\"     the version when the .VS was added, so that the sidebars can be
  37 '\"     found and removed when they reach a certain age.  If another argument
  38 '\"     is present, then a line break is forced before starting the sidebar.
  39 '\"
  40 '\" .VE
  41 '\"     End of vertical sidebar.
  42 '\"
  43 '\" .DS
  44 '\"     Begin an indented unfilled display.
  45 '\"
  46 '\" .DE
  47 '\"     End of indented unfilled display.
  48 '\"
  49 '\" .SO
  50 '\"     Start of list of standard options for a Tk widget.  The
  51 '\"     options follow on successive lines, in four columns separated
  52 '\"     by tabs.
  53 '\"
  54 '\" .SE
  55 '\"     End of list of standard options for a Tk widget.
  56 '\"
  57 '\" .OP cmdName dbName dbClass
  58 '\"     Start of description of a specific option.  cmdName gives the
  59 '\"     option's name as specified in the class command, dbName gives
  60 '\"     the option's name in the option database, and dbClass gives
  61 '\"     the option's class in the option database.
  62 '\"
  63 '\" .UL arg1 arg2
  64 '\"     Print arg1 underlined, then print arg2 normally.
  65 '\"
  66 '\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  67 .if t .wh -1.3i ^B
  68 .nr ^l \n(.l
  69 .ad b
  70 '\"     # Start an argument description
  71 .de AP
  72 .ie !"\\$4"" .TP \\$4
  73 .el \{\
  74 .   ie !"\\$2"" .TP \\n()Cu
  75 .   el          .TP 15
  76 .\}
  77 .ta \\n()Au \\n()Bu
  78 .ie !"\\$3"" \{\
  79 \&\\$1  \\fI\\$2\\fP    (\\$3)
  80 .\".b
  81 .\}
  82 .el \{\
  83 .br
  84 .ie !"\\$2"" \{\
  85 \&\\$1  \\fI\\$2\\fP
  86 .\}
  87 .el \{\
  88 \&\\fI\\$1\\fP
  89 .\}
  90 .\}
  91 ..
  92 '\"     # define tabbing values for .AP
  93 .de AS
  94 .nr )A 10n
  95 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  96 .nr )B \\n()Au+15n
  97 .\"
  98 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  99 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 100 ..
 101 .AS Tcl_Interp Tcl_CreateInterp in/out
 102 '\"     # BS - start boxed text
 103 '\"     # ^y = starting y location
 104 '\"     # ^b = 1
 105 .de BS
 106 .br
 107 .mk ^y
 108 .nr ^b 1u
 109 .if n .nf
 110 .if n .ti 0
 111 .if n \l'\\n(.lu\(ul'
 112 .if n .fi
 113 ..
 114 '\"     # BE - end boxed text (draw box now)
 115 .de BE
 116 .nf
 117 .ti 0
 118 .mk ^t
 119 .ie n \l'\\n(^lu\(ul'
 120 .el \{\
 121 .\"     Draw four-sided box normally, but don't draw top of
 122 .\"     box if the box started on an earlier page.
 123 .ie !\\n(^b-1 \{\
 124 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 125 .\}
 126 .el \}\
 127 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 128 .\}
 129 .\}
 130 .fi
 131 .br
 132 .nr ^b 0
 133 ..
 134 '\"     # VS - start vertical sidebar
 135 '\"     # ^Y = starting y location
 136 '\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 137 .de VS
 138 .if !"\\$2"" .br
 139 .mk ^Y
 140 .ie n 'mc \s12\(br\s0
 141 .el .nr ^v 1u
 142 ..
 143 '\"     # VE - end of vertical sidebar
 144 .de VE
 145 .ie n 'mc
 146 .el \{\
 147 .ev 2
 148 .nf
 149 .ti 0
 150 .mk ^t
 151 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 152 .sp -1
 153 .fi
 154 .ev
 155 .\}
 156 .nr ^v 0
 157 ..
 158 '\"     # Special macro to handle page bottom:  finish off current
 159 '\"     # box/sidebar if in box/sidebar mode, then invoked standard
 160 '\"     # page bottom macro.
 161 .de ^B
 162 .ev 2
 163 'ti 0
 164 'nf
 165 .mk ^t
 166 .if \\n(^b \{\
 167 .\"     Draw three-sided box if this is the box's first page,
 168 .\"     draw two sides but no top otherwise.
 169 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 170 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 171 .\}
 172 .if \\n(^v \{\
 173 .nr ^x \\n(^tu+1v-\\n(^Yu
 174 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 175 .\}
 176 .bp
 177 'fi
 178 .ev
 179 .if \\n(^b \{\
 180 .mk ^y
 181 .nr ^b 2
 182 .\}
 183 .if \\n(^v \{\
 184 .mk ^Y
 185 .\}
 186 ..
 187 '\"     # DS - begin display
 188 .de DS
 189 .RS
 190 .nf
 191 .sp
 192 ..
 193 '\"     # DE - end display
 194 .de DE
 195 .fi
 196 .RE
 197 .sp
 198 ..
 199 '\"     # SO - start of list of standard options
 200 .de SO
 201 .SH "STANDARD OPTIONS"
 202 .LP
 203 .nf
 204 .ta 5.5c 11c
 205 .ft B
 206 ..
 207 '\"     # SE - end of list of standard options
 208 .de SE
 209 .fi
 210 .ft R
 211 .LP
 212 See the \\fBoptions\\fR manual entry for details on the standard options.
 213 ..
 214 '\"     # OP - start of full description for a single option
 215 .de OP
 216 .LP
 217 .nf
 218 .ta 4c
 219 Command-Line Name:      \\fB\\$1\\fR
 220 Database Name:  \\fB\\$2\\fR
 221 Database Class: \\fB\\$3\\fR
 222 .fi
 223 .IP
 224 ..
 225 '\"     # CS - begin code excerpt
 226 .de CS
 227 .RS
 228 .nf
 229 .ta .25i .5i .75i 1i
 230 .if t .ft C
 231 ..
 232 '\"     # CE - end code excerpt
 233 .de CE
 234 .fi
 235 .if t .ft R
 236 .RE
 237 ..
 238 .de UL
 239 \\$1\l'|0\(ul'\\$2
 240 ..
 241
 242 .TH "tsv" n 2.7  "Tcl Threading"
 243 .BS
 244 .SH "NAME"
 245 tsv \-
 246 Part of the Tcl threading extension allowing script level
 247 manipulation of data shared between threads.
 248 .SH "SYNOPSIS"
 249 package require \fBTcl  8.4\fR
 250 .sp
 251 package require \fBThread  ?2.7?\fR
 252 .sp
 253 \fBtsv::names\fR ?pattern?
 254 .sp
 255 \fBtsv::object\fR \fIvarname\fR \fIelement\fR
 256 .sp
 257 \fBtsv::set\fR \fIvarname\fR \fIelement\fR ?value?
 258 .sp
 259 \fBtsv::get\fR \fIvarname\fR \fIelement\fR ?namedvar?
 260 .sp
 261 \fBtsv::unset\fR \fIvarname\fR ?element?
 262 .sp
 263 \fBtsv::exists\fR \fIvarname\fR \fIelement\fR
 264 .sp
 265 \fBtsv::pop\fR \fIvarname\fR \fIelement\fR
 266 .sp
 267 \fBtsv::move\fR \fIvarname\fR \fIoldname\fR \fInewname\fR
 268 .sp
 269 \fBtsv::incr\fR \fIvarname\fR \fIelement\fR ?count?
 270 .sp
 271 \fBtsv::append\fR \fIvarname\fR \fIelement\fR \fIvalue\fR ?value ...?
 272 .sp
 273 \fBtsv::lock\fR \fIvarname\fR \fIarg\fR ?arg ...?
 274 .sp
 275 \fBtsv::lappend\fR \fIvarname\fR \fIelement\fR \fIvalue\fR ?value ...?
 276 .sp
 277 \fBtsv::linsert\fR \fIvarname\fR \fIelement\fR \fIindex\fR \fIvalue\fR ?value ...?
 278 .sp
 279 \fBtsv::lreplace\fR \fIvarname\fR \fIelement\fR \fIfirst\fR \fIlast\fR ?value ...?
 280 .sp
 281 \fBtsv::llength\fR \fIvarname\fR \fIelement\fR
 282 .sp
 283 \fBtsv::lindex\fR \fIvarname\fR \fIelement\fR ?index?
 284 .sp
 285 \fBtsv::lrange\fR \fIvarname\fR \fIelement\fR \fIfrom\fR \fIto\fR
 286 .sp
 287 \fBtsv::lsearch\fR \fIvarname\fR \fIelement\fR ?options? \fIpattern\fR
 288 .sp
 289 \fBtsv::lset\fR \fIvarname\fR \fIelement\fR \fIindex\fR ?index ...? \fIvalue\fR
 290 .sp
 291 \fBtsv::lpop\fR \fIvarname\fR \fIelement\fR ?index?
 292 .sp
 293 \fBtsv::lpush\fR \fIvarname\fR \fIelement\fR ?index?
 294 .sp
 295 \fBtsv::array set\fR \fIvarname\fR \fIlist\fR
 296 .sp
 297 \fBtsv::array get\fR \fIvarname\fR ?pattern?
 298 .sp
 299 \fBtsv::array names\fR \fIvarname\fR ?pattern?
 300 .sp
 301 \fBtsv::array size\fR \fIvarname\fR
 302 .sp
 303 \fBtsv::array reset\fR \fIvarname\fR \fIlist\fR
 304 .sp
 305 \fBtsv::array bind\fR \fIvarname\fR \fIhandle\fR
 306 .sp
 307 \fBtsv::array unbind\fR \fIvarname\fR
 308 .sp
 309 \fBtsv::array isbound\fR \fIvarname\fR
 310 .sp
 311 \fBtsv::keyldel\fR \fIvarname\fR \fIkeylist\fR \fIkey\fR
 312 .sp
 313 \fBtsv::keylget\fR \fIvarname\fR \fIkeylist\fR \fIkey\fR ?retvar?
 314 .sp
 315 \fBtsv::keylkeys\fR \fIvarname\fR \fIkeylist\fR ?key?
 316 .sp
 317 \fBtsv::keylset\fR \fIvarname\fR \fIkeylist\fR \fIkey\fR \fIvalue\fR ?key value..?
 318 .sp
 319 .BE
 320 .SH "DESCRIPTION"
 321 This section describes commands implementing thread shared variables.
 322 A thread shared variable is very similar to a Tcl array but in
 323 contrast to a Tcl array it is created in shared memory and can
 324 be accessed from many threads at the same time. Important feature of
 325 thread shared variable is that each access to the variable is internaly
 326 protected by a mutex so script programmer does not have to take care
 327 about locking the variable himself.
 328 .PP
 329 Thread shared variables are not bound to any thread explicitly. That
 330 means that when a thread which created any of thread shared variables
 331 exits, the variable and associated memory is not unset/reclaimed.
 332 User has to explicitly unset the variable to reclaim the memory
 333 consumed by the variable.
 334 .SH "ELEMENT COMMANDS"
 335 .TP
 336 \fBtsv::names\fR ?pattern?
 337 Returns names of shared variables matching optional ?pattern?
 338 or all known variables if pattern is ommited.
 339 .TP
 340 \fBtsv::object\fR \fIvarname\fR \fIelement\fR
 341 Creates object accessor command for the \fIelement\fR in the
 342 shared variable \fIvarname\fR. Using this command, one can apply most
 343 of the other shared variable commands as method functions of
 344 the element object command. The object command is automatically
 345 deleted when the element which this command is pointing to is unset.
 346 .nf
 347     % tsv::set foo bar "A shared string"
 348     % set string [tsv::object foo bar]
 349     % $string append " appended"
 350     => A shared string appended
 351 .fi
 352 .TP
 353 \fBtsv::set\fR \fIvarname\fR \fIelement\fR ?value?
 354 Sets the value of the \fIelement\fR in the shared variable \fIvarname\fR
 355 to \fIvalue\fR and returns the value to caller. The \fIvalue\fR
 356 may be ommited, in which case the command will return the current
 357 value of the element. If the element cannot be found, error is triggered.
 358 .TP
 359 \fBtsv::get\fR \fIvarname\fR \fIelement\fR ?namedvar?
 360 Retrieves the value of the \fIelement\fR from the shared variable \fIvarname\fR.
 361 If the optional argument \fInamedvar\fR is given, the value is
 362 stored in the named variable. Return value of the command depends
 363 of the existence of the optional argument \fInamedvar\fR.
 364 If the argument is ommited and the requested element cannot be found
 365 in the shared array, the command triggers error. If, however, the
 366 optional argument is given on the command line, the command returns
 367 true (1) if the element is found or false (0) if the element is not found.
 368 .TP
 369 \fBtsv::unset\fR \fIvarname\fR ?element?
 370 Unsets the \fIelement\fR from the shared variable \fIvarname\fR.
 371 If the optional element is not given, it deletes the variable.
 372 .TP
 373 \fBtsv::exists\fR \fIvarname\fR \fIelement\fR
 374 Checks wether the \fIelement\fR exists in the shared variable \fIvarname\fR
 375 and returns true (1) if it does or false (0) if it doesn't.
 376 .TP
 377 \fBtsv::pop\fR \fIvarname\fR \fIelement\fR
 378 Returns value of the \fIelement\fR in the shared variable \fIvarname\fR
 379 and unsets the element, all in one atomic operation.
 380 .TP
 381 \fBtsv::move\fR \fIvarname\fR \fIoldname\fR \fInewname\fR
 382 Renames the element \fIoldname\fR to the \fInewname\fR in the
 383 shared variable \fIvarname\fR. This effectively performs an get/unset/set
 384 sequence of operations but all in one atomic step.
 385 .TP
 386 \fBtsv::incr\fR \fIvarname\fR \fIelement\fR ?count?
 387 Similar to standard Tcl \fBincr\fR command but increments the value
 388 of the \fIelement\fR in shared variaboe \fIvarname\fR instead of
 389 the Tcl variable.
 390 .TP
 391 \fBtsv::append\fR \fIvarname\fR \fIelement\fR \fIvalue\fR ?value ...?
 392 Similar to standard Tcl \fBappend\fR command but appends one or more
 393 values to the \fIelement\fR in shared variable \fIvarname\fR instead of the
 394 Tcl variable.
 395 .TP
 396 \fBtsv::lock\fR \fIvarname\fR \fIarg\fR ?arg ...?
 397 This command concatenates passed arguments and evaluates the
 398 resulting script under the internal mutex protection. During the
 399 script evaluation, the entire shared variable is locked. For shared
 400 variable commands within the script, internal locking is disabled
 401 so no deadlock can occur. It is also allowed to unset the shared
 402 variable from within the script. The shared variable is automatically
 403 created if it did not exists at the time of the first lock operation.
 404 .nf
 405     % tsv::lock foo {
 406         tsv::lappend foo bar 1
 407         tsv::lappend foo bar 2
 408         puts stderr [tsv::set foo bar]
 409         tsv::unset foo
 410     }
 411 .fi
 412 .SH "LIST COMMANDS"
 413 Those command are similar to the equivalently named Tcl command. The difference
 414 is that they operate on elements of shared arrays.
 415 .TP
 416 \fBtsv::lappend\fR \fIvarname\fR \fIelement\fR \fIvalue\fR ?value ...?
 417 Similar to standard Tcl \fBlappend\fR command but appends one
 418 or more values to the \fIelement\fR in shared variable \fIvarname\fR
 419 instead of the Tcl variable.
 420 .TP
 421 \fBtsv::linsert\fR \fIvarname\fR \fIelement\fR \fIindex\fR \fIvalue\fR ?value ...?
 422 Similar to standard Tcl \fBlinsert\fR command but inserts one
 423 or more values at the \fIindex\fR list position in the
 424 \fIelement\fR in the shared variable \fIvarname\fR instead of the Tcl variable.
 425 .TP
 426 \fBtsv::lreplace\fR \fIvarname\fR \fIelement\fR \fIfirst\fR \fIlast\fR ?value ...?
 427 Similar to standard Tcl \fBlreplace\fR command but replaces one
 428 or more values between the \fIfirst\fR and \fIlast\fR position
 429 in the \fIelement\fR of the shared variable \fIvarname\fR instead of
 430 the Tcl variable.
 431 .TP
 432 \fBtsv::llength\fR \fIvarname\fR \fIelement\fR
 433 Similar to standard Tcl \fBllength\fR command but returns length
 434 of the \fIelement\fR in the shared variable \fIvarname\fR instead of the Tcl
 435 variable.
 436 .TP
 437 \fBtsv::lindex\fR \fIvarname\fR \fIelement\fR ?index?
 438 Similar to standard Tcl \fBlindex\fR command but returns the value
 439 at the \fIindex\fR list position of the \fIelement\fR from
 440 the shared variable \fIvarname\fR instead of the Tcl variable.
 441 .TP
 442 \fBtsv::lrange\fR \fIvarname\fR \fIelement\fR \fIfrom\fR \fIto\fR
 443 Similar to standard Tcl \fBlrange\fR command but returns values
 444 between \fIfrom\fR and \fIto\fR list positions from the
 445 \fIelement\fR in the shared variable \fIvarname\fR instead of the Tcl variable.
 446 .TP
 447 \fBtsv::lsearch\fR \fIvarname\fR \fIelement\fR ?options? \fIpattern\fR
 448 Similar to standard Tcl \fBlsearch\fR command but searches the \fIelement\fR
 449 in the shared variable \fIvarname\fR instead of the Tcl variable.
 450 .TP
 451 \fBtsv::lset\fR \fIvarname\fR \fIelement\fR \fIindex\fR ?index ...? \fIvalue\fR
 452 Similar to standard Tcl \fBlset\fR command but sets the \fIelement\fR
 453 in the shared variable \fIvarname\fR instead of the Tcl variable.
 454 .TP
 455 \fBtsv::lpop\fR \fIvarname\fR \fIelement\fR ?index?
 456 Similar to the standard Tcl \fBlindex\fR command but in addition to
 457 returning, it also splices the value out of the \fIelement\fR
 458 from the shared variable \fIvarname\fR in one atomic operation.
 459 In contrast to the Tcl \fBlindex\fR command, this command returns
 460 no value to the caller.
 461 .TP
 462 \fBtsv::lpush\fR \fIvarname\fR \fIelement\fR ?index?
 463 This command performes the opposite of the \fBtsv::lpop\fR command.
 464 As its counterpart, it returns no value to the caller.
 465 .SH "ARRAY COMMANDS"
 466 This command supports most of the options of the standard Tcl
 467 \fBarray\fR command. In addition to those, it allows binding
 468 a shared variable to some persisten storage databases. Currently
 469 the only persistent option supported is the famous GNU Gdbm
 470 database. This option has to be selected during the package
 471 compilation time. The implementation provides hooks for
 472 defining other persistency layers, if needed.
 473 .TP
 474 \fBtsv::array set\fR \fIvarname\fR \fIlist\fR
 475 Does the same as standard Tcl \fBarray set\fR.
 476 .TP
 477 \fBtsv::array get\fR \fIvarname\fR ?pattern?
 478 Does the same as standard Tcl \fBarray get\fR.
 479 .TP
 480 \fBtsv::array names\fR \fIvarname\fR ?pattern?
 481 Does the same as standard Tcl \fBarray names\fR.
 482 .TP
 483 \fBtsv::array size\fR \fIvarname\fR
 484 Does the same as standard Tcl \fBarray size\fR.
 485 .TP
 486 \fBtsv::array reset\fR \fIvarname\fR \fIlist\fR
 487 Does the same as standard Tcl \fBarray set\fR but it clears
 488 the \fIvarname\fR and sets new values from the list atomically.
 489 .TP
 490 \fBtsv::array bind\fR \fIvarname\fR \fIhandle\fR
 491 Binds the \fIvarname\fR to the persistent storage \fIhandle\fR.
 492 The format of the \fIhandle\fR is <handler>:<address>. For the built-in
 493 GNU Gdbm persistence layer, the format of the handle is "gdbm:<path>"
 494 where <path> is the path to the Gdbm database file.
 495 .TP
 496 \fBtsv::array unbind\fR \fIvarname\fR
 497 Unbinds the shared \fIarray\fR from its bound persistent storage.
 498 .TP
 499 \fBtsv::array isbound\fR \fIvarname\fR
 500 Returns true (1) if the shared \fIvarname\fR is bound to some
 501 persistent storage or zero (0) if not.
 502 .SH "KEYED LIST COMMANDS"
 503 Keyed list commands are borrowed from the TclX package. Keyed lists provide
 504 a structured data type built upon standard Tcl lists. This is a functionality
 505 similar to structs in the C programming language.
 506 .PP
 507 A keyed list is a list in which each element contains a key and value
 508 pair. These element pairs are stored as lists themselves, where the key
 509 is the first element of the list, and the value is the second. The
 510 key-value pairs are referred to as fields.  This is an example of a
 511 keyed list:
 512 .nf
 513     {{NAME  {Frank  Zappa}} {JOB {musician and composer}}}
 514 .fi
 515 Fields may contain subfields; `.' is the separator character. Subfields
 516 are actually fields  where the value is another keyed list. Thus the
 517 following list has the top level fields ID and NAME, and subfields
 518 NAME.FIRST and NAME.LAST:
 519 .nf
 520     {ID 106} {NAME {{FIRST Frank} {LAST Zappa}}}
 521 .fi
 522 There is no limit to the recursive depth of subfields,
 523 allowing one to build complex data structures. Keyed lists are constructed
 524 and accessed via a number of commands. All  keyed  list management
 525 commands take the name of the variable containing the keyed list as an
 526 argument (i.e. passed by reference), rather than passing the list directly.
 527 .TP
 528 \fBtsv::keyldel\fR \fIvarname\fR \fIkeylist\fR \fIkey\fR
 529 Delete the field specified by \fIkey\fR from the keyed list \fIkeylist\fR
 530 in the shared variable \fIvarname\fR.
 531 This removes both the key and the value from the keyed list.
 532 .TP
 533 \fBtsv::keylget\fR \fIvarname\fR \fIkeylist\fR \fIkey\fR ?retvar?
 534 Return the value associated with \fIkey\fR from the keyed list \fIkeylist\fR
 535 in the shared variable \fIvarname\fR.
 536 If the optional \fIretvar\fR is not specified, then the value will be
 537 returned as the result of the command. In this case, if key is not found
 538 in the list, an error will result.
 539 .sp
 540 If \fIretvar\fR is specified and \fIkey\fR is in the list, then the value
 541 is returned in the variable \fIretvar\fR and the command returns 1 if the
 542 key was present within the list. If \fIkey\fR isn't in the list, the
 543 command will return 0, and \fIretvar\fR will be left unchanged. If {} is
 544 specified for \fIretvar\fR, the value is not returned, allowing the Tcl
 545 programmer to determine if a \fIkey\fR is present in a keyed list without
 546 setting a variable as a side-effect.
 547 .TP
 548 \fBtsv::keylkeys\fR \fIvarname\fR \fIkeylist\fR ?key?
 549 Return  the a list of the keys in the keyed list \fIkeylist\fR in the
 550 shared variable \fIvarname\fR. If \fIkey\fR is specified, then it is
 551 the name of a key field who's subfield keys are to be retrieved.
 552 .TP
 553 \fBtsv::keylset\fR \fIvarname\fR \fIkeylist\fR \fIkey\fR \fIvalue\fR ?key value..?
 554 Set the value associated with \fIkey\fR, in the keyed list \fIkeylist\fR
 555 to \fIvalue\fR. If the \fIkeylist\fR does not exists, it is created.
 556 If \fIkey\fR is not currently in the list, it will be added. If it already
 557 exists, \fIvalue\fR replaces the existing value. Multiple keywords and
 558 values may be specified, if desired.
 559 .SH "DISCUSSION"
 560 The current implementation of thread shared variables allows for easy and
 561 convenient access to data shared between different threads.
 562 Internally, the data is stored in Tcl objects and all package commands
 563 operate on internal data representation, thus minimizing shimmering and
 564 improving performance. Special care has been taken to assure that all
 565 object data is properly locked and deep-copied when moving objects between
 566 threads.
 567 .PP
 568 Due to the internal design of the Tcl core, there is no provision of full
 569 integration of shared variables within the Tcl syntax, unfortunately. All
 570 access to shared data must be performed with the supplied package commands.
 571 Also, variable traces are not supported. But even so, benefits of easy,
 572 simple and safe shared data manipulation outweights imposed limitations.
 573 .SH "CREDITS"
 574 Thread shared variables are inspired by the nsv interface found in
 575 AOLserver, a highly scalable Web server from America Online.
 576 .SH "SEE ALSO"
 577 thread, tpool, ttrace
 578 .SH "KEYWORDS"
 579 locking, synchronization, thread shared data, threads