ns_cache

Overview

Work with Tcl cache

Syntax

ns_cache create ?-maxentries maxentries? ?-maxentrysize size? ?-maxentryage maxage? ?-prunepercentage percentage? ?-maxlifetime maxlifetime? ?-maxkbytestocache kbytes?

ns_cache destroy cacheid

ns_cache disable cacheid

ns_cache enable cacheid

ns_cache enabled cacheid

ns_cache eval cacheid proc ?max_result_age?

ns_cache getprop cacheid { maxentries | maxentrysize | maxentryage | maxlifetime | prunepercentage | maxkbytestocache }

ns_cache prune cacheid ?-all? ?-key key-pattern? ?-count count? ?-tocount tocount? ?-age age?

ns_cache setprop cacheid ?-maxentries maxentries? ?-maxentrysize size? ?-maxentryage maxage? ?-prunepercentage percentage? ?-maxlifetime maxlifetime? ?-maxkbytestocache kbytes?

ns_cache stats cacheid { entries | hits | cachehits | reusehits | hitratio | reuseratio | bytescached }

ns_cache stats cache reset

ns_cache create

ns_cache create creates a Tcl cache with the specified properties and returns a cache identifier. The cache is enabled by default.

The maxentries argument specifies the maximum number of entries that can be in this cache. The default is that there is no limit.

The size argument specifies the maximum number of bytes per entry that will be cached. If the data to be cached is greater than size, it won't be cached. The default is that there is no limit.

The maxage argument specifies the maximum amount of time in seconds (since it was last accessed) that an entry should stay in the cache. The default is that there is no limit.

The percentage argument specifies the percentage of cache entries that should be pruned when maxentries is reached. Specifying 0 (zero) specifies that the cache should not be pruned. The default is 10%.

The maxlifetime argument specifies the maximum amount of time in seconds (since it was orginally put into the cache) that an an entry should stay in the cache.

The kbytes argument specifies the total number of kilobytes to keep in the cache.

ns_cache destroy

ns_cache destroy destroys the cache identified by the specified cacheid.

ns_cache disable

ns_cache disable disables the cache. When the cache is disabled, ns_cache eval always invokes the given procedure. The statistics gathering mechanism is also disabled.

ns_cache enable

ns_cache enable enables the cache. When the cache is enabled, ns_cache eval will attempt to get the cached result of the given procedure if appropriate.

ns_cache enabled

ns_cache enabled returns false if the specified cache is disabled and true if it is enabled.

ns_cache eval

ns_cache eval either evaluates the specified procedure or gets its cached result, based on the following criteria. If proc is currently cached, the cached value is returned, assuming that the age of the data is younger than max_result_age (if specified) and younger than the maxlifetime specified in ns_cache create. The age of the data is calculated based on when the proc was initially cached, not on when it was last accessed.

If proc is not currently cached, proc is evaluated and the result it cached. This also updates the stats kept on the cache entry.

The proc can be a single procedure name, or it can be a script enclosed in braces. In the latter case, it is best to keep the script as short as possible, because it will be used as a lookup key in the cache.

Note that Tcl scripts are parsed when they are cached, but they are not evaluated. Parsed scripts are stored in the cache, identified only by the name of the script. When a Tcl script is invoked, it is evaluated from the parsed version in the cache (according to the criteria described above) with the arguments passed to it.

ns_cache getprop

ns_cache getprop gets the specified property for the cache identified by cacheid. For all of the choices except prunepercentage, a value of -1 indicates that there is no limit for the property. See the description of ns_cache create for information on each property.

ns_cache prune

ns_cache prune flushes the cache entries that meet the specified criteria and returns the number of entries pruned.

If -all is specified, flush all entries.

If -key is specified, prune all entries whose keys match the given key-pattern.

If -count is specified, prune the number of last recently-used entries specified by count.

If -tocount is specified, prune all entries except the number of last recently-used entries specified by tocount.

If -age is specified, prune entries that haven't been used in the number of seconds specified by age.

If none of the above switches are specified, the prune percentage of the cache is used to prune that percentage of entries. Also, any entries that violate the cache's properties are removed.

If more than one switch is supplied, they're evaluated in the order specified.

The following example flushes all the entries with keys that start with bork, then will flush those that haven't been accessed in 500 seconds, and then will flush 50 of those that remain. (The order of the flushing will be in the reverse order from when they were last used):

    ns_cache prune $cache -key "bork.*" -age 500 -count 50

The following example will flush the 'oldest' 50, then those that match bork, then those that haven't been used in 500 seconds or more.

    ns_cache prune $cache -count 50 -key "bork.*" -age 500

Note: Pruning is time-stamp based (with a granularity of one second), not FIFO. So if you have several cache entries of exactly or nearly the same age, the order in which they are pruned is arbitrary.

ns_cache setprop

ns_cache setprop changes the specified properties of the cache identified by cacheid. Refer to the description for ns_cache create for information on each property. For all of the parameters except percentage, specifying a value of -1 indicates that there is no limit for the given property.

ns_cache stats

ns_cache stats returns one of the following items of information about the cache:

entries: the number of items in the cache

hits: the number of lookups that were done, whether they succeeded or not

cachehits: the number of lookups that found a result in the cache

reusehits: the number of lookups that found a result that wasn't expired yet

hitratio: the fraction of lookups that came from the cache (cachehits divided by total hits)

reuseratio: the fraction of lookups that came from the cache and haven't expired yet (reusehits divided by total hits)

bytescached: the number of bytes in the cache

ns_cache stats cache reset

ns_cache stats cache reset zeroes out the cache statistics.