## NAME

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

## SYNOPSIS

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

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

## COMMANDS

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.

## DISCUSSION

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.

## CREDITS

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

## SEE ALSO

Guide to the Tcl threading model

## KEYWORDS

threads, synchronization, locking, thread shared data