added docs for mod_cml

git-svn-id: svn:// 152afb58-edef-0310-8abb-c4023f1b3aa9
Jan Kneschke 2005-07-06 13:24:10 +00:00
parent 81368ccd4e
commit ab76910963
2 changed files with 160 additions and 2 deletions

View File

@ -29,7 +29,8 @@ access.txt \
traffic-shaping.txt \
setenv.txt \
status.txt \
scgi.txt \
HTMLDOCS=accesslog.html \
authentication.html \
@ -59,7 +60,8 @@ HTMLDOCS=accesslog.html \
traffic-shaping.html \
setenv.html \
status.html \
scgi.html \
EXTRA_DIST=lighttpd.conf lighttpd.user \
rc.lighttpd rc.lighttpd.redhat sysconfig.lighttpd \

doc/cml.txt Normal file
View File

@ -0,0 +1,156 @@
CML (Cache Meta Language)
Module: mod_cml
:Author: Jan Kneschke
:Date: $Date: 2004/11/03 22:26:05 $
:Revision: $Revision: 1.2 $
CML is a Meta language to describe the dependencies of a page at one side and building a page from its fragments on the other side
.. meta::
:keywords: lighttpd, cml
.. contents:: Table of Contents
CML (Cache Meta Language) wants to solves several problems:
* dynamic content needs caching to perform
* checking if the content is dirty inside of the application is usually more expensive than sending out the cached data
* a dynamic page is usually fragmented and the fragments have different livetimes
* the different fragements can be cached independently
Cache Decision
A simple example should show how to a content caching the very simple way in PHP. has a very simple design:
* the layout is taken from a template in templates/jk.tmpl
* the menu is generated from a menu.csv file
* the content is coming from files on the local directory named content-1, content-2 and so on
The page content is static as long non of the those tree items changes. A change in the layout
is affecting all pages, a change of menu.csv too, a change of content-x file only affects the
cached page itself.
If we model this in PHP we get: ::
## ... fetch all content-* files into $content
$cachefile = "/cache/dir/to/cached-content";
function is_cachable($content, $cachefile) {
if (!file_exists($cachefile)) {
return 0;
} else {
$cachemtime = filemtime($cachefile);
foreach($content as $k => $v) {
if (isset($v["file"]) &&
filemtime($v["file"]) > $cachemtime) {
return 0;
if (filemtime("/menu/menu.csv") > $cachemtime) {
return 0;
if (filemtime("/templates/jk.tmpl") > $cachemtime) {
return 0;
if (is_cachable(...), $cachefile) {
} else {
# generate content and write it to $cachefile
Quite simple. No magic involved. If the one of the files is new than the cached
content, the content is dirty and has to be regenerated.
Now let take a look at the numbers:
* 150 req/s for a Cache-Hit
* 100 req/s for a Cache-Miss
As you can see the increase is not as good as it could be. The main reason as the overhead
of the PHP interpreter to start up (a byte-code cache has been used here).
Moving these decisions out of the PHP script into a server module will remove the need
to start PHP for a cache-hit.
To transform this example into a CML you need 'index.cml' in the list of indexfiles
and the following index.cml file: ::
output.content-type text/html
output.include _cache.html
trigger.handler index.php
trigger.if file.mtime("../lib/php/menu.csv") > file.mtime("_cache.html")
trigger.if file.mtime("templates/jk.tmpl") > file.mtime("_cache.html")
trigger.if file.mtime("content.html") > file.mtime("_cache.html")
Numbers again:
* 4900 req/s for Cache-Hit
* 100 req/s for Cache-Miss
Content Assembling
Sometimes the different fragment are already generated externally. You have to cat them together: ::
We we can do the same several times faster directly in the webserver.
Don't forget: Webserver are built to send out static content, that is what they can do best.
The index.cml for this looks like: ::
output.content-type text/html
output.include head.html
output.include menu.html
output.include spacer.html
output.include db-content.html
output.include spacer2.html
output.include news.html
output.include footer.html
Now we get about 10000 req/s instead of 600 req/s.
the file extension that is bound to the cml-module
... will come later ...