SREhttp/2 Manual||
SSIs||
SSIcache||
SSI_VARS ||
View cache entries
SREhttp/2 and SSI-Caching
To improve performance, SREhttp/2 will "cache" HTML documents that
have server side includes (SSI). This caching is of the document
after the SSIs have been performed.
In simple cases SREhttp/2 can send this cached file, without having to repeat the actual
process of SSI lookups, etc. Needless to say, this can greatly
improve server performance.
Basic Description
First, let us define some terms:
- Static SSIs
- Static SSIs are those that do not change over time and client.
over time. For example, the <!-- REPLACE CREATION -->
should rarely change (the creation date of the document file).
Another example is <!-- INCLUDE filename
-->,
given that the contents of filename does not change.
- Dynamic SSIs
- Dynamic SSIs are those that will change over time and client.
The simplest example is <!-- REPLACE TIME -->.
Somewhat less
obvious are the several conditional options, such as:
Although these options may yield unchanging values,
it's likely that
(at least occasionally), the values will depend on the client,
time of day, or some other varying factor.
- Simple cases
- Simple cases are HTML documents that only
contain static SSIs.
It's not hard to see that the caching of simple cases
yields immediate benefits. This is especially true as the number and size
of static SSIs increases. For example, if you use HEADERS,
FOOTERS, and <!-- INCLUDE filename --> SSIs to maintain
a standard set of backgrounds and menu bars, the advantages of
caching can be substantial.
In non-simple cases, caching is more complex. SREhttp/2's
caching procedure solves this problem by using the following strategy:
- The raw HTML document (the one containing the SSI keyphrases) is
read in.
- Static server side includes are performed.
- Dynamic server side includes are noted, with placeholders
inserted.
- After saving this partially processed file to the cache,
dynamic SSI's are then resolved. The resulting text is
sent to the client.
Since SSIs are iterative, this might entail another
round of processing (say, of REPLACE keyphrases in an INCLUDEd file). This
later round is not cached.
When a new request for the raw HTML document is recieved, the
TRIGGERS and DURATION are checked. If either of these are out of date,
the cache entry is not used. Otherwise, the cached file (from step 4)
is read, the dynamic SSIs (from step 3) are resolved, and
the resulting document is sent to the client.
While not as quick as simple cases, the pre-processing of
static SSIs does improve performance.
Configuring the SREhttp/2 SSI-Cache
Configuration of the SREhttp/2 SSI-Cache is done via:
- ii)The
<!-- CACHE argument -->
server side include
keyphrases.
<!-- CACHE argument -->
can be used to set file-specific caching directive. They are described below.
- iii)Advanced controls
- Ambitious programmers can also modify a few SSI-cache parmeters that are set
in SREH2INI.RXX
The CACHE keyword
To set ssi-caching directives you can use
the <!-- CACHE option -->
SSI keyphrase. The following lists
the currently valid directives:
- <!-- cache no --> or <!-- cache off -->
- Do not cache this document. This means that each time the document
is requested, all of its SSIs will be regenerated.
- <!-- cache asis -->
- Use a cached version "as is". This means that when this document is
first requested, the SSIs will be
resolved. The resulting text will be saved to the cache (and also
sent to the client). All subsequent requests for this document will be sent
this cached result without further modification.
Thus, if you have dynamic SSIs (such as the current time), they will not be
updated. Therefore .....
<!-- cache asis --> should be used with care!
To force SREhttp/2 to update a ASIS cache, you can modify the
HTML file (or update its timestamp). Alternatively, include a DURATION
CACHE directive.
- <!-- cache notrigger -->
- Do not check the trigger files; but do check the own
file. In particular, the various INCLUDEd files
will not be checked (nor will any explicitly mentioned
trigger files be checked). One can think of
notrigger
as
a subset of asis
.
- <!-- cache duration nnn --> or <!-- cache days nnn -->
- Set the lifespan for this file's cache entry.
After nnn (possibly fractional) days,
the cached entry will be removed. Note that
if this is not specified, a default of 1 day is used.
- <!-- cache hours hhh -->
- Same as <!-- cache duration-->, except hhh is
interpreted as hours (not as days)
- <!-- cache trigger file1 file2 .. -->
- Check the file-stamps for these fully
qualified files.
If any of them have changed (since the time the cached file was
created), then do not use the cached file (the
entry will be recreated).
Notes:
- The own file name is always implicitly included in the
trigger list (regardless of asis or duration settings).
- The list of INCLUDEd files may be included in the
trigger list.
- <!-- cache trigger_type stamp -->
- Selects which field(s) of the trigger file-stamps
to check.
stamp can take one of the following values:
DATE TIME DATETIME SIZE ALL. By default, ALL is used.
Note that you can only use one of these five stamps.
Hints, Cautions, and other miscellaneous Notes
- The SSI-cache only caches files that are
subject to server side includes.
- If a document only has static SSIs
(that is, no TIME, HITS, INTERPRET, or any other SSIs that
might depend on time, client identity,
or other varying factors); then it is treated as an asis document.
- Non-asis documents are partially cached -- the cache file is
first processed for dynamic SSIs, and then sent to the client.
This yields a more "accurate" document, but it's not as fast as
returning asis entries.
- Once the number of files exceeds FILECACHE_MAXFILES (as set in SREH2INI.RXX with
a typical value of 500), the oldest
entries will be deleted (where oldest is measured in terms of
"last request").
- If you use the
asis
or notrigger
CACHE directives,
the quickest way to reset the cache entry
is by touching the document's file (say, by modifying its creation time).
- Cache entries are host-specific -- the same file delivered
by different hosts will have seperate cache entries.
- To suppress use of the SSI-Cache on a request specific basis, you can use SREhttp/2's
!FORCE/a_url special directive.