NaviServer - programmable web server

[ Main Table Of Contents | Table Of Contents | Keyword Index ]

# ns_cache(n) 4.99.8 naviserver "NaviServer Built-In Commands"

## Name

ns_cache - Cache manipulation

## Table Of Contents

## Synopsis

- ns_cache_create ?-timeout t? ?-expires t? ?-maxentry s? ?--? name size
- ns_cache_names
- ns_cache_keys ?-exact? ?--? name ?pattern?
- ns_cache_eval ?-timeout t? ?-expires t? ?-force bool? ?--? name key script ?args?
- ns_cache_get name key ?varName?
- ns_cache_incr ?-timeout t? ?-expires t? ?--? name key ?incr?
- ns_cache_append ?-timeout t? ?-expires t? ?--? name key args
- ns_cache_lappend ?-timeout t? ?-expires t? ?--? name key args
- ns_cache_flush ?-glob? ?--? name ?args?
- ns_cache_stats ?-contents? ?-reset? ?--? name
- ns_fastpath_cache_stats ?-contents? ?-reset? ?--? name

## Description

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.

## OPTIONS

The following options are used for several commands below.

-timeout t

  The time in seconds to wait for some other thread to compute the cache value.

-expires t

  A time in the future when the cache value expires. The expired value will be deleted only when retrieved, e.g. via ns_cache_eval.

  The -expires time can be expressed either as an absolute time in the future (the number of seconds since 190), or as an offset from the current time. Small values are treated as offsets, large values as absolute time. It is slightly less efficient to specify an offset as the current time must be looked up.

## COMMANDS

ns_cache_create ?-timeout t? ?-expires t? ?-maxentry s? ?--? name size

  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).

ns_cache_names

  Return the list of all caches for the current virtual server.

ns_cache_keys ?-exact? ?--? name ?pattern?

  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.

ns_cache_eval ?-timeout t? ?-expires t? ?-force bool? ?--? name key script ?args?

  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.

ns_cache_get name key ?varName?

  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).

ns_cache_incr ?-timeout t? ?-expires t? ?--? name key ?incr?

  Increment the integer value in the cache by 1, or by incr if specified, and return it.

ns_cache_append ?-timeout t? ?-expires t? ?--? name key args

  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.

ns_cache_lappend ?-timeout t? ?-expires t? ?--? name key args

  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.

ns_cache_flush ?-glob? ?--? name ?args?

  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.

ns_cache_stats ?-contents? ?-reset? ?--? name

  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:

  maxsize

    The maximum size in bytes this cache can grow to, as specified by the -size option to ns_cache_create.

  size

    The current size of the cache, in bytes.

  entries

    The current number of entries the cache contains.

  flushed

    Number of entries which were explicitly flushed by the ns_cache_flush command.

  hits

    Number of times cache was queried and entry was present and valid.

  missed

    Number of times cache was queried and entry was not present or valid.

  hitrate

    The successful hit rate expressed as a percentage of total hits. Higher is better.

  expired

    Number of times an entry was found to be present but expired when requested and so not returned.

  pruned

    Number of time an entry reached the end of the LRU list and was removed to make way for a new entry.

ns_fastpath_cache_stats ?-contents? ?-reset? ?--? name

  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.

## EXAMPLES

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]

## See Also

ns_memoize, ns_time, nsv

## Keywords

cache, fastpath