1tsv(n) tsv(n)
2______________________________________________________________________________
6
8 tsv - Part of the Tcl threading extension allowing script level manipu‐
9 lation of data shared between threads.
10
12 package require Tcl 8.4
13 package require Thread ?2.8?
15 tsv::names ?pattern?
17 tsv::object varname element
19 tsv::set varname element ?value?
21 tsv::get varname element ?namedvar?
23 tsv::unset varname ?element?
25 tsv::exists varname element
27 tsv::pop varname element
29 tsv::move varname oldname newname
31 tsv::incr varname element ?count?
33 tsv::append varname element value ?value ...?
35 tsv::lock varname arg ?arg ...?
37 tsv::handlers
39 tsv::lappend varname element value ?value ...?
41 tsv::linsert varname element index value ?value ...?
43 tsv::lreplace varname element first last ?value ...?
45 tsv::llength varname element
47 tsv::lindex varname element ?index?
49 tsv::lrange varname element from to
51 tsv::lsearch varname element ?options? pattern
53 tsv::lset varname element index ?index ...? value
55 tsv::lpop varname element ?index?
57 tsv::lpush varname element ?index?
59 tsv::array set varname list
61 tsv::array get varname ?pattern?
63 tsv::array names varname ?pattern?
65 tsv::array size varname
67 tsv::array reset varname list
69 tsv::array bind varname handle
71 tsv::array unbind varname
73 tsv::array isbound varname
75 tsv::keyldel varname keylist key
77 tsv::keylget varname keylist key ?retvar?
79 tsv::keylkeys varname keylist ?key?
81 tsv::keylset varname keylist key value ?key value..?
83______________________________________________________________________________
85
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 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
102 tsv::names ?pattern?
103 Returns names of shared variables matching optional ?pattern?
104 or all known variables if pattern is ommited.
105 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 % tsv::set foo bar "A shared string"
115 % set string [tsv::object foo bar]
116 % $string append " appended"
117 => A shared string appended
118 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 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 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 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 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 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 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 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 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 % 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 tsv::handlers
184 Returns the names of all persistent storage handlers enabled at
185 compile time. See ARRAY COMMANDS for details.
186
188 Those command are similar to the equivalently named Tcl command. The
189 difference is that they operate on elements of shared arrays.
190 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 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 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 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 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 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 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 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 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 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
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 tsv::array set varname list
249 Does the same as standard Tcl array set.
250 tsv::array get varname ?pattern?
252 Does the same as standard Tcl array get.
253 tsv::array names varname ?pattern?
255 Does the same as standard Tcl array names.
256 tsv::array size varname
258 Does the same as standard Tcl array size.
259 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 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 tsv::array unbind varname
271 Unbinds the shared array from its bound persistent storage.
272 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
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 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 {{NAME {Frank Zappa}} {JOB {musician and composer}}}
290 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 {ID 106} {NAME {{FIRST Frank} {LAST Zappa}}}
298 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 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 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 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 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 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
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 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
354 Thread shared variables are inspired by the nsv interface found in
355 AOLserver, a highly scalable Web server from America Online.
356
358 thread, tpool, ttrace
359
361 locking, synchronization, thread shared data, threads
362Tcl Threading 2.8 tsv(n)