The Memory Cache

The memory cache (also known as the RAM cache) in Roxen is responsible for making sure that any page that does not need to be regenerated upon each request, isn't. Such pages can be served at greater speed right from from the cache instead, making the server more responsive and its visitors generally happier.

If all pages were static, they would always end up in the cache. Of course, the world is seldom that simple, and the cache needs to know a little bit more about just what pages can or can not be served from a previous rendering to gain some speed, so it does not cache all too enthusiastically. It is up to you as a programmer to help it make the proper decisions.

The cache is keyed with the raw URL (including prestates and query variables), and only GET requests without Authentication headers are cached. Since this also includes dynamic pages with the result of database queries and the like, such pages need to interact with the cache to make sure they are not overcached. This is done in pike with the two macros NOCACHE() and CACHE(seconds). In Java, it is done via the cache(seconds) and noCache() methods of the RoxenRequest class. For the Perl and CGI modules, all pages are currently never ever cached (both modules use the NOCACHE() macro internally).

If NOCACHE() has not been called sometime during the proceedings of a request, the reply is cached in the in-memory request-cache. Hence if, later on, a request for the same file with the same query and prestate parameters occurs, the in-memory entry will be used instead.

CACHE(seconds) limits the cache time to the number of seconds specified (NOCACHE() is actually just an alias for CACHE(0)). Hence if the same page gets called for within the number of seconds specified in the CACHE() macro, it will get sent from the cache. If, on the other hand, more time has passed, it will be regenerated.

This way, you may have as dynamic or as static pages as you like, and still always get optimum use of the memory cache to speed up things. Just remember that it is always up to you to instruct the cache of the cachability of results produced by your tags, modules or scripts, since it will assume that they can be put in the cache unless otherwise noted!

Note!

The CACHE() and NOCACHE() macros assume that id is the name of the RequestID variable.

You can, if you want closer manual supervision of what leaves the cache, you may install a per-page callback with

Roxen.add_cache_callback(RequestID id, function(RequestID,object:int) callback)

to add a callback that is called each time the file is to be sent from the cache. If your callback returns 1, the in-memory entry will be reused, otherwise not. If you also destruct() the second argument, the entry will be removed from the cache.

Note!

This callback will not be called for all pages leaving the cache, only for those given the same cache key (the raw URL) you installed the callback for.

Another alternative is

Roxen.add_cache_stat_callback(RequestID id, string file, int mtime)

This will case the (real) file specified as 'file' to be stat(2)ed for each request, if it's mtime differs from the supplied mtime, the entry is deleted from the cache. The 'main' file is always handled in this manner.