ns_cache - Cache manipulation
The cache commands store key-value data in memory for quick access, like nsv. Unlike nsv, a limit is placed on the amount of memory used for each cache, and additional limits can be placed on the expire time of cache entries, timeouts waiting for updates, etc.
The cache commands try to be efficient. For example, if two threads are simultaneously accessing the same entry in a cache, and the cache entry does not exist or has expired, then the first thread will evaluate it's script to generate the new value. The second thread will recognize this and wait for the first thread to finish, and then return the value computed by the first thread.
A cache will tend to grow to it's maximum specified size. Unused entries will move towards the end of the Least Recently Used list and be deleted to make room for new entries. Similarly, expired entries will remain in the cache and only be deleted when they reach the end of the LRU list, or are accessed and it is noticed that they have expired.
The following options are used for several commands below.
Create a new Tcl cache identified by name with maximum size size. Optionally, one can specify a default -timeout and a default -expires and the maximum size of a single entry (parameter -maxentry).
Return the list of all caches for the current virtual server.
Return a list of all keys in the named cache. If pattern is given then each key is matched against the globbing pattern, and only those which match are included in the list. When the option -exact is used, pattern is interpreted literally, either a key with a literally exact match or empty is returned.
Return the data identified by key from the named cache. If the key does not exist then script is executed, its value is returned and inserted into the cache.
The script is also executed if a cached value exists but has expired.
If the -force option is set then any existing cached value is removed whether it has expired or not, and the script is run to regenerate it.
Get the cached value for the provided key from the cache. If the optional variable name is not provided, it returns the associated value on success or it raises an error, if the key does not exist. If the optional variable name is provided it returns 1 or 0 on success / failure and sets the provided variable with the associated value (similar to nsv_get).
Increment the integer value in the cache by 1, or by incr if specified, and return it.
Append the given args to the value in the cache and return the new value. The args and the cache value are treated as simple strings.
If the cache value does not already exist it is created.
Append the given args to the value in the cache and return the new value. The cache value is as a Tcl list and the args are appended to maintain it's well-formed-list format.
If the cache value does not already exist it is created.
Flush the entries in a cache. If
The number of entries flushed are returned. If args are given then they are the keys in the cache to be flushed. If the -glob option is given then the keys are treated as globbing patterns and only the keys which match are flushed.
Return the accumulated statistics for the given cache name in array-get format since the cache was created or was last reset.
If the -reset option is given then the statistics will be reset to zero after the command returns.
If the -contents option is given then the first element of the returned list contains the size and expire time for each entry in the cache. The time is in ns_time timespec format. The cache statistics track the following items:
The maximum size in bytes this cache can grow to, as specified by the -size option to ns_cache_create.
The current size of the cache, in bytes.
The current number of entries the cache contains.
Number of entries which were explicitly flushed by the ns_cache_flush command.
Number of times cache was queried and entry was present and valid.
Number of times cache was queried and entry was not present or valid.
The successful hit rate expressed as a percentage of total hits. Higher is better.
Number of times an entry was found to be present but expired when requested and so not returned.
Number of time an entry reached the end of the LRU list and was removed to make way for a new entry.
Return the accumulated statistics for fastpath cache in array-get format since the cache was created or was last reset. For details, see ns_cache_stats above.
In the following example our goal is to serve a web page within 5 seconds. The web page requires two sets of data: the user's name and email address, and a personalized advert, both of which are stored in a database.
The data doesn't change often so a cache is used to speed up access. Even so, the server may become so busy that database queries take longer than our target response time of 5 seconds so we specify a -timeout to both calls to the ns_cache_eval command.
In this case, a time 5 seconds into the future is constructed once and passed to both cache calls. The second call will use the remainder of the time once the first completes.
set timeout [ns_time incr [ns_time get] 5] if {[catch { set user [ns_cache_eval -timeout $timeout -- users $userid { db_query { select name, email from users where userid = :userid } }] set ad [ns_cache_eval -timeout $timeout -expires 120 -- ads $userid { db_query { select advert from personalized_adverts where userid = :userid } }] } errmsg]} { ns_returnunavailable "Sorry, our web server is too busy." } ns_return 200 text/html [example_personalized_page $user $ad]