1tsv(n) tsv(n)
3______________________________________________________________________________
7
9 tsv - Part of the Tcl threading extension allowing script level manipu‐
10 lation of data shared between threads.
11
13 package require Tcl 8.4
14 package require Thread ?2.6?
16 tsv::names ?pattern?
18 tsv::object varname element
20 tsv::set varname element ?value?
22 tsv::get varname element ?namedvar?
24 tsv::unset varname ?element?
26 tsv::exists varname element
28 tsv::pop varname element
30 tsv::move varname oldname newname
32 tsv::incr varname element ?count?
34 tsv::append varname element value ?value ...?
36 tsv::lock varname arg ?arg ...?
38 tsv::lappend varname element value ?value ...?
40 tsv::linsert varname element index value ?value ...?
42 tsv::lreplace varname element first last ?value ...?
44 tsv::llength varname element
46 tsv::lindex varname element ?index?
48 tsv::lrange varname element from to
50 tsv::lsearch varname element ?options? pattern
52 tsv::lset varname element index ?index ...? value
54 tsv::lpop varname element ?index?
56 tsv::lpush varname element ?index?
58 tsv::array set varname list
60 tsv::array get varname ?pattern?
62 tsv::array names varname ?pattern?
64 tsv::array size varname
66 tsv::array reset varname list
68 tsv::array bind varname handle
70 tsv::array unbind varname
72 tsv::array isbound varname
74 tsv::keyldel varname keylist key
76 tsv::keylget varname keylist key ?retvar?
78 tsv::keylkeys varname keylist ?key?
80 tsv::keylset varname keylist key value ?key value..?
82_________________________________________________________________
84
86 This section describes commands implementing thread shared variables.
87 A thread shared variable is very similar to a Tcl array but in contrast
88 to a Tcl array it is created in shared memory and can be accessed from
89 many threads at the same time. Important feature of thread shared vari‐
90 able is that each access to the variable is internaly protected by a
91 mutex so script programmer does not have to take care about locking the
92 variable himself.
93 Thread shared variables are not bound to any thread explicitly. That
95 means that when a thread which created any of thread shared variables
96 exits, the variable and associated memory is not unset/reclaimed. User
97 has to explicitly unset the variable to reclaim the memory consumed by
98 the variable.
99
101 tsv::names ?pattern?
102 Returns names of shared variables matching optional ?pattern?
103 or all known variables if pattern is ommited.
104 tsv::object varname element
106 Creates object accessor command for the element in the shared
107 variable varname. Using this command, one can apply most of the
108 other shared variable commands as method functions of the ele‐
109 ment object command. The object command is automatically deleted
110 when the element which this command is pointing to is unset.
111 % tsv::set foo bar "A shared string"
112 % set string [tsv::object foo bar]
113 % $string append " appended"
114 => A shared string appended
115 tsv::set varname element ?value?
117 Sets the value of the element in the shared variable varname to
118 value and returns the value to caller. The value may be ommited,
119 in which case the command will return the current value of the
120 element. If the element cannot be found, error is triggered.
121 tsv::get varname element ?namedvar?
123 Retrieves the value of the element from the shared variable var‐
124 name. If the optional argument namedvar is given, the value is
125 stored in the named variable. Return value of the command
126 depends of the existence of the optional argument namedvar. If
127 the argument is ommited and the requested element cannot be
128 found in the shared array, the command triggers error. If, how‐
129 ever, the optional argument is given on the command line, the
130 command returns true (1) if the element is found or false (0) if
131 the element is not found.
132 tsv::unset varname ?element?
134 Unsets the element from the shared variable varname. If the
135 optional element is not given, it deletes the variable.
136 tsv::exists varname element
138 Checks wether the element exists in the shared variable varname
139 and returns true (1) if it does or false (0) if it doesn't.
140 tsv::pop varname element
142 Returns value of the element in the shared variable varname and
143 unsets the element, all in one atomic operation.
144 tsv::move varname oldname newname
146 Renames the element oldname to the newname in the shared vari‐
147 able varname. This effectively performs an get/unset/set
148 sequence of operations but all in one atomic step.
149 tsv::incr varname element ?count?
151 Similar to standard Tcl incr command but increments the value of
152 the element in shared variaboe varname instead of the Tcl vari‐
153 able.
154 tsv::append varname element value ?value ...?
156 Similar to standard Tcl append command but appends one or more
157 values to the element in shared variable varname instead of the
158 Tcl variable.
159 tsv::lock varname arg ?arg ...?
161 This command concatenates passed arguments and evaluates the
162 resulting script under the internal mutex protection. During the
163 script evaluation, the entire shared variable is locked. For
164 shared variable commands within the script, internal locking is
165 disabled so no deadlock can occur. It is also allowed to unset
166 the shared variable from within the script. The shared variable
167 is automatically created if it did not exists at the time of the
168 first lock operation.
169 % tsv::lock foo {
170 tsv::lappend foo bar 1
171 tsv::lappend foo bar 2
172 puts stderr [tsv::set foo bar]
173 tsv::unset foo
174 }
175
177 Those command are similar to the equivalently named Tcl command. The
178 difference is that they operate on elements of shared arrays.
179 tsv::lappend varname element value ?value ...?
181 Similar to standard Tcl lappend command but appends one or more
182 values to the element in shared variable varname instead of the
183 Tcl variable.
184 tsv::linsert varname element index value ?value ...?
186 Similar to standard Tcl linsert command but inserts one or more
187 values at the index list position in the element in the shared
188 variable varname instead of the Tcl variable.
189 tsv::lreplace varname element first last ?value ...?
191 Similar to standard Tcl lreplace command but replaces one or
192 more values between the first and last position in the element
193 of the shared variable varname instead of the Tcl variable.
194 tsv::llength varname element
196 Similar to standard Tcl llength command but returns length of
197 the element in the shared variable varname instead of the Tcl
198 variable.
199 tsv::lindex varname element ?index?
201 Similar to standard Tcl lindex command but returns the value at
202 the index list position of the element from the shared variable
203 varname instead of the Tcl variable.
204 tsv::lrange varname element from to
206 Similar to standard Tcl lrange command but returns values
207 between from and to list positions from the element in the
208 shared variable varname instead of the Tcl variable.
209 tsv::lsearch varname element ?options? pattern
211 Similar to standard Tcl lsearch command but searches the element
212 in the shared variable varname instead of the Tcl variable.
213 tsv::lset varname element index ?index ...? value
215 Similar to standard Tcl lset command but sets the element in the
216 shared variable varname instead of the Tcl variable.
217 tsv::lpop varname element ?index?
219 Similar to the standard Tcl lindex command but in addition to
220 returning, it also splices the value out of the element from the
221 shared variable varname in one atomic operation. In contrast to
222 the Tcl lindex command, this command returns no value to the
223 caller.
224 tsv::lpush varname element ?index?
226 This command performes the opposite of the tsv::lpop command.
227 As its counterpart, it returns no value to the caller.
228
230 This command supports most of the options of the standard Tcl array
231 command. In addition to those, it allows binding a shared variable to
232 some persisten storage databases. Currently the only persistent option
233 supported is the famous GNU Gdbm database. This option has to be
234 selected during the package compilation time. The implementation pro‐
235 vides hooks for defining other persistency layers, if needed.
236 tsv::array set varname list
238 Does the same as standard Tcl array set.
239 tsv::array get varname ?pattern?
241 Does the same as standard Tcl array get.
242 tsv::array names varname ?pattern?
244 Does the same as standard Tcl array names.
245 tsv::array size varname
247 Does the same as standard Tcl array size.
248 tsv::array reset varname list
250 Does the same as standard Tcl array set but it clears the var‐
251 name and sets new values from the list atomically.
252 tsv::array bind varname handle
254 Binds the varname to the persistent storage handle. The format
255 of the handle is <handler>:<address>. For the built-in GNU Gdbm
256 persistence layer, the format of the handle is "gdbm:<path>"
257 where <path> is the path to the Gdbm database file.
258 tsv::array unbind varname
260 Unbinds the shared array from its bound persistent storage.
261 tsv::array isbound varname
263 Returns true (1) if the shared varname is bound to some persis‐
264 tent storage or zero (0) if not.
265
267 Keyed list commands are borrowed from the TclX package. Keyed lists
268 provide a structured data type built upon standard Tcl lists. This is a
269 functionality similar to structs in the C programming language.
270 A keyed list is a list in which each element contains a key and value
272 pair. These element pairs are stored as lists themselves, where the key
273 is the first element of the list, and the value is the second. The key-
274 value pairs are referred to as fields. This is an example of a keyed
275 list:
276 {{NAME {Frank Zappa}} {JOB {musician and composer}}}
277 Fields may contain subfields; `.' is the separator character. Subfields
278 are actually fields where the value is another keyed list. Thus the
279 following list has the top level fields ID and NAME, and subfields
280 NAME.FIRST and NAME.LAST:
281 {ID 106} {NAME {{FIRST Frank} {LAST Zappa}}}
282 There is no limit to the recursive depth of subfields, allowing one to
283 build complex data structures. Keyed lists are constructed and accessed
284 via a number of commands. All keyed list management commands take the
285 name of the variable containing the keyed list as an argument (i.e.
286 passed by reference), rather than passing the list directly.
287 tsv::keyldel varname keylist key
289 Delete the field specified by key from the keyed list keylist in
290 the shared variable varname. This removes both the key and the
291 value from the keyed list.
292 tsv::keylget varname keylist key ?retvar?
294 Return the value associated with key from the keyed list keylist
295 in the shared variable varname. If the optional retvar is not
296 specified, then the value will be returned as the result of the
297 command. In this case, if key is not found in the list, an error
298 will result.
299 If retvar is specified and key is in the list, then the value is
301 returned in the variable retvar and the command returns 1 if the
302 key was present within the list. If key isn't in the list, the
303 command will return 0, and retvar will be left unchanged. If {}
304 is specified for retvar, the value is not returned, allowing the
305 Tcl programmer to determine if a key is present in a keyed list
306 without setting a variable as a side-effect.
307 tsv::keylkeys varname keylist ?key?
309 Return the a list of the keys in the keyed list keylist in the
310 shared variable varname. If key is specified, then it is the
311 name of a key field who's subfield keys are to be retrieved.
312 tsv::keylset varname keylist key value ?key value..?
314 Set the value associated with key, in the keyed list keylist to
315 value. If the keylist does not exists, it is created. If key is
316 not currently in the list, it will be added. If it already
317 exists, value replaces the existing value. Multiple keywords and
318 values may be specified, if desired.
319
321 The current implementation of thread shared variables allows for easy
322 and convenient access to data shared between different threads. Inter‐
323 nally, the data is stored in Tcl objects and all package commands oper‐
324 ate on internal data representation, thus minimizing shimmering and
325 improving performance. Special care has been taken to assure that all
326 object data is properly locked and deep-copied when moving objects
327 between threads.
328 Due to the internal design of the Tcl core, there is no provision of
330 full integration of shared variables within the Tcl syntax, unfortu‐
331 nately. All access to shared data must be performed with the supplied
332 package commands. Also, variable traces are not supported. But even
333 so, benefits of easy, simple and safe shared data manipulation out‐
334 weights imposed limitations.
335
337 Thread shared variables are inspired by the nsv interface found in
338 AOLserver, a highly scalable Web server from America Online.
339
341 thread, tpool, ttrace
342
344 locking, synchronization, thread shared data, threads
345Tcl Threading 2.6 tsv(n)