manpagez: man(ual) pages & more
man tsv(n)
Home | html | info | man
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 Tcl  8.4

       package require Thread  ?2.8?

       tsv::names ?pattern?

       tsv::object varname element

       tsv::set varname element ?value?

       tsv::get varname element ?namedvar?

       tsv::unset varname ?element?

       tsv::exists varname element

       tsv::pop varname element

       tsv::move varname oldname newname

       tsv::incr varname element ?count?

       tsv::append varname element value ?value ...?

       tsv::lock varname arg ?arg ...?

       tsv::handlers

       tsv::lappend varname element value ?value ...?

       tsv::linsert varname element index value ?value ...?

       tsv::lreplace varname element first last ?value ...?

       tsv::llength varname element

       tsv::lindex varname element ?index?

       tsv::lrange varname element from to

       tsv::lsearch varname element ?options? pattern

       tsv::lset varname element index ?index ...? value

       tsv::lpop varname element ?index?

       tsv::lpush varname element ?index?

       tsv::array set varname list

       tsv::array get varname ?pattern?

       tsv::array names varname ?pattern?

       tsv::array size varname

       tsv::array reset varname list

       tsv::array bind varname handle

       tsv::array unbind varname

       tsv::array isbound varname

       tsv::keyldel varname keylist key

       tsv::keylget varname keylist key ?retvar?

       tsv::keylkeys varname keylist ?key?

       tsv::keylset 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.


ELEMENT COMMANDS

       tsv::names ?pattern?
              Returns names of shared variables  matching  optional  ?pattern?
              or all known variables if pattern is ommited.

       tsv::object 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


       tsv::set 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.

       tsv::get 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.

       tsv::unset varname ?element?
              Unsets the element from the shared  variable  varname.   If  the
              optional element is not given, it deletes the variable.

       tsv::exists 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.

       tsv::pop varname element
              Returns value of the element in the shared variable varname  and
              unsets the element, all in one atomic operation.

       tsv::move 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.

       tsv::incr varname element ?count?
              Similar to standard Tcl incr command but increments the value of
              the element in shared variaboe varname instead of the Tcl  vari-
              able.

       tsv::append varname element value ?value ...?
              Similar  to  standard Tcl append command but appends one or more
              values to the element in shared variable varname instead of  the
              Tcl variable.

       tsv::lock 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
                  }


       tsv::handlers
              Returns the names of all persistent storage handlers enabled  at
              compile time.  See ARRAY COMMANDS for details.



LIST COMMANDS

       Those  command  are  similar to the equivalently named Tcl command. The
       difference is that they operate on elements of shared arrays.

       tsv::lappend varname element value ?value ...?
              Similar to standard Tcl lappend command but appends one or  more
              values  to the element in shared variable varname instead of the
              Tcl variable.

       tsv::linsert varname element index value ?value ...?
              Similar to standard Tcl linsert 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.

       tsv::lreplace varname element first last ?value ...?
              Similar to standard Tcl lreplace 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.

       tsv::llength varname element
              Similar to standard Tcl llength command but  returns  length  of
              the  element  in  the shared variable varname instead of the Tcl
              variable.

       tsv::lindex varname element ?index?
              Similar to standard Tcl lindex command but returns the value  at
              the  index list position of the element from the shared variable
              varname instead of the Tcl variable.

       tsv::lrange varname element from to
              Similar to  standard  Tcl  lrange  command  but  returns  values
              between  from  and  to  list  positions  from the element in the
              shared variable varname instead of the Tcl variable.

       tsv::lsearch varname element ?options? pattern
              Similar to standard Tcl lsearch command but searches the element
              in the shared variable varname instead of the Tcl variable.

       tsv::lset varname element index ?index ...? value
              Similar to standard Tcl lset command but sets the element in the
              shared variable varname instead of the Tcl variable.

       tsv::lpop varname element ?index?
              Similar to the standard Tcl lindex 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  lindex  command,  this command returns no value to the
              caller.

       tsv::lpush varname element ?index?
              This command performes the opposite of  the  tsv::lpop  command.
              As its counterpart, it returns no value to the caller.



ARRAY COMMANDS

       This  command  supports  most  of the options of the standard Tcl array
       command. In addition to those, it allows binding a shared  variable  to
       some persisten storage databases. Currently the persistent options sup-
       ported are the famous GNU Gdbm and  LMDB.  These  options  have  to  be
       selected  during the package compilation time.  The implementation pro-
       vides hooks for defining other persistency layers, if needed.

       tsv::array set varname list
              Does the same as standard Tcl array set.

       tsv::array get varname ?pattern?
              Does the same as standard Tcl array get.

       tsv::array names varname ?pattern?
              Does the same as standard Tcl array names.

       tsv::array size varname
              Does the same as standard Tcl array size.

       tsv::array reset varname list
              Does the same as standard Tcl array set but it clears  the  var-
              name and sets new values from the list atomically.

       tsv::array bind varname handle
              Binds  the varname to the persistent storage handle.  The format
              of the handle is <handler>:<address>, where <handler> is  "gdbm"
              for  GNU  Gdbm  and "lmdb" for LMDB and <address> is the path to
              the database file.

       tsv::array unbind varname
              Unbinds the shared array from its bound persistent storage.

       tsv::array isbound varname
              Returns true (1) if the shared varname is bound to some  persis-
              tent storage or zero (0) if not.



KEYED LIST COMMANDS

       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.

       tsv::keyldel 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.

       tsv::keylget 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.

       tsv::keylkeys 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.

       tsv::keylset 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.



DISCUSSION

       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.


CREDITS

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


SEE ALSO

       thread(n), tpool(n), ttrace(n)


KEYWORDS

       locking, synchronization, thread shared data, threads



Tcl Threading                         2.8                               tsv(n)

tcl 8.6.6 - Generated Mon Aug 22 18:32:51 CDT 2016
© manpagez.com 2000-2017
Individual documents may contain additional copyright information.