1tsv(n)                                                                  tsv(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       tsv - Part of the Tcl threading extension allowing script level manipu‐
9       lation of data shared between threads.
10

SYNOPSIS

12       package require Tcl  8.4
13
14       package require Thread  ?2.8?
15
16       tsv::names ?pattern?
17
18       tsv::object varname element
19
20       tsv::set varname element ?value?
21
22       tsv::get varname element ?namedvar?
23
24       tsv::unset varname ?element?
25
26       tsv::exists varname element
27
28       tsv::pop varname element
29
30       tsv::move varname oldname newname
31
32       tsv::incr varname element ?count?
33
34       tsv::append varname element value ?value ...?
35
36       tsv::lock varname arg ?arg ...?
37
38       tsv::handlers
39
40       tsv::lappend varname element value ?value ...?
41
42       tsv::linsert varname element index value ?value ...?
43
44       tsv::lreplace varname element first last ?value ...?
45
46       tsv::llength varname element
47
48       tsv::lindex varname element ?index?
49
50       tsv::lrange varname element from to
51
52       tsv::lsearch varname element ?options? pattern
53
54       tsv::lset varname element index ?index ...? value
55
56       tsv::lpop varname element ?index?
57
58       tsv::lpush varname element ?index?
59
60       tsv::array set varname list
61
62       tsv::array get varname ?pattern?
63
64       tsv::array names varname ?pattern?
65
66       tsv::array size varname
67
68       tsv::array reset varname list
69
70       tsv::array bind varname handle
71
72       tsv::array unbind varname
73
74       tsv::array isbound varname
75
76       tsv::keyldel varname keylist key
77
78       tsv::keylget varname keylist key ?retvar?
79
80       tsv::keylkeys varname keylist ?key?
81
82       tsv::keylset varname keylist key value ?key value..?
83
84______________________________________________________________________________
85

DESCRIPTION

87       This section describes commands implementing thread  shared  variables.
88       A thread shared variable is very similar to a Tcl array but in contrast
89       to a Tcl array it is created in shared memory and can be accessed  from
90       many threads at the same time. Important feature of thread shared vari‐
91       able is that each access to the variable is internaly  protected  by  a
92       mutex so script programmer does not have to take care about locking the
93       variable himself.
94
95       Thread shared variables are not bound to any  thread  explicitly.  That
96       means  that  when a thread which created any of thread shared variables
97       exits, the variable and associated memory is not unset/reclaimed.  User
98       has  to explicitly unset the variable to reclaim the memory consumed by
99       the variable.
100

ELEMENT COMMANDS

102       tsv::names ?pattern?
103              Returns names of shared variables  matching  optional  ?pattern?
104              or all known variables if pattern is ommited.
105
106       tsv::object varname element
107              Creates  object  accessor  command for the element in the shared
108              variable varname. Using this command, one can apply most of  the
109              other  shared  variable commands as method functions of the ele‐
110              ment object command. The object command is automatically deleted
111              when the element which this command is pointing to is unset.
112
113
114                  % tsv::set foo bar "A shared string"
115                  % set string [tsv::object foo bar]
116                  % $string append " appended"
117                  => A shared string appended
118
119
120       tsv::set varname element ?value?
121              Sets  the value of the element in the shared variable varname to
122              value and returns the value to caller. The value may be ommited,
123              in  which  case the command will return the current value of the
124              element. If the element cannot be found, error is triggered.
125
126       tsv::get varname element ?namedvar?
127              Retrieves the value of the element from the shared variable var‐
128              name.   If the optional argument namedvar is given, the value is
129              stored in the  named  variable.  Return  value  of  the  command
130              depends  of the existence of the optional argument namedvar.  If
131              the argument is ommited and  the  requested  element  cannot  be
132              found  in the shared array, the command triggers error. If, how‐
133              ever, the optional argument is given on the  command  line,  the
134              command returns true (1) if the element is found or false (0) if
135              the element is not found.
136
137       tsv::unset varname ?element?
138              Unsets the element from the shared  variable  varname.   If  the
139              optional element is not given, it deletes the variable.
140
141       tsv::exists varname element
142              Checks  wether the element exists in the shared variable varname
143              and returns true (1) if it does or false (0) if it doesn't.
144
145       tsv::pop varname element
146              Returns value of the element in the shared variable varname  and
147              unsets the element, all in one atomic operation.
148
149       tsv::move varname oldname newname
150              Renames  the  element oldname to the newname in the shared vari‐
151              able  varname.  This  effectively  performs   an   get/unset/set
152              sequence of operations but all in one atomic step.
153
154       tsv::incr varname element ?count?
155              Similar to standard Tcl incr command but increments the value of
156              the element in shared variaboe varname instead of the Tcl  vari‐
157              able.
158
159       tsv::append varname element value ?value ...?
160              Similar  to  standard Tcl append command but appends one or more
161              values to the element in shared variable varname instead of  the
162              Tcl variable.
163
164       tsv::lock varname arg ?arg ...?
165              This  command  concatenates  passed  arguments and evaluates the
166              resulting script under the internal mutex protection. During the
167              script  evaluation,  the  entire  shared variable is locked. For
168              shared variable commands within the script, internal locking  is
169              disabled  so  no deadlock can occur. It is also allowed to unset
170              the shared variable from within the script. The shared  variable
171              is automatically created if it did not exists at the time of the
172              first lock operation.
173
174
175                  % tsv::lock foo {
176                      tsv::lappend foo bar 1
177                      tsv::lappend foo bar 2
178                      puts stderr [tsv::set foo bar]
179                      tsv::unset foo
180                  }
181
182
183       tsv::handlers
184              Returns the names of all persistent storage handlers enabled  at
185              compile time.  See ARRAY COMMANDS for details.
186

LIST COMMANDS

188       Those  command  are  similar to the equivalently named Tcl command. The
189       difference is that they operate on elements of shared arrays.
190
191       tsv::lappend varname element value ?value ...?
192              Similar to standard Tcl lappend command but appends one or  more
193              values  to the element in shared variable varname instead of the
194              Tcl variable.
195
196       tsv::linsert varname element index value ?value ...?
197              Similar to standard Tcl linsert command but inserts one or  more
198              values  at  the index list position in the element in the shared
199              variable varname instead of the Tcl variable.
200
201       tsv::lreplace varname element first last ?value ...?
202              Similar to standard Tcl lreplace command  but  replaces  one  or
203              more  values  between the first and last position in the element
204              of the shared variable varname instead of the Tcl variable.
205
206       tsv::llength varname element
207              Similar to standard Tcl llength command but  returns  length  of
208              the  element  in  the shared variable varname instead of the Tcl
209              variable.
210
211       tsv::lindex varname element ?index?
212              Similar to standard Tcl lindex command but returns the value  at
213              the  index list position of the element from the shared variable
214              varname instead of the Tcl variable.
215
216       tsv::lrange varname element from to
217              Similar to  standard  Tcl  lrange  command  but  returns  values
218              between  from  and  to  list  positions  from the element in the
219              shared variable varname instead of the Tcl variable.
220
221       tsv::lsearch varname element ?options? pattern
222              Similar to standard Tcl lsearch command but searches the element
223              in the shared variable varname instead of the Tcl variable.
224
225       tsv::lset varname element index ?index ...? value
226              Similar to standard Tcl lset command but sets the element in the
227              shared variable varname instead of the Tcl variable.
228
229       tsv::lpop varname element ?index?
230              Similar to the standard Tcl lindex command but  in  addition  to
231              returning, it also splices the value out of the element from the
232              shared variable varname in one atomic operation.  In contrast to
233              the  Tcl  lindex  command,  this command returns no value to the
234              caller.
235
236       tsv::lpush varname element ?index?
237              This command performes the opposite of  the  tsv::lpop  command.
238              As its counterpart, it returns no value to the caller.
239

ARRAY COMMANDS

241       This  command  supports  most  of the options of the standard Tcl array
242       command. In addition to those, it allows binding a shared  variable  to
243       some persisten storage databases. Currently the persistent options sup‐
244       ported are the famous GNU Gdbm and  LMDB.  These  options  have  to  be
245       selected  during the package compilation time.  The implementation pro‐
246       vides hooks for defining other persistency layers, if needed.
247
248       tsv::array set varname list
249              Does the same as standard Tcl array set.
250
251       tsv::array get varname ?pattern?
252              Does the same as standard Tcl array get.
253
254       tsv::array names varname ?pattern?
255              Does the same as standard Tcl array names.
256
257       tsv::array size varname
258              Does the same as standard Tcl array size.
259
260       tsv::array reset varname list
261              Does the same as standard Tcl array set but it clears  the  var‐
262              name and sets new values from the list atomically.
263
264       tsv::array bind varname handle
265              Binds  the varname to the persistent storage handle.  The format
266              of the handle is <handler>:<address>, where <handler> is  "gdbm"
267              for  GNU  Gdbm  and "lmdb" for LMDB and <address> is the path to
268              the database file.
269
270       tsv::array unbind varname
271              Unbinds the shared array from its bound persistent storage.
272
273       tsv::array isbound varname
274              Returns true (1) if the shared varname is bound to some  persis‐
275              tent storage or zero (0) if not.
276

KEYED LIST COMMANDS

278       Keyed  list  commands  are  borrowed from the TclX package. Keyed lists
279       provide a structured data type built upon standard Tcl lists. This is a
280       functionality similar to structs in the C programming language.
281
282       A  keyed  list is a list in which each element contains a key and value
283       pair. These element pairs are stored as lists themselves, where the key
284       is the first element of the list, and the value is the second. The key-
285       value pairs are referred to as fields.  This is an example of  a  keyed
286       list:
287
288
289                  {{NAME  {Frank  Zappa}} {JOB {musician and composer}}}
290
291       Fields may contain subfields; `.' is the separator character. Subfields
292       are actually fields  where the value is another keyed  list.  Thus  the
293       following  list  has  the  top  level fields ID and NAME, and subfields
294       NAME.FIRST and NAME.LAST:
295
296
297                  {ID 106} {NAME {{FIRST Frank} {LAST Zappa}}}
298
299       There is no limit to the recursive depth of subfields, allowing one  to
300       build complex data structures. Keyed lists are constructed and accessed
301       via a number of commands. All  keyed  list management commands take the
302       name  of  the  variable  containing the keyed list as an argument (i.e.
303       passed by reference), rather than passing the list directly.
304
305       tsv::keyldel varname keylist key
306              Delete the field specified by key from the keyed list keylist in
307              the  shared variable varname.  This removes both the key and the
308              value from the keyed list.
309
310       tsv::keylget varname keylist key ?retvar?
311              Return the value associated with key from the keyed list keylist
312              in  the  shared variable varname.  If the optional retvar is not
313              specified, then the value will be returned as the result of  the
314              command. In this case, if key is not found in the list, an error
315              will result.
316
317              If retvar is specified and key is in the list, then the value is
318              returned in the variable retvar and the command returns 1 if the
319              key was present within the list. If key isn't in the  list,  the
320              command  will return 0, and retvar will be left unchanged. If {}
321              is specified for retvar, the value is not returned, allowing the
322              Tcl  programmer to determine if a key is present in a keyed list
323              without setting a variable as a side-effect.
324
325       tsv::keylkeys varname keylist ?key?
326              Return  the a list of the keys in the keyed list keylist in  the
327              shared  variable  varname.  If  key is specified, then it is the
328              name of a key field who's subfield keys are to be retrieved.
329
330       tsv::keylset varname keylist key value ?key value..?
331              Set the value associated with key, in the keyed list keylist  to
332              value. If the keylist does not exists, it is created.  If key is
333              not currently in the list, it  will  be  added.  If  it  already
334              exists, value replaces the existing value. Multiple keywords and
335              values may be specified, if desired.
336

DISCUSSION

338       The current implementation of thread shared variables allows  for  easy
339       and convenient access to data shared between different threads.  Inter‐
340       nally, the data is stored in Tcl objects and all package commands oper‐
341       ate  on  internal  data  representation, thus minimizing shimmering and
342       improving performance. Special care has been taken to assure  that  all
343       object  data  is  properly  locked  and deep-copied when moving objects
344       between threads.
345
346       Due to the internal design of the Tcl core, there is  no  provision  of
347       full  integration  of  shared variables within the Tcl syntax, unfortu‐
348       nately. All access to shared data must be performed with  the  supplied
349       package  commands.   Also,  variable traces are not supported. But even
350       so, benefits of easy, simple and safe  shared  data  manipulation  out‐
351       weights imposed limitations.
352

CREDITS

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

SEE ALSO

358       thread, tpool, ttrace
359

KEYWORDS

361       locking, synchronization, thread shared data, threads
362
363
364
365Tcl Threading                         2.8                               tsv(n)
Impressum