Manual Pages for UNIX Darwin command on man tsv

tsv(n) tsv(n)

NAME

tsv - Part of the Tcl threading extension allowing script level manipu-

lation of data shared between threads.

SYNOPSIS

package require TTccll 88..33 package require TThhrreeaadd ??22..66?? ttssvv::::nnaammeess ?pattern? ttssvv::::oobbjjeecctt varname element ttssvv::::sseett varname element ?value? ttssvv::::ggeett varname element ?namedvar? ttssvv::::uunnsseett varname ?element? ttssvv::::eexxiissttss varname element ttssvv::::ppoopp varname element ttssvv::::mmoovvee varname oldname newname ttssvv::::iinnccrr varname element ?count? ttssvv::::aappppeenndd varname element value ?value ...? ttssvv::::lloocckk varname arg ?arg ...? ttssvv::::llaappppeenndd varname element value ?value ...? ttssvv::::lliinnsseerrtt varname element index value ?value ...? ttssvv::::llrreeppllaaccee varname element first last ?value ...? ttssvv::::lllleennggtthh varname element ttssvv::::lliinnddeexx varname element ?index? ttssvv::::llrraannggee varname element from to ttssvv::::llsseeaarrcchh varname element ?options? pattern ttssvv::::llsseett varname element index ?index ...? value ttssvv::::llppoopp varname element ?index? ttssvv::::llppuusshh varname element ?index? ttssvv::::aarrrraayy sseett varname list ttssvv::::aarrrraayy ggeett varname ?pattern? ttssvv::::aarrrraayy nnaammeess varname ?pattern? ttssvv::::aarrrraayy ssiizzee varname ttssvv::::aarrrraayy rreesseett varname list ttssvv::::aarrrraayy bbiinndd varname handle ttssvv::::aarrrraayy uunnbbiinndd varname ttssvv::::aarrrraayy iissbboouunndd varname ttssvv::::kkeeyyllddeell varname keylist key ttssvv::::kkeeyyllggeett varname keylist key ?retvar? ttssvv::::kkeeyyllkkeeyyss varname keylist ?key? ttssvv::::kkeeyyllsseett varname keylist key value ?key value..?

DESCRIPTION

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 vari-

able is that each access to the variable is internaly 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. EELLEEMMEENNTT CCOOMMMMAANNDDSS ttssvv::::nnaammeess ?pattern? Returns names of shared variables matching optional ?pattern? or all known variables if pattern is ommited. ttssvv::::oobbjjeecctt 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 ele-

ment 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 ttssvv::::sseett varname element ?value? Sets the value of the element in the shared variable varname to value and returns the value to caller. The value may be ommited, in which case the command will return the current value of the element. If the element cannot be found, error is triggered. ttssvv::::ggeett varname element ?namedvar?

Retrieves the value of the element from the shared variable var-

name. 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 ommited and the requested element cannot be

found in the shared array, the command triggers error. If, how-

ever, 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. ttssvv::::uunnsseett varname ?element? Unsets the element from the shared variable varname. If the optional element is not given, it deletes the variable. ttssvv::::eexxiissttss varname element Checks wether the element exists in the shared variable varname and returns true (1) if it does or false (0) if it doesn't. ttssvv::::ppoopp varname element Returns value of the element in the shared variable varname and unsets the element, all in one atomic operation. ttssvv::::mmoovvee varname oldname newname

Renames the element oldname to the newname in the shared vari-

able varname. This effectively performs an get/unset/set sequence of operations but all in one atomic step. ttssvv::::iinnccrr varname element ?count? Similar to standard Tcl iinnccrr command but increments the value of

the element in shared variaboe varname instead of the Tcl vari-

