Thread-shared Variables - Revision history

Gustafn: fix category entries

2009-02-09T08:45:11Z

fix category entries

Lemuelf: removed "aka Network Shared Variables or NSVs" because nothing is shared in the network and it just confuses people how nsvs work

2009-02-09T07:38:18Z

removed "aka Network Shared Variables or NSVs" because nothing is shared in the network and it just confuses people how nsvs work

Josephbui at 20:19, 1 May 2006

2006-05-01T20:19:31Z

Caveman: formatting of code sample

2005-12-08T01:59:38Z

formatting of code sample

71.214.77.117 at 01:17, 8 December 2005

2005-12-08T01:17:39Z

WikiSysop: imported from WiKit id 1311

2004-06-19T11:05:10Z

imported from WiKit id 1311

New page

aka Network Shared Variables or NSVs

The nsv commands provide a high performance data sharing mechanism. This facility is much flexible alternative to the obsolete [[ns_share]] command. The model uses an array syntax and includes more features. In addition, lock contention is managed in a much more scalable way--something that is not possible with the obsolete [[ns_share]] facility.
* [[nsv_get]] - get key value
* [[nsv_exists]] - check key existence
* [[nsv_set]] - set key value
* [[nsv_append]] - append value
* [[nsv_lappend]] - append value as list element
* [[nsv_incr]] - increment and return value
* [[nsv_unset]] - unset a value
* [[nsv_array]] - manage nsv arrays
* [[nsv_names]] - list the nsvs in use

Commands for the most part mirror the corresponding Tcl command for ordinary variables. Basically, to set a value, simply use the nsv_set command:

nsv_set myarray foo $value

and to get a value, simply use the nsv_get command:

set value [[nsv_get myarray foo]]

'''Multithreading Features'''

One advantages of nsv is built in interlocking for thread safety. For example, consider a case of a "increment-by-one" unique id system. Here's the [[ns_share]] solution:

ns_share ids
set ids(lock) [[ns_mutex create]]
set ids(next) 0

proc nextid {} {
ns_share ids
ns_mutex lock $ids(lock)
set next [[incr ids(next)]]
ns_mutex unlock $ids(lock)
return $next
}

and here's an nsv solution:

nsv_set ids next 0

proc nextid {} {
return [[nsv_incr ids next]]
}

Note that the nsv solution does not need a mutex as the [[nsv_incr]] command is internally interlocked.

'''Compatibility with Tcl Arrays'''

Another useful feature of nsv is the [[nsv_array]] command which works much like the Tcl array command. This can be used to import and export values from ordinary Tcl arrays. For example, to copy from Tcl use:

nsv_array set meta [[array get tmpmeta]]

and to copy to Tcl use:

array set metacopy [[nsv_array get meta]]

As with all other nsv command, [[nsv_array]] is atomic and no explicit locking is required. This feature can be used to contruct a new nsv array by first filling up an ordinary temporary Tcl array via some time consuming process and then swapping it into place as above. While the new temporary array is being constructed, other threads can access the old array without delay or inconsistant data. You can even reset a complete nsv array in one step with "reset". For example, instead of:

ns_share lock meta
set lock [[ns_mutex create]]

ns_mutex lock $lock
unset meta
array set meta [[array get tmpmeta]]
ns_mutex unlock $lock

you can simply use:

nsv_array reset meta [[array get tmpmeta]]

The reset option will flush and then reset all values atomically, eliminating the need for the explicit lock.

Other options for the nsv_array command include:
* [[nsv_array]] exists ''array'' - test existance of array
* [[nsv_array]] size ''array'' - return # of elements in array
* [[nsv_array]] names ''array'' ''?pattern?'' - return keys of array

'''Configuration'''

The nsv system uses a common multithreading technique to reduce the potential for lock contention which is to split the locks to acheive finer grained locking. This technique groups arrays randomly into buckets and only the arrays within a particular bucket share a lock. The number of buckets to be used can be configured by setting the "nsvbuckets" tcl parameters, e.g.:

[[ns/server/server1/tcl]]
nsvbuckets=20

The default is 8 which should be reasonable. Note that you can monitor the lock contention, if any, by enabling mutex metering:

[[ns/threads]]
mutexmetering=on

and then viewing the results of "[[ns_info]] locks" command after the server has been running for some time. The nsv locks all have names of the form "nsv:##". If you find many lock attempts which did not successed immediately, try increasing nsvbuckets.

'''Migrating From ns_share'''

Migrating from [[ns_share]] is straightforward. If your init.tcl included commands such as:

ns_share myshare
set myshare(lock) [[ns_mutex create]]

use instead:

nsv_set myshare lock [[ns_mutex create]]

In your procedures, instead of:

