[
Table Of Contents
| Keyword Index
]
ns_cache(n) 4.99.2 "NaviServer Built-In Commands"
ns_cache - Cache manipulation
TABLE OF CONTENTS
SYNOPSIS
DESCRIPTION
COMMANDS
OPTIONS
EXAMPLES
SEE ALSO
KEYWORDS
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 expirey 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 recognise 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.
- ns_cache_create ?-timeout t? ?-expires t? ?-maxentry s? ?--? name size
-
Create a new Tcl cache identified by name with maximum size size.
- ns_cache_names
-
Return the list of all caches for the current virtual server.
- ns_cache_keys 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.
- 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_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 expirey 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.
- -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 futre (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.
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
personalised 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
personalised_adverts
where userid = :userid
}
}]
} errmsg]} {
ns_returnunavailable "Sorry, our web server is too busy."
}
ns_return 200 text/html [example_personalised_page $user $ad]
|
ns_memoize , nsv
cache