able. ttssvv::::aappppeenndd varname element value ?value ...? Similar to standard Tcl aappppeenndd command but appends one or more values to the element in shared variable varname instead of the Tcl variable. ttssvv::::lloocckk 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

} LLIISSTT CCOOMMMMAANNDDSS Those command are similar to the equivalently named Tcl command. The difference is that they operate on elements of shared arrays. ttssvv::::llaappppeenndd varname element value ?value ...? Similar to standard Tcl llaappppeenndd command but appends one or more values to the element in shared variable varname instead of the Tcl variable. ttssvv::::lliinnsseerrtt varname element index value ?value ...? Similar to standard Tcl lliinnsseerrtt 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. ttssvv::::llrreeppllaaccee varname element first last ?value ...? Similar to standard Tcl llrreeppllaaccee 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. ttssvv::::lllleennggtthh varname element Similar to standard Tcl lllleennggtthh command but returns length of the element in the shared variable varname instead of the Tcl variable. ttssvv::::lliinnddeexx varname element ?index? Similar to standard Tcl lliinnddeexx command but returns the value at the index list position of the element from the shared variable varname instead of the Tcl variable. ttssvv::::llrraannggee varname element from to Similar to standard Tcl llrraannggee command but returns values between from and to list positions from the element in the shared variable varname instead of the Tcl variable. ttssvv::::llsseeaarrcchh varname element ?options? pattern Similar to standard Tcl llsseeaarrcchh command but searches the element in the shared variable varname instead of the Tcl variable. ttssvv::::llsseett varname element index ?index ...? value Similar to standard Tcl llsseett command but sets the element in the shared variable varname instead of the Tcl variable. ttssvv::::llppoopp varname element ?index? Similar to the standard Tcl lliinnddeexx 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 lliinnddeexx command, this command returns no value to the caller. ttssvv::::llppuusshh varname element ?index? This command performes the opposite of the ttssvv::::llppoopp command. As its counterpart, it returns no value to the caller. AARRRRAAYY CCOOMMMMAANNDDSS This command supports most of the options of the standard Tcl aarrrraayy command. In addition to those, it allows binding a shared variable to some persisten storage databases. Currently the only persistent option supported is the famous GNU Gdbm database. This option has to be

selected during the package compilation time. The implementation pro-

vides hooks for defining other persistency layers, if needed. ttssvv::::aarrrraayy sseett varname list Does the same as standard Tcl aarrrraayy sseett. ttssvv::::aarrrraayy ggeett varname ?pattern? Does the same as standard Tcl aarrrraayy ggeett. ttssvv::::aarrrraayy nnaammeess varname ?pattern? Does the same as standard Tcl aarrrraayy nnaammeess. ttssvv::::aarrrraayy ssiizzee varname Does the same as standard Tcl aarrrraayy ssiizzee. ttssvv::::aarrrraayy rreesseett varname list

Does the same as standard Tcl aarrrraayy sseett but it clears the var-

name and sets new values from the list atomically. ttssvv::::aarrrraayy bbiinndd varname handle Binds the varname to the persistent storage handle. The format

of the handle is :

. For the built-in GNU Gdbm

persistence layer, the format of the handle is "gdbm:" where is the path to the Gdbm database file. ttssvv::::aarrrraayy uunnbbiinndd varname Unbinds the shared array from its bound persistent storage. ttssvv::::aarrrraayy iissbboouunndd varname

Returns true (1) if the shared varname is bound to some persis-

tent storage or zero (0) if not. KKEEYYEEDD LLIISSTT CCOOMMMMAANNDDSS 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}}}

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. ttssvv::::kkeeyyllddeell 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. ttssvv::::kkeeyyllggeett 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. 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.

ttssvv::::kkeeyyllkkeeyyss 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 who's subfield keys are to be retrieved. ttssvv::::kkeeyyllsseett varname keylist key value ?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. DDIISSCCUUSSSSIIOONN The current implementation of thread shared variables allows for easy

and convenient access to data shared between different threads. Inter-

nally, the data is stored in Tcl objects and all package commands oper-

ate 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. Due to the internal design of the Tcl core, there is no provision of

full integration of shared variables within the Tcl syntax, unfortu-

nately. 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 out-

weights imposed limitations. CCRREEDDIITTSS Thread shared variables are inspired by the nsv interface found in AOLserver, a highly scalable Web server from America Online.