Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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  de-
	      pends  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 op-
	      tional 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  se-
	      quence 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 re-
	      sulting 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  be-
	      tween  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  se-
       lected  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  ex-
	      ists,  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 im-
       proving performance. Special care has been taken	to assure that all ob-
       ject  data  is  properly	locked and deep-copied when moving objects be-
       tween 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, tpool, ttrace

KEYWORDS
       locking,	synchronization, thread	shared data, threads

Tcl Threading			      2.8				tsv(n)

NAME | SYNOPSIS | DESCRIPTION | ELEMENT COMMANDS | LIST COMMANDS | ARRAY COMMANDS | KEYED LIST COMMANDS | DISCUSSION | CREDITS | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=tsv&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help