tsv - Part of the Tcl threading extension allowing script-level manipulation of data shared between threads in a simple, safe and protected fashion.

package require Thread ?2.5?

tsv::names ?pattern? tsv::object array element tsv::set array element value tsv::get array element ?varname? tsv::unset array ?element? tsv::exists array ?element? tsv::pop array element tsv::move array old new tsv::incr array element ?increment? tsv::append array element value ?value ...? tsv::lappend array element value ?value ...? tsv::linsert array element index value ?value ...? tsv::lreplace array element first last ?value ...? tsv::llength array element tsv::lindex array element index tsv::lrange array element first last tsv::lsearch array element ?mode? pattern tsv::lpop array element ?index? tsv::lpush array element value ?index? tsv::lock arg ?arg ...?

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 thread-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 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.

tsv::names

Returns names of shared variables matching optional pattern or all known variables if pattern is ommited. The tsv::names returns an empty list on process start. All thread shared variables are created by explicit user action.

tsv::object

Creates object accessor command for the element in the given shared array. 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

Sets the value of the element in the shared array to value and returns the value. The value may be ommited, and the command will return the current value of the element. If the element cannot be found, error is triggered.

tsv::get

Retrieves a value of the element located in the shared array. The command triggers error if the element is not found. If the optional varname is given, the value is stored in the named variable. In this case, the command returns true (1) if element is found or false (0) if the element is not found.

tsv::unset

Deletes the element in the shared array. If the element is not given, it deletes the whole array.

tsv::exists

Checks wether the element exists in the shared array. If the element is not given it tests the existence of the array itself. Returns true (1) if the item exists, false (0) if not.

tsv::pop

Returns value of the element in the shared array variable and unsets the element in one atomic operation.

tsv::move

Renames the element old to new in the shared array. This effectively performs an get/unset/set sequence of operations but in one atomic step.

tsv::incr

Similar to standard Tcl incr but increments the value of the element in shared array instead of the Tcl variable.

tsv::append

Similar to standard Tcl append but appends one or more values to the element in the shared array instead of the Tcl variable.

tsv::lappend

Similar to standard Tcl lappend but appends one or more values to the list element in the shared array instead of the Tcl variable.

tsv::linsert

Similar to standard Tcl linsert but inserts one or more values at the index list position in the list element in the shared array instead of the Tcl variable.

tsv::lreplace

Similar to standard Tcl lreplace but replaces one or more values from the list element in the shared array instead of the Tcl variable.

tsv::llength

Similar to standard Tcl llength but returns length of the list element in the shared array instead of the Tcl variable.

tsv::lindex

Similar to standard Tcl lindex but returns value at the index list position from the list element in the shared array instead of the Tcl variable.

tsv::lrange

Similar to standard Tcl lrange but returns values between first and last list position from the list element in the shared array instead of the Tcl variable.

tsv::lsearch

Similar to standard Tcl lsearch but searches the list element in the shared array instead of the Tcl variable.

tsv::lpop

Splices out the value at the index list position from the list element in the shared array. If index is not specified, it defaults to zero.

tsv::lpush

Inserts the value at the index list position in the list element in the shared array. If index is not specified, it defaults to zero.

tsv::lock

This command concatenates passed arguments and evaluates the resulting script under the internal mutex protection. During the script evaluation, the entire shared array 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 { # Atomically append two elements tsv::lappend foo bar 1 tsv::lappend foo bar 2 puts stderr [tsv::array get foo] tsv::unset foo } %

tsv::array

This command supports most of the options of the standard Tcl array command like:

tsv::array set

Does the same as standard Tcl array set

tsv::array get

Does the same as standard Tcl array get

tsv::array names

Does the same as standard Tcl array names

tsv::array size

Does the same as standard Tcl array size

tsv::array reset

Does the same as standard Tcl array set but it clears the array and sets new values atomically.

The current implementation of thread shared variables allows easy and convenient access to data to be 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 in assuring that all object data is properly locked and 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, 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 outweights imposed limitations.

Thread shared variables are inspired by the nsv interface found in AOLserver 3.+ highly scalable Web server from America Online.

Guide to the Tcl threading model

threads, synchronization, locking, thread shared data