Difference between revisions of "Ns cache"

From AOLserver Wiki
Jump to navigation Jump to search
(New page: '''NAME''' : '''ns_cache − Cache arbitrary data '''SYNOPSIS''' : '''ns_cache append''' ''cachename key string ?string ...?'' : '''ns_cache create''' ''cachename ?‐size maxsize? ?‐ti...)
 
Line 18: Line 18:
 
: '''ns_cache create''' ''cachename ?'' ‐size ''maxsize? ?''‐timeout ''timeout? ?''‐thread ''thread?''
 
: '''ns_cache create''' ''cachename ?'' ‐size ''maxsize? ?''‐timeout ''timeout? ?''‐thread ''thread?''
  
: This command creates a new cache named cachename. If ‐thread is given and is true, then it is a thread‐private cache. Otherwise  it is a global cache. If maxsize is given, then it is a sized-based cache. If timeout is given, then it is a timeout‐based cache. Otherwise, it is a timeout‐based cache with an infinite timeout, meaning it will never be flushed.
+
:: This command creates a new cache named cachename. If ‐thread is given and is true, then it is a thread‐private cache. Otherwise  it is a global cache. If maxsize is given, then it is a sized-based cache. If timeout is given, then it is a timeout‐based cache. Otherwise, it is a timeout‐based cache with an infinite timeout, meaning it will never be flushed.
  
: This command returns nothing if it is successful.
+
:: This command returns nothing if it is successful.
  
 
: '''ns_cache eval''' ''cachename key script''
 
: '''ns_cache eval''' ''cachename key script''
  
: This command atomically sets and gets a cache value. First, it looks up key in the cache named cachename. If it finds an entry, it returns the value of that entry. Otherwise, it executes script, stores the return value in the cache, and also returns that value.
+
:: This command atomically sets and gets a cache value. First, it looks up key in the cache named cachename. If it finds an entry, it returns the value of that entry. Otherwise, it executes script, stores the return value in the cache, and also returns that value.
  
: Script may optionally use the return command to return its value. For example, this will store the value "2" in mycache, if mykey is not already present:
+
:: Script may optionally use the return command to return its value. For example, this will store the value "2" in mycache, if mykey is not already present:
  
 
  ns_cache eval mycache mykey { expr {1+1} }
 
  ns_cache eval mycache mykey { expr {1+1} }
  
: This will also store the value "2" in mycache:
+
:: This will also store the value "2" in mycache:
  
 
  ns_cache eval mycache mykey { return [expr {1+1}] }
 
  ns_cache eval mycache mykey { return [expr {1+1}] }
  
: If script raises an error, or exits with break or continue, then  ns_cache eval simply returns the same condition without modifying the cache.
+
:: If script raises an error, or exits with break or continue, then  ns_cache eval simply returns the same condition without modifying the cache.
  
 
: '''ns_cache flush''' ''cachename key''
 
: '''ns_cache flush''' ''cachename key''
  
: This command removes the entry for key from the cache named cachename. If the cache has no entry for key, then nothing happens.
+
:: This command removes the entry for key from the cache named cachename. If the cache has no entry for key, then nothing happens.
  
: For global caches, ns_cache flush interacts with ns_cache eval. Suppose thread 1 has called get_thing A and is executing the long operation to compute the value for A. Thread 2 calls get_thing A and starts waiting for thread 1 to finish. Thread 3  calls ns_cache flush thing_cache A. Thread 1 will continue executing the long operation, but thread 2 will also start the long operation. When thread 1 completes the long operation, ns_cache eval returns the (now stale) value it computed, but it does not store the value in the cache. When thread 2 completes the long  operation, ns_cache eval stores the (fresh) value it computed in the cache and returns the fresh value.
+
:: For global caches, ns_cache flush interacts with ns_cache eval. Suppose thread 1 has called get_thing A and is executing the long operation to compute the value for A. Thread 2 calls get_thing A and starts waiting for thread 1 to finish. Thread 3  calls ns_cache flush thing_cache A. Thread 1 will continue executing the long operation, but thread 2 will also start the long operation. When thread 1 completes the long operation, ns_cache eval returns the (now stale) value it computed, but it does not store the value in the cache. When thread 2 completes the long  operation, ns_cache eval stores the (fresh) value it computed in the cache and returns the fresh value.
  
 
: '''ns_cache get''' ''cachename key ?varname?''
 
: '''ns_cache get''' ''cachename key ?varname?''
  
: This command looks up key in the specified cache. It operates differently depending on whether varname was given.
+
:: This command looks up key in the specified cache. It operates differently depending on whether varname was given.
  
: If varname absent and the key exists the value is returned and if the key is missing an error is raised. If varname is provided and the key exists the command sets varname to the value and returns 1, otherwise it returns 0.
+
:: If varname absent and the key exists the value is returned and if the key is missing an error is raised. If varname is provided and the key exists the command sets varname to the value and returns 1, otherwise it returns 0.
  
 
: '''ns_cache names''' ''cachename''
 
: '''ns_cache names''' ''cachename''
  
: This command returns a list of all keys currently in the specified cache.
+
:: This command returns a list of all keys currently in the specified cache.
  
 
: If the cache is thread‐private, then the list only includes keys that are in the thread’s private cache.
 
: If the cache is thread‐private, then the list only includes keys that are in the thread’s private cache.
Line 56: Line 56:
 
: '''ns_cache set''' ''cachename key value''
 
: '''ns_cache set''' ''cachename key value''
  
: This command stores value for key in the specified cache.
+
:: This command stores value for key in the specified cache.
  
 
'''CACHE TYPES'''
 
'''CACHE TYPES'''
Line 65: Line 65:
 
:: '''ns_cache create''' ''cachename'' ‐size ''maxsize''
 
:: '''ns_cache create''' ''cachename'' ‐size ''maxsize''
  
: Entries in a cache of this type are accessible to all threads. Each cache has its own mutex that protects access to its entries.
+
:: Entries in a cache of this type are accessible to all threads. Each cache has its own mutex that protects access to its entries.
  
: Cache values are stored as counted strings, so arbitrary binary data can be cached. A global cache stores strings instead of Tcl objects to prevent race conditions that could lead to heap corruption.
+
:: Cache values are stored as counted strings, so arbitrary binary data can be cached. A global cache stores strings instead of Tcl objects to prevent race conditions that could lead to heap corruption.
  
: The cache has a maximum size specified when the cache is created. The size of the cache is the sum of the sizes of all the values in the  cache; keys do not count toward a cache’s size. If inserting a value  into the cache makes the cache’s size exceed its maximum, then cache  entries are evicted starting with the least‐recently used entry until the size is below the maximum size (or until only the new value remains in the cache).
+
:: The cache has a maximum size specified when the cache is created. The size of the cache is the sum of the sizes of all the values in the  cache; keys do not count toward a cache’s size. If inserting a value  into the cache makes the cache’s size exceed its maximum, then cache  entries are evicted starting with the least‐recently used entry until the size is below the maximum size (or until only the new value remains in the cache).
  
 
: '''Global Time‐Limited Cache'''
 
: '''Global Time‐Limited Cache'''
Line 75: Line 75:
 
:: '''ns_cache create''' ''cachename'' '''‐timeout''' ''timeout''
 
:: '''ns_cache create''' ''cachename'' '''‐timeout''' ''timeout''
  
: Entries in a cache of this type are accessible to all threads. Each cache has its own mutex that protects access to its entries.
+
:: Entries in a cache of this type are accessible to all threads. Each cache has its own mutex that protects access to its entries.
  
: Cache values are stored as counted strings, as in a global size‐limited cache.
+
:: Cache values are stored as counted strings, as in a global size‐limited cache.
  
: The cache has a maximum entry lifetime, called its timeout, specified  (in seconds) when the cache is created. Every timeout seconds, AOLserver flushes all cache entries that have not were not created or  accessed in the last timeout seconds.
+
:: The cache has a maximum entry lifetime, called its timeout, specified  (in seconds) when the cache is created. Every timeout seconds, AOLserver flushes all cache entries that have not were not created or  accessed in the last timeout seconds.
  
 
: '''Thread‐Private Size‐Limited Cache'''
 
: '''Thread‐Private Size‐Limited Cache'''
Line 85: Line 85:
 
:: '''ns_cache create''' ''cachename'' '''‐size''' ''maxsize'' '''‐thread 1'''
 
:: '''ns_cache create''' ''cachename'' '''‐size''' ''maxsize'' '''‐thread 1'''
  
: Each thread in AOLserver automatically gets its own private cache named cachename. Since a thread‐private cache is only accessed by one thread, access to it does not require a mutex. Entries in one thread’s cache  are not visible to any other thread.
+
:: Each thread in AOLserver automatically gets its own private cache named cachename. Since a thread‐private cache is only accessed by one thread, access to it does not require a mutex. Entries in one thread’s cache  are not visible to any other thread.
  
: Cache values are stored as Tcl objects. When a value is stored in the cache, nscache computes its string form and uses the length of the string as the size of the value.
+
:: Cache values are stored as Tcl objects. When a value is stored in the cache, nscache computes its string form and uses the length of the string as the size of the value.
  
: The cache has a maximum size, like a global size‐limited cache. However, because of the way the cache value sizes are computed, the actual memory usage of the cache values may be several times larger than max size.
+
:: The cache has a maximum size, like a global size‐limited cache. However, because of the way the cache value sizes are computed, the actual memory usage of the cache values may be several times larger than max size.
  
: Thread‐private caches may offer higher performance if the cached values are complex objects such as lists or scripts, but require more storage than global caches.
+
:: Thread‐private caches may offer higher performance if the cached values are complex objects such as lists or scripts, but require more storage than global caches.
  
 
'''SEE ALSO'''
 
'''SEE ALSO'''
 
: [[nsv]]
 
: [[nsv]]

Revision as of 15:02, 31 January 2009

NAME

ns_cache − Cache arbitrary data

SYNOPSIS

ns_cache append cachename key string ?string ...?
ns_cache create cachename ?‐size maxsize? ?‐timeout timeout? ?‐thread thread?
ns_cache eval cachename key script
ns_cache flush cachename key
ns_cache get cachename key ?varname?
ns_cache incr cachename key ?value?
ns_cache lappend cachename key string ?string ...?
ns_cache names cachename
ns_cache set cachename key string

DESCRIPTION

AOLserver implements a C API for caching arbitrary data. This module provides a Tcl API on top of the C API. A cache, in this context, is simply a dictionary that maps keys to values. Keys are always stored as NUL‐terminated strings. How values are stored depends on the type of cache.
ns_cache create cachename ? ‐size maxsize? ?‐timeout timeout? ?‐thread thread?
This command creates a new cache named cachename. If ‐thread is given and is true, then it is a thread‐private cache. Otherwise it is a global cache. If maxsize is given, then it is a sized-based cache. If timeout is given, then it is a timeout‐based cache. Otherwise, it is a timeout‐based cache with an infinite timeout, meaning it will never be flushed.
This command returns nothing if it is successful.
ns_cache eval cachename key script
This command atomically sets and gets a cache value. First, it looks up key in the cache named cachename. If it finds an entry, it returns the value of that entry. Otherwise, it executes script, stores the return value in the cache, and also returns that value.
Script may optionally use the return command to return its value. For example, this will store the value "2" in mycache, if mykey is not already present:
ns_cache eval mycache mykey { expr {1+1} }
This will also store the value "2" in mycache:
ns_cache eval mycache mykey { return [expr {1+1}] }
If script raises an error, or exits with break or continue, then ns_cache eval simply returns the same condition without modifying the cache.
ns_cache flush cachename key
This command removes the entry for key from the cache named cachename. If the cache has no entry for key, then nothing happens.
For global caches, ns_cache flush interacts with ns_cache eval. Suppose thread 1 has called get_thing A and is executing the long operation to compute the value for A. Thread 2 calls get_thing A and starts waiting for thread 1 to finish. Thread 3 calls ns_cache flush thing_cache A. Thread 1 will continue executing the long operation, but thread 2 will also start the long operation. When thread 1 completes the long operation, ns_cache eval returns the (now stale) value it computed, but it does not store the value in the cache. When thread 2 completes the long operation, ns_cache eval stores the (fresh) value it computed in the cache and returns the fresh value.
ns_cache get cachename key ?varname?
This command looks up key in the specified cache. It operates differently depending on whether varname was given.
If varname absent and the key exists the value is returned and if the key is missing an error is raised. If varname is provided and the key exists the command sets varname to the value and returns 1, otherwise it returns 0.
ns_cache names cachename
This command returns a list of all keys currently in the specified cache.
If the cache is thread‐private, then the list only includes keys that are in the thread’s private cache.
ns_cache set cachename key value
This command stores value for key in the specified cache.

CACHE TYPES

ns_cache supports three types of caches:
Global Size‐Limited Cache
ns_cache create cachename ‐size maxsize
Entries in a cache of this type are accessible to all threads. Each cache has its own mutex that protects access to its entries.
Cache values are stored as counted strings, so arbitrary binary data can be cached. A global cache stores strings instead of Tcl objects to prevent race conditions that could lead to heap corruption.
The cache has a maximum size specified when the cache is created. The size of the cache is the sum of the sizes of all the values in the cache; keys do not count toward a cache’s size. If inserting a value into the cache makes the cache’s size exceed its maximum, then cache entries are evicted starting with the least‐recently used entry until the size is below the maximum size (or until only the new value remains in the cache).
Global Time‐Limited Cache
ns_cache create cachename ‐timeout timeout
Entries in a cache of this type are accessible to all threads. Each cache has its own mutex that protects access to its entries.
Cache values are stored as counted strings, as in a global size‐limited cache.
The cache has a maximum entry lifetime, called its timeout, specified (in seconds) when the cache is created. Every timeout seconds, AOLserver flushes all cache entries that have not were not created or accessed in the last timeout seconds.
Thread‐Private Size‐Limited Cache
ns_cache create cachename ‐size maxsize ‐thread 1
Each thread in AOLserver automatically gets its own private cache named cachename. Since a thread‐private cache is only accessed by one thread, access to it does not require a mutex. Entries in one thread’s cache are not visible to any other thread.
Cache values are stored as Tcl objects. When a value is stored in the cache, nscache computes its string form and uses the length of the string as the size of the value.
The cache has a maximum size, like a global size‐limited cache. However, because of the way the cache value sizes are computed, the actual memory usage of the cache values may be several times larger than max size.
Thread‐private caches may offer higher performance if the cached values are complex objects such as lists or scripts, but require more storage than global caches.

SEE ALSO

nsv