proc myproc {} {
ns_share myshare
ns_mutex lock $myshare(lock) ...

use:

proc myproc {} {
ns_mutex lock [[nsv_get myshare lock]]
...

and within an ADP page, instead of:

<%
ns_share myshare
ns_puts $myshare(key1)
%>

<%=$myshare(key2)%>

use:

<%
ns_puts [[nsv_get myshare key1]]
%>

<%=[[nsv_get myshare key2]]%>

Notice that, unlike [[ns_share]], no command is required to define the shared array. The first attempt at setting the variable through any means will automaticaly create the array. Also notice that only arrays are supported. However, to migrate from [[ns_share]] you can simply package up all existing [[ns_share]] scalars into a single array with a short name, perhaps just ".". For example, if you had:

ns_share mylock myfile
set myfile /tmp/some.file
set mylock [[ns_mutex create]]

you can use:

nsv_set . myfile /tmp/some.file
nsv_set . mylock [[ns_mutex create]]

----

[[Category Documentation]] - [[Category Core Tcl API]]

← Older revision		Revision as of 08:45, 9 February 2009
Line 146:		Line 146:
	----		----

−	[[Category Documentation]] - [[Category Core Tcl API]]	+	[[Category:Documentation]] - [[Category:Core Tcl API]]

← Older revision		Revision as of 07:38, 9 February 2009
Line 1:		Line 1:
−	~~aka Network Shared Variables or NSVs~~
−
	The nsv commands provide a high performance data sharing mechanism. This facility is a more flexible alternative to the obsolete [[ns_share]] command. The model uses an array syntax and includes more features. In addition, lock contention is managed in a much more scalable way--something that is not possible with the obsolete [[ns_share]] facility.		The nsv commands provide a high performance data sharing mechanism. This facility is a more flexible alternative to the obsolete [[ns_share]] command. The model uses an array syntax and includes more features. In addition, lock contention is managed in a much more scalable way--something that is not possible with the obsolete [[ns_share]] facility.
	* [[nsv_get]] - get key value		* [[nsv_get]] - get key value

← Older revision		Revision as of 01:17, 8 December 2005
Line 20:		Line 20:

	set value [[nsv_get myarray foo]]		set value [[nsv_get myarray foo]]
		+
		+
		+	What is the difference between nsv_set and nsv_array set? Is it exactly the same as the difference between set and array set?

	'''Multithreading Features'''		'''Multithreading Features'''

@@ Line 1: / Line 1: @@
 aka Network Shared Variables or NSVs
-The nsv commands provide a high performance data sharing mechanism. This facility is much flexible alternative to the obsolete [[ns_share]] command. The model uses an array syntax and includes more features. In addition, lock contention is managed in a much more scalable way--something that is not possible with the obsolete [[ns_share]] facility.
+The nsv commands provide a high performance data sharing mechanism. This facility is a more flexible alternative to the obsolete [[ns_share]] command. The model uses an array syntax and includes more features. In addition, lock contention is managed in a much more scalable way--something that is not possible with the obsolete [[ns_share]] facility.
 * [[nsv_get]] - get key value
 * [[nsv_exists]] - check key existence

@@ Line 19: / Line 19: @@
 and to get a value, simply use the nsv_get command:
-     set value [[nsv_get myarray foo]]
+     set value [nsv_get myarray foo]
@@ Line 29: / Line 29: @@
      ns_share ids
-     set ids(lock) [[ns_mutex create]]
+     set ids(lock) [ns_mutex create]
      set ids(next) 0
@@ Line 35: / Line 35: @@
          ns_share ids
          ns_mutex lock $ids(lock)
-         set next [[incr ids(next)]]
+         set next [incr ids(next)]
          ns_mutex unlock $ids(lock)
          return $next
@@ Line 45: / Line 45: @@
      proc nextid {} {
-         return [[nsv_incr ids next]]
+         return [nsv_incr ids next]
+     }
@@ Line 54: / Line 54: @@
 Another useful feature of nsv is the [[nsv_array]] command which works much like the Tcl array command. This can be used to import and export values from ordinary Tcl arrays. For example, to copy from Tcl use:
-     nsv_array set meta [[array get tmpmeta]]
+     nsv_array set meta [array get tmpmeta]
 and to copy to Tcl use:
-     array set metacopy [[nsv_array get meta]]
+     array set metacopy [nsv_array get meta]
 As with all other nsv command, [[nsv_array]] is atomic and no explicit locking is required. This feature can be used to contruct a new nsv array by first filling up an ordinary temporary Tcl array via some time consuming process and then swapping it into place as above. While the new temporary array is being constructed, other threads can access the old array without delay or inconsistant data. You can even reset a complete nsv array in one step with "reset". For example, instead of:
      ns_share lock meta
-     set lock [[ns_mutex create]]
+     set lock [ns_mutex create]
      ns_mutex lock $lock
      unset meta
-     array set meta [[array get tmpmeta]]
+     array set meta [array get tmpmeta]
      ns_mutex unlock $lock
 you can simply use:
-     nsv_array reset meta [[array get tmpmeta]]
+     nsv_array reset meta [array get tmpmeta]
 The reset option will flush and then reset all values atomically, eliminating the need for the explicit lock.
@@ Line 100: / Line 100: @@
      ns_share myshare
-     set myshare(lock) [[ns_mutex create]]
+     set myshare(lock) [ns_mutex create]
 use instead:
-     nsv_set myshare lock [[ns_mutex create]]
+     nsv_set myshare lock [ns_mutex create]
 In your procedures, instead of:
@@ Line 115: / Line 115: @@
      proc myproc {} {
-         ns_mutex lock [[nsv_get myshare lock]]
+         ns_mutex lock [nsv_get myshare lock]
          ...
@@ Line 130: / Line 130: @@
      <%
-         ns_puts [[nsv_get myshare key1]]
+         ns_puts [nsv_get myshare key1]
      %>
-     <%=[[nsv_get myshare key2]]%>
+     <%=[nsv_get myshare key2]%>
 Notice that, unlike [[ns_share]], no command is required to define the shared array. The first attempt at setting the variable through any means will automaticaly create the array. Also notice that only arrays are supported. However, to migrate from [[ns_share]] you can simply package up all existing [[ns_share]] scalars into a single array with a short name, perhaps just ".". For example, if you had:
@@ Line 139: / Line 139: @@
      ns_share mylock myfile
      set myfile /tmp/some.file
-     set mylock [[ns_mutex create]]
+     set mylock [ns_mutex create]
 you can use:
      nsv_set . myfile /tmp/some.file
-     nsv_set . mylock [[ns_mutex create]]
+     nsv_set . mylock [ns_mutex create]
 ----
 [[Category Documentation]] - [[Category Core Tcl API]]