[0001]
[0002]
[0003]
[0004]
[0005]
[0006]
[0007]
[0008]
[0009]
[0010]
[0011]
[0012]
[0013]
[0014]
[0015]
[0016]
[0017]
[0018]
[0019]
[0020]
[0021]
[0022]
[0023]
[0024]
[0025]
[0026]
[0027]
[0028]
[0029]
[0030]
[0031]
[0032]
[0033]
[0034]
[0035]
[0036]
[0037]
[0038]
[0039]
[0040]
[0041]
[0042]
[0043]
[0044]
[0045]
[0046]
[0047]
[0048]
[0049]
[0050]
[0051]
[0052]
[0053]
[0054]
[0055]
[0056]
[0057]
[0058]
[0059]
[0060]
[0061]
[0062]
[0063]
[0064]
[0065]
[0066]
[0067]
[0068]
[0069]
[0070]
[0071]
[0072]
[0073]
[0074]
[0075]
[0076]
[0077]
[0078]
[0079]
[0080]
[0081]
[0082]
[0083]
[0084]
[0085]
[0086]
[0087]
[0088]
[0089]
[0090]
[0091]
[0092]
[0093]
[0094]
[0095]
[0096]
[0097]
[0098]
[0099]
[0100]
[0101]
[0102]
[0103]
[0104]
[0105]
[0106]
[0107]
[0108]
[0109]
[0110]
[0111]
[0112]
[0113]
[0114]
[0115]
[0116]
[0117]
[0118]
[0119]
[0120]
[0121]
[0122]
[0123]
[0124]
[0125]
[0126]
[0127]
[0128]
[0129]
[0130]
[0131]
[0132]
[0133]
[0134]
[0135]
[0136]
[0137]
[0138]
[0139]
[0140]
[0141]
[0142]
[0143]
[0144]
[0145]
[0146]
[0147]
[0148]
[0149]
[0150]
[0151]
[0152]
[0153]
[0154]
[0155]
[0156]
[0157]
[0158]
[0159]
[0160]
[0161]
[0162]
[0163]
[0164]
[0165]
[0166]
[0167]
[0168]
[0169]
[0170]
[0171]
[0172]
[0173]
[0174]
[0175]
[0176]
[0177]
[0178]
[0179]
[0180]
[0181]
[0182]
[0183]
[0184]
[0185]
[0186]
[0187]
[0188]
[0189]
[0190]
[0191]
[0192]
[0193]
[0194]
[0195]
[0196]
[0197]
[0198]
[0199]
[0200]
[0201]
[0202]
[0203]
[0204]
[0205]
[0206]
[0207]
[0208]
[0209]
[0210]
[0211]
[0212]
[0213]
[0214]
[0215]
[0216]
[0217]
[0218]
[0219]
[0220]
[0221]
[0222]
[0223]
[0224]
[0225]
[0226]
[0227]
[0228]
[0229]
[0230]
[0231]
[0232]
[0233]
[0234]
[0235]
[0236]
[0237]
[0238]
[0239]
[0240]
[0241]
[0242]
[0243]
[0244]
[0245]
[0246]
[0247]
[0248]
[0249]
[0250]
[0251]
[0252]
[0253]
[0254]
[0255]
[0256]
[0257]
[0258]
[0259]
[0260]
[0261]
[0262]
[0263]
[0264]
[0265]
[0266]
[0267]
[0268]
[0269]
[0270]
[0271]
[0272]
[0273]
[0274]
[0275]
[0276]
[0277]
[0278]
[0279]
[0280]
[0281]
[0282]
[0283]
[0284]
[0285]
[0286]
[0287]
[0288]
[0289]
[0290]
[0291]
[0292]
[0293]
[0294]
[0295]
[0296]
[0297]
[0298]
[0299]
[0300]
[0301]
[0302]
[0303]
[0304]
[0305]
[0306]
[0307]
[0308]
[0309]
[0310]
[0311]
[0312]
[0313]
[0314]
[0315]
[0316]
[0317]
[0318]
[0319]
[0320]
[0321]
[0322]
[0323]
[0324]
[0325]
[0326]
[0327]
[0328]
[0329]
[0330]
[0331]
[0332]
[0333]
[0334]
[0335]
[0336]
[0337]
[0338]
[0339]
[0340]
[0341]
[0342]
[0343]
[0344]
[0345]
[0346]
[0347]
[0348]
[0349]
[0350]
[0351]
[0352]
[0353]
[0354]
[0355]
[0356]
[0357]
[0358]
[0359]
[0360]
[0361]
[0362]
[0363]
[0364]
[0365]
[0366]
[0367]
[0368]
[0369]
[0370]
[0371]
[0372]
[0373]
[0374]
[0375]
[0376]
[0377]
[0378]
[0379]
[0380]
[0381]
[0382]
[0383]
[0384]
[0385]
[0386]
[0387]
[0388]
[0389]
[0390]
[0391]
[0392]
[0393]
[0394]
[0395]
[0396]
[0397]
[0398]
[0399]
[0400]
[0401]
[0402]
[0403]
[0404]
[0405]
[0406]
[0407]
[0408]
[0409]
[0410]
[0411]
[0412]
[0413]
[0414]
[0415]
[0416]
[0417]
[0418]
[0419]
[0420]
[0421]
[0422]
[0423]
[0424]
[0425]
[0426]
[0427]
[0428]
[0429]
[0430]
[0431]
[0432]
[0433]
[0434]
[0435]
[0436]
[0437]
[0438]
[0439]
[0440]
[0441]
[0442]
[0443]
[0444]
[0445]
[0446]
[0447]
[0448]
[0449]
[0450]
[0451]
[0452]
[0453]
[0454]
[0455]
[0456]
[0457]
[0458]
[0459]
[0460]
[0461]
[0462]
[0463]
[0464]
[0465]
[0466]
[0467]
[0468]
[0469]
[0470]
[0471]
[0472]
[0473]
[0474]
[0475]
[0476]
[0477]
[0478]
[0479]
[0480]
[0481]
[0482]
[0483]
[0484]
[0485]
[0486]
[0487]
[0488]
[0489]
[0490]
[0491]
[0492]
[0493]
[0494]
[0495]
[0496]
[0497]
[0498]
[0499]
[0500]
[0501]
[0502]
[0503]
[0504]
[0505]
[0506]
[0507]
[0508]
[0509]
[0510]
[0511]
[0512]
[0513]
[0514]
[0515]
[0516]
[0517]
[0518]
[0519]
[0520]
[0521]
[0522]
[0523]
[0524]
[0525]
[0526]
[0527]
[0528]
[0529]
[0530]
[0531]
[0532]
[0533]
[0534]
[0535]
[0536]
[0537]
[0538]
[0539]
[0540]
[0541]
[0542]
[0543]
[0544]
[0545]
[0546]
[0547]
[0548]
[0549]
[0550]
[0551]
[0552]
[0553]
[0554]
[0555]
[0556]
[0557]
[0558]
[0559]
[0560]
[0561]
[0562]
[0563]
[0564]
[0565]
[0566]
[0567]
[0568]
[0569]
[0570]
[0571]
[0572]
[0573]
[0574]
[0575]
[0576]
[0577]
[0578]
[0579]
[0580]
[0581]
[0582]
[0583]
[0584]
[0585]
[0586]
[0587]
[0588]
[0589]
[0590]
[0591]
[0592]
[0593]
[0594]
[0595]
[0596]
[0597]
[0598]
[0599]
[0600]
[0601]
[0602]
[0603]
[0604]
[0605]
[0606]
[0607]
[0608]
[0609]
[0610]
[0611]
[0612]
[0613]
[0614]
[0615]
[0616]
[0617]
[0618]
[0619]
[0620]
[0621]
[0622]
[0623]
[0624]
[0625]
[0626]
[0627]
[0628]
[0629]
[0630]
[0631]
[0632]
[0633]
[0634]
[0635]
[0636]
[0637]
[0638]
[0639]
[0640]
[0641]
[0642]
[0643]
[0644]
[0645]
[0646]
[0647]
[0648]
[0649]
[0650]
[0651]
[0652]
[0653]
[0654]
[0655]
[0656]
[0657]
[0658]
[0659]
[0660]
[0661]
[0662]
[0663]
[0664]
[0665]
[0666]
[0667]
[0668]
[0669]
[0670]
[0671]
[0672]
[0673]
[0674]
[0675]
[0676]
[0677]
[0678]
[0679]
[0680]
[0681]
[0682]
[0683]
[0684]
[0685]
[0686]
[0687]
[0688]
[0689]
[0690]
[0691]
[0692]
[0693]
[0694]
[0695]
[0696]
[0697]
[0698]
[0699]
[0700]
[0701]
[0702]
[0703]
[0704]
[0705]
[0706]
[0707]
[0708]
[0709]
[0710]
<!DOCTYPE html>
<!-- WASDOC AXP-2.0.0 (CGILIB AXP-1.9.9) -->
<!-- wasDOC Copyright (C) 2019,2020 Mark G.Daniel - Apache-2.0 licenced -->
<!-- 3-NOV-2021 02:50 -->
<noscript>NOTE: SOME FUNCTIONALITY EMPLOYS JAVASCRIPT</noscript>
<div id="erreport1" style="display:none;"></div>
<script>
function errorReport(string) {
for (var cnt = 1; cnt <= 2; cnt++) {
var err = document.getElementById('erreport'+cnt);
err.style.display = 'block';
err.innerHTML += string;
}
}
</script>
<style type="text/css">
html { font-family: arial, verdana, sans-serif; font-size:12pt; margin:1em; }
h1 { font-size:124%; font-style:bold;
margin-top:1em; margin-bottom:0.5em; }
h2 { font-size:120%; font-style:bold;
margin-top:1.1em; margin-bottom:0.4em; }
h3 { font-size:116%; font-style:bold;
margin-top:1.0em; margin-bottom:0.3em; }
h4 { font-size:112%; font-style:bold;
margin-top:1.1em; margin-bottom:0.3em; }
h5 { font-size:112%; font-style:bold;
margin-top:1.1em; margin-bottom:0.3em; }
h6 { font-size:112%; font-style:bold; padding:0; margin:0; }
h1 .text { text-decoration:underline; }
h1 .numb { padding-right:0.8em; }
h1 .numb:empty { display:none; padding-right:0; }
h2 .numb { padding-right:0.8em; }
h2 .numb:empty { display:none; padding-right:0; }
h3 .numb { padding-right:0.8em; }
h3 .numb:empty { display:none; padding-right:0; }
h4 .numb { padding-right:0.8em; }
h4 .numb:empty { display:none; padding-right:0; }
h5 .numb { display:none; padding-right:0; }
h6 .numb { display:none; padding-right:0; }
kbd { font-family:monospace; }
noscript { font-size:1.2em; }
p { line-height:1.1em; margin-top:1em; margin-bottom:1em; }
.chunk { font-size:130%; text-decoration:underline; }
.head {}
.high {}
.bold { font-weight:bold; }
.center { text-align:center; }
.italic { font-style:italic; }
.left { text-align:left; }
.nowrap { white-space:nowrap; }
.prewrap { white-space:pre; }
.right { text-align:right; }
.strike { text-decoration:line-through; }
.under { text-decoration:underline; }
.backlight { background-color:#f2f2f2; }
.display0 { display:none; }
img { max-width:100%; }
.imglink { }
.link { }
.blank { }
.list { margin-bottom:1em; }
.list li { margin-top:0.5em; }
.list0 li { margin-top:0; }
.item {}
.tabl { border-collapse:collapse; text-align:left; margin:0.4em 2em 0.5em 2em; }
.tabu { border-collapse:collapse; text-align:right; margin:0.4em 2em 0.5em 2em; }
.tabr { vertical-align:top; }
.tabh { padding:0.2em 0 0 2em; margin:0; }
.tabd { padding:0.1em 0 0 2em; margin:0; }
.tabh:first-of-type, td:first-of-type { padding-left:0; }
.tabu .tabh,
.tabu .tabd { border:1px solid gray; padding:0.2em 0.3em 0.2em 0.3em; }
.tab0 { border:none; visibility:hidden; max-width:1em;
white-space:nowrap; overflow:hidden; }
.tabauto { margin-left:auto; margin-right:auto; }
.tabr:empty { height:0.2em; }
.tabu .tabh:empty, .tabu .tabd:empty { border:none; visibility:hidden; }
.error { font-size:110%; color:black; background-color:yellow;
font-family:sans-serif; font-weight:bold; font-style:normal;
width:95%; border:solid 1px gray; padding:0.5em 1em 0.5em 1em; }
.error::before { content:'\026a0\00a0'; }
.image { }
.page { width:98%; border:1px dashed gray; margin:1.5em 0 1.8em 0; }
.epage { width:98%; border:1px dashed black; margin:1.5em 0 1.8em 0; }
.monosp { font-family:monospace; }
.ppage { display:none; }
.simple { list-style-type:none; }
.valtop { vertical-align:top; }
.valmid { vertical-align:middle; }
.valbot { vertical-align:bottom; }
.code { border-style:solid; border-width:0 0 0 1px; padding-left:1em;
font-family:monospace; white-space:pre; }
.block { }
.blockof { margin:0.4em 2em 0.5em 2em; }
.example { border-style:dashed; border-width:0 0 0 1px; padding-left:1em;
margin-top:0.5em; margin-bottom:0.5em; white-space:pre; }
.indent { margin-left:2em; margin-right:2em; }
.noindent { margin-left:0; margin-right:0; }
.inblock { display:inline-block; }
.mono { white-space:pre; font-family:monospace; }
.note { margin:0.4em 2em 0.5em 2em; page-break-inside:avoid; }
.note h5 { margin-top:0 }
.note_hr { width:80%; border:1px solid gray; }
.prop { padding-left:1em; margin-top:0.5em; margin-bottom:0.5em; }
.quote { border-style:dashed; border-width:0 0 0 1px; padding-left:1em;
margin-top:0.5em; margin-bottom:0.5em; }
.this { display:none; }
a:link,a:visited { color:black; text-decoration:none; }
a:hover,a:active { text-decoration:underline; }
a:focus { outline:0; }
:target:before { content:''; display:block; height:0.1em; margin:-0.1em; }
a.link:link, a.link:visited,a.link:active
{ color:midnightBlue; text-decoration:underline; text-decoration-style:solid; }
.TOC1cols1 { width:80%; max-width:80%; }
.TOC1cols2 { column-count:2; width:80%; max-width:80%; }
.TOC1cols3 { column-count:3; max-width:90%; max-width:90%; }
.TOC1cols4 { column-count:4; max-width:100%; max-width:100%; }
.TOC1table { margin-left:2em; white-space:nowrap; break-inside:auto; }
.TOC1table tr { vertical-align:top; text-align:left; break-inside:avoid; break-after:auto; }
.TOC1table td+td { padding:0 0 0 0.5em; }
.TOC1table .numb { width:3em; max-width:3em; }
.TOC1table .sepr { width:5em; max-width:6em; overflow:hidden; }
.TOC1table .majr { font-weight:bold; }
.TOC1table .text { white-space:normal; }
/* These are due to Firefox (at least <= 76) recalcitrant multi-column handling.
Web search "Split table into css columns, issue in Firefox" (stackoverflow).
"Good grief, Charlie Brown!" */
.TOC1cols2 table,
.TOC1cols2 tbody,
.TOC1cols2 tr,
.TOC1cols3 table,
.TOC1cols3 tbody,
.TOC1cols3 tr,
.TOC1cols4 table,
.TOC1cols4 tbody,
.TOC1cols4 tr { display:block; padding:0; }
.TOC2cols1 { width:60%; max-width:60%; }
.TOC2cols2 { column-count:2; width:70%; max-width:70%; }
.TOC2cols3 { column-count:3; width:80%; max-width:80%; }
.TOC2cols4 { column-count:4; width:90%; max-width:90%; }
.TOC2table { margin-left:2em; white-space:nowrap; break-inside:auto; }
.TOC2table tr { vertical-align:top; text-align:left; break-inside:avoid; break-after:auto; }
.TOC2table .numb { font-weight:bold; padding-right:0.5em; }
.TOC2table .text { width:100%; white-space:normal; }
/* see "recalcitrant" above */
.TOC2cols2 table,
.TOC2cols2 tbody,
.TOC2cols2 tr,
.TOC2cols3 table,
.TOC2cols3 tbody,
.TOC2cols3 tr,
.TOC2cols4 table,
.TOC2cols4 tbody,
.TOC2cols4 tr { display:block; padding:0; }
.NAVtable { margin:0.1em 0 0 2em; }
.NAVtable td { font-size:110%; font-weight:bold; padding:0; margin:0; }
.NAVtable a { padding:0 0.5em 0 0.5em; text-decoration:none; }
.IDXcols1 { width:80%; max-width:80%; }
.IDXcols2 { column-count:2; width:90%; max-width:90%; }
.IDXcols3 { column-count:3; width:95%; max-width:95%; }
.IDXcols4 { column-count:4; width:100%; max-width:100%; }
.IDXtable { margin:1em 0 1em 2em; white-space:nowrap; break-inside:auto; }
.IDXtable tr { vertical-align:top; text-align:left; break-inside:avoid; break-after:auto; }
.IDXtable .alpha { font-weight:bold; min-width:2em; }
.IDXtable .text { width:100%; white-space:normal; }
.IDXtable .para:before { content:'\00b6\00a0'; }
/* see "recalcitrant" above */
.IDXcols2 table,
.IDXcols2 tbody,
.IDXcols2 tr,
.IDXcols3 table,
.IDXcols3 tbody,
.IDXcols3 tr,
.IDXcols4 table,
.IDXcols4 tbody,
.IDXcols4 tr { display:block; padding:0; }
.insight { background-color:cyan; font-family:monospace;
padding:0 0.2em 0 0.2em; margin:0 0.2em 0 0.2em;
font-size:100%; font-style:normal; font-weight:normal;
text-decoration:none; }
.wasdoc { font-family: "Lucida Console", Monaco, monospace;
letter-spacing:-0.07em; }
@media screen { .blank::after { content:"\2924"; }
.print { display:none; }
}
@media print {
table { page-break-inside:avoid; }
.noprint { display:none; }
.page { border:none; page-break-after: always; }
.epage { display:none; }
.ppage { page-break-after:always; }
.NAVtable { display:none; }
.NAVprint { display:block!important; }
}
@page { margin:2cm 1cm 2cm 1cm; }
</style>
<!-- source:0000_config.wasdoc -->
<style type="text/css">._smiley::after { font-size:150%; vertical-align:middle; content:'\263a' }</style>
<style type="text/css">._frowny::after { font-size:150%; vertical-align:middle; content:'\2639' }</style>
<a id="0." href="#"></a>
<title>WASD Configuration – Cache Configuration</title>
<a id="9." href="#"></a>
<a id="9.cacheconfiguration" href="#"></a>
<a id="cacheconfiguration" href="#"></a>
<h1 class="head chunk">WASD Configuration</h1>
<h1 class="head"><span class="numb">9.</span><span class="text">Cache Configuration</span></h1>
<div class="TOC2cols2">
<table class="TOC2table">
<tr><td><a href="config009.html#9.1.nonfilecontentcaching"><span class="numb">9.1</span><span class="text">Non-File Content Caching</span></a>
<tr><td><a href="config009.html#9.2.permanentandvolatile"><span class="numb">9.2</span><span class="text">Permanent and Volatile</span></a>
<tr><td><a href="config009.html#9.3.cachesuitabilityconsiderations"><span class="numb">9.3</span><span class="text">Cache Suitability Considerations</span></a>
<tr><td><a href="config009.html#9.4.cachecontentvalidation"><span class="numb">9.4</span><span class="text">Cache Content Validation</span></a>
<tr><td><a href="config009.html#9.5.cacheconfiguration"><span class="numb">9.5</span><span class="text">Cache Configuration</span></a>
<tr><td><a href="config009.html#9.6.cachecontrol"><span class="numb">9.6</span><span class="text">Cache Control</span></a>
<tr><td><a href="config009.html#9.7.circumventingthecache"><span class="numb">9.7</span><span class="text">Circumventing The Cache</span></a>
</table>
</div>
<table class="NAVtable NAVprint"><tr>
<td><a href="javascript:window.history.back();">↩︎</a>
<td><a href="config008.html#8.">↖︎</a>
<td><a href="config000.html#0.">↑︎</a>
<td><a href="config010.html#10.">↘︎</a>
<td><a href="javascript:window.history.forward();">↪︎</a>
</table>
<p> WASD HTTPd provides an optional, configurable, monitorable file data and
revision time cache. File data, so that requests for documents can be fulfilled
without reference to the underlying file system, potentially reducing request
latency and more importantly improving overall server performance and system
impact, and file revision time, so that requests specifying an
"If-Modified-Since:" header can also benefit from the above. Files are cached
using a hash derived from the VMS file-system path equivalent generated during
the mapping process (i.e. represents the file name) but before any actual RMS
activity. WASD can also cache the content of responses from non-file sources.
This can be useful for reducing the system impact of frequently accessed,
dynamically generated, but otherwise relatively static pages. These sources
are cached using a hash derived from virtual service connected to and the
request URI.
<a id="9.0.0.0.1" href="#"></a>
<a id="9.whyimplementcaching" href="#"></a>
<a id="whyimplementcaching" href="#"></a>
<h5 class="head"><span class="text">Why Implement Caching?</span></h5>
<p> Caching, in concept, attempts to improve performance by keeping data in
storage that is faster to access than the usual location. The performance
improvement can be assessed in three basic ways; reduction of
<ul class="list list0">
<li class="item"> response when accessing the data (latency and transfer time)
<li class="item"> processing involved (CPU cycles)
<li class="item"> impact on the usual storage location (file system I/O)
</ul>
<p> This cache is provided to address all three. Where networks are
particularly responsive a reduction in request latency can often be noticeable.
It is also suggested a cache "hit" may consume less CPU cycles than the
equivalent access to the (notoriously expensive) VMS file system. Where
servers are particularly busy or where disk subsystems particularly loaded a
reduction in the need to access the file system can significantly improve
performance while simultaneously reducing the impact of the server on other
system activities.
<p> A comparison between cached and non-cached performance is provided in
in the "Server Performance" section.
<a id="9.0.0.0.2" href="#"></a>
<a id="9.terminology" href="#"></a>
<a id="terminology" href="#"></a>
<h5 class="head"><span class="text">Terminology</span></h5>
<table class="tabl">
<tr class="tabr under">
<th class="tabh">Term
<th class="tabh">Description
<tr class="tabr">
<tr class="tabr backlight">
<td class="tabd">hit
<td class="tabd">Refers to a request path being found in cache. If the data
is still valid the request can be supplied from cache.
<tr class="tabr">
<td class="tabd">flushing
<td class="tabd">Occurs when the cache becomes full, with older, less
frequently used cache entries being removed from the cache and replaced by
other files.
<tr class="tabr backlight">
<td class="tabd">loading
<td class="tabd">Refers to reading the contents of a file into cache memory.
<tr class="tabr">
<td class="tabd">permanent
<td class="tabd">These entries are loaded once and remain in the cache
until it is explicitly purged by the administrator or the the server is
restarted. They are not flushed or revalidated.
<tr class="tabr backlight">
<td class="tabd">revalidate
<td class="tabd">Compare the cache entrys size and modification
date-time to the file it represents in the file-system. Obviously a difference
indicates the content has changed.
<tr class="tabr">
<td class="tabd">valid
<td class="tabd">The file from which the cached data was
originally read has not had its revision date changed (the implication being
the file contents have not changed).
<tr class="tabr backlight">
<td class="tabd">volatile
<td class="tabd">Entries have the original file periodically checked for
modification and are reloaded if necessary. They can also be flushed if
demand for space requires it.
</table>
<a id="9.1" href="#"></a>
<a id="9.1.nonfilecontentcaching" href="#"></a>
<a id="nonfilecontentcaching" href="#"></a>
<h2 class="head"><span class="numb">9.1</span><span class="text">Non-File Content Caching</span></h2>
<p> The WASD cache was originally provided to reduce file-system access (a
somewhat expensive activity under VMS). With the expansion in the use of
dynamically generated page content (e.g. PHP, Perl, Python) there is an obvious
need to reduce the system impact of some of these activities. While many such
responses have content specific to the individual request a large number are
also generated as general site pages, perhaps with simple time or date
components, or other periodic information. Non-file caching is intended for
this type of dynamic content.
<p> Revalidation of non-file content is fraught with a number of issues and so
is not provided. Instead the cache entry is flushed on expiry of the
[CacheValidateSeconds], or as otherwise specified by path mapping, and the
request is serviced by the content source (script, PHP, Perl, etc.) with the
generated response being freshly cached. All of the considerations described in
<a class="link" href="config009.html#9.4.cachecontentvalidation">9.4 Cache Content Validation</a> apply equally to file and non-file content.
<a id="9.1.0.0.1" href="#"></a>
<a id="9.1.controllingnonfilecontentcaching" href="#"></a>
<a id="controllingnonfilecontentcaching" href="#"></a>
<h5 class="head"><span class="text">Controlling Non-File Content Caching</span></h5>
<p> Determining which non-file content is cached and which not, and how long
before flushing, is done using mapping rules (<a class="link" href="config010.html#10.5.5.setrule">10.5.5 SET Rule</a>). The source of
non-file cache content is specified using one or a combination of the following
SET rules against general or specific paths.
<ul class="list simple list0">
<li class="item"> <span class="high bold">cache=[no]cgi </span> from Common Gateway Interface (CGI) script response
<li class="item"> <span class="high bold">cache=[no]file </span> from the file system (default and pre-8.4 cache behaviour)
<li class="item"> <span class="high bold">cache=[no]net </span> caches the full data stream irrespective of the source
<li class="item"> <span class="high bold">cache=[no]nph </span> full stream from Non-Parse Header (NPH) script response
<li class="item"> <span class="high bold">cache=[no]query </span> cache requests with query strings (<span class="high bold">use with care</span>)
<li class="item"> <span class="high bold">cache=[no]script </span> both CGI and NPH script responses
<li class="item"> <span class="high bold">cache=[no]ssi </span> from Server-Side Includes (SSI) documents
</ul>
<p> A good understanding of site requirements and dynamic content sources,
along with considerable care in specifying cache path SETings, is required to
cache dynamic content effectively. It is especially important to get the
content revalidation period appropriate to the content of the pages. This is
specified using the following path SETings.
<ul class="list simple list0">
<li class="item"> <span class="high bold">cache=expires=0 </span> cancels any expiry
<li class="item"> <span class="high bold">cache=expires=DAY </span> expires when the day changes
<li class="item"> <span class="high bold">cache=expires=HOUR </span> when the clock hour changes
<li class="item"> <span class="high bold">cache=expires=MINUTE </span> when the clock minute changes
<li class="item"> <span class="high bold">cache=expires=<hh:mm:ss> </span> expires after the specified period in the cache
</ul>
<p> For example. To cache the content of PHP-generated home pages that
contain a time-of-day clock, resolving down to the minute, would require a
mapping rule similar to the following.
<div class="blockof code">set /**/index.php cache=cgi cache=expires=minute
</div>
<a id="9.2" href="#"></a>
<a id="9.2.permanentandvolatile" href="#"></a>
<a id="permanentandvolatile" href="#"></a>
<h2 class="head"><span class="numb">9.2</span><span class="text">Permanent and Volatile</span></h2>
<p> The WASD file cache provides for some resources to be permanently cached
while others are allowed to be moved into and out of the cache according to
demand. Most sites have at least some files that are fundamental components of
the site's pages, are rarely modified, commonly accessed, and therefore should
be permanently available from cache. Other files are modified on a regular or
ad hoc basis and may experience fluctuations in demand. These more volatile
resources should be cached based on current demand.
<p> Volatile caching is the default with the site administrator using mapping
rules to indicate to the server which resources on which paths should be
permanently cached (<a class="link" href="config009.html#9.cacheconfiguration">9. Cache Configuration</a>).
<p> Although permanent and volatile entries share the same cache structure and
are therefore subject to the configuration's maximum number of cache entries,
the memory used store the cached file data is derived from separate pools. The
total size of all volatile entries data is constrained by configuration. In
contrast there is no configuration limit placed on the quantity of data that
can be cached by permanent entries. One of the purposes of the permanent
aspect of the cache is to allow the site administrator considerable discretion
in the configuration of the site's low-latency resources, no matter how large
or small that might be. Of course there is the ultimate constraint of server
process and system virtual memory limits on this activity. It should also be
kept in mind that unless sufficient physical memory is available to keep such
cached content in-memory the site may only end up trading file-system I/O for
page file I/O.
<a id="9.3" href="#"></a>
<a id="9.3.cachesuitabilityconsiderations" href="#"></a>
<a id="cachesuitabilityconsiderations" href="#"></a>
<h2 class="head"><span class="numb">9.3</span><span class="text">Cache Suitability Considerations</span></h2>
<p> A cache is not always of benefit! the cost may outweigh the return.
<p> Any cache's efficiencies can only occur where subsets of data are
consistently being demanded. Although these subsets may change slowly over time
a consistent and rapidly changing aggregate of requests lose the benefit of
more readily accessible data to the overhead of cache management, due to the
constant and continuous flushing and reloading of cache data. This server's
cache is no different, it will only improve performance if the site experiences
some consistency in the files requested. For sites that have only a small
percentage of files being repeatedly requested it is probably better that the
cache be disabled. The other major consideration is available system memory.
On a system where memory demand is high there is little value in having cache
memory sitting in page space, trading disk I/O and latency for paging I/O and
latency. On memory-challenged systems cache is probably best disabled.
<p> To help assessment of the cache's efficiency for any given site monitor the
Server Administration facility's cache report.
<p> Two sets of data provide complementary information, cache activity and
file request profile.
<ul class="list">
<li class="item"> <span class="high bold">Activity Data</span>
<p> This summarizes the cache search behaviour, in particular that of the hash
table.
<p> The "searched" item, indicates the number of times the cache has
been searched. Most importantly, this may include paths that can never be
cached because they represent non-file requests (e.g. directory listings).
Requests involving scripts, and some others, never attempt a cache search.
<p> The "hit" item, indicates the number of times the hash table
directly provided a cached path. This is very efficient.
<p> The "miss" item, indicates the number of times the hash table
directly indicated a path was not cached. This is decisive and is also very
efficient.
<p> The "collision" item, indicates the number of times multiple paths
resolved to the same hash table entry. Collisions require further processing
and are far less efficient. The sub-items, "collision hits" and
"collision misses" indicate the number of times that further processing
resulted in a found or not-found cache item.
<p> A large number of cache misses compared to searches may only indicate a
large number of non-cacheable requests and so depending on that further datum
is not of great concern. A large proportion of collisions (say greater than
12.5%) is however, indicating either the hash table size needs increasing
(1024 should be considered a minimum) or the hashing algorithm in the software
need reviewing :-)
<li class="item"> <span class="high bold">Files Data</span>
<p> This summarizes the site's file request profile.
<p> With the "loads not hit" item, the count represents the cumulative
number of files loaded but never subsequently hit. If this percentage is high
it means most files loaded are never hit, indicating the site's request
profile is possibly unsuitable for caching.
<p> The item "hits" respresents the cumulative, total number of hits
against the cumulative, total number of loads. The percentage here can range
from zero to many thousands of percent :-) with less than 100% indicating poor
cache performance and from 200% upwards better and good performance. The items
"1-9", "10-99" and "100+" show the count and percentage
of total hits that occured when a given entry had experienced hits within that
range (e.g. if an entry has had 8 previous hits, the ninth increments the
"1-9" item whereas the tenth and eleventh increments the "10-99"
item, etc.)
<p> Other considerations also apply when assessing the benefit of having a
cache. For example, a high number and percentage of hits can be generated
while the percentage of "loads not hit" could be in the also be very
high. The explanation for this would be one or two frequently requested files
being hit while most others are loaded, never hit, and flushed as other files
request cache space. In situations such as this it is difficult to judge
whether cache processing is improving performance or just adding overhead.
</ul>
<a id="9.4" href="#"></a>
<a id="9.4.cachecontentvalidation" href="#"></a>
<a id="cachecontentvalidation" href="#"></a>
<h2 class="head"><span class="numb">9.4</span><span class="text">Cache Content Validation</span></h2>
<p> The cache will automatically revalidate the volatile entry file data after a
specified number of seconds ([CacheValidateSeconds] configuration parameter),
by comparing the original file revision time to the current revision time. If
different the file contents have changed and the cache contents declared
invalid. If found invalid the file transfer then continues outside of the
cache with the new contents being concurrently reloaded into the cache.
Permanent entries are not subject to revalidation and the associated reloading.
<p> Cache validation is also always performed if the request uses
"Cache-Control:" with <span class="high italic">no-cache</span>, <span class="high italic">no-store</span> or <span class="high italic">max-age=0</span> attributes
(HTTP/1.1 directive), or if a "Pragma: no-cache" field (HTTP/1.0 directive).
These request directives are often associated with a browser agent <span class="high italic">reload
page</span> function. Hence there is no need for any explicit flushing of the cache
under normal operation. If a document does not immediately reflect any changes
made to it (i.e. validation time has not been reached) validation (and
consequent reload) can be "forced" with a browser reload. Permanent entries
are also not subject to this source of revalidation. The configuration
directive [CacheGuardPeriod] limits this form of revalidation when used within
the specified period since last revalidated. It has a default value of fifteen
seconds.
<p> If a site's contents are relatively static the validation seconds could be
set to an extended period (say 3600 seconds, one hour) and then rely on an
explicit "reload" to force validation of a changed file.
<p> The entire cache may be purged of cached data, both volatile and permanent
entries, either from the Server Administration facility or using command line
server control.
<div class="blockof code">$ HTTPD /DO=CACHE=PURGE
</div>
<a id="9.5" href="#"></a>
<a id="9.5.cacheconfiguration" href="#"></a>
<a id="cacheconfiguration" href="#"></a>
<h2 class="head"><span class="numb">9.5</span><span class="text">Cache Configuration</span></h2>
<p> The cache is controlled using WASD_CONFIG_GLOBAL configuration file and WASD_CONFIG_MAP
mapping file directives. A number of parameters control the basics of cache
behaviour.
<ul class="list">
<li class="item"> <span class="high bold">[Cache] – </span>
Enables and disables caching.
<li class="item"> <span class="high bold">[CacheEntriesMax]</span>
and <span class="high bold">[CacheTotalKBytesMax] – </span>
Provide growth limits to cache expansion. Maximum entries limits the number of
files loaded into the cache before entries begin to be reused (flushing the
original contents). Maximum total kilobytes allocated to the cache provides a
ceiling on the memory consumed. These parameters operate to limit each other
(i.e. if one reaches its limit before the other, the other will not grow
further either).
<li class="item"> <span class="high bold">[CacheFileKBytesMax] – </span>
Provides a limit on file size (in kilobytes). Files larger than the specified
limit will not be cached. This may be overridden on a per-path basis using the
<span class="high italic">set cache=max=<integer></span> mapping rule (see below).
<li class="item"> <span class="high bold">[CacheFrequentHits]</span> and
<span class="high bold">[CacheFrequentSeconds] – </span>
Attempt to reduce unproductive reuse of cache entries by providing the cache
with some indication of what constitutes a frequently hit entry. If it is
frequently hit then it should not be immediately reused when there is a demand
for cache space. The first parameter sets the number of hits an entry must
sustain before being a candidate for <span class="high italic">CacheFrequentSeconds</span> assessment. If a
file has been hit at least <span class="high italic">CacheFrequentHits</span> times in total and the last hit
was within the number of seconds set by <span class="high italic">CacheFrequentSeconds</span> it will not be
flushed and reused. If it has not been hit within the specified period it will
be reused.
<li class="item"> <span class="high bold">[CacheGuardPeriod] – </span>
Prevents browser initiated content revalidation described above
(<a class="link" href="config009.html#9.4.cachecontentvalidation">9.4 Cache Content Validation</a>). It is provided to help limit unnecessary
file-system activity. The default is fifteen seconds.
<li class="item"> <span class="high bold">[CacheEntriesMax] – </span> <span class="high italic">(obsolete)</span>
<li class="item"> <span class="high bold">[CacheValidateSeconds] – </span>
The interval after which a cache entry's original, content revision time is
revalidated against the file's current revision time. If not the same the
contents are declared invalid and reloaded. Setting this to a greater period
reduces disk I/O but revised files may not be obvious within an acceptable
timer unless a revalidation is forced with a <span class="high italic">reload</span>. Permanent entries are
not subject to validation.
</ul>
<a id="9.5.0.0.1" href="#"></a>
<a id="9.5.mappingrules" href="#"></a>
<a id="mappingrules" href="#"></a>
<h5 class="head"><span class="text">Mapping Rules</span></h5>
<p> Mapping rules (<a class="link" href="config010.html#10.5.5.setrule">10.5.5 SET Rule</a>) allow further tailoring of cache behaviour
based on request (file) path. Those files that should be made permanent
entries are indicated using the <span class="high italic">cache=perm</span> directive. In the following
example all files in the WASD runtime directories (directory icons, help files,
etc.) are made permanent cache entries at the same time the path is mapped.
<div class="blockof code">pass /*/-/* /wasd_root/runtime/*/* cache=perm
</div>
<p> Of course, specified file types as well as specific paths can be mapped in
this way. Here all files in the site's /help/ path are made permanent
entries except those having a .PS type (PostScript documents).
<div class="blockof code">set /help/* cache=perm
set /help/*.ps cache=noperm
</div>
<p> The configuration directive [CacheFileKBytesMax] puts a limit on individual
file size. Those exceeding that limit are considered too large and not cached.
It is possible to override this general constraint by specifying a maximum size
(in kilobytes) on a per-path basis.
<div class="blockof code">set /help/examples*.jpg cache=max=128
set /cai/*.mpg cache=max=2048 cache=perm
</div>
<p> Caching may be disabled and/or enabled for specified paths and subpaths.
<div class="blockof code">set /web/* cache=none
set /web/icons/* cache
</div>
<a id="9.6" href="#"></a>
<a id="9.6.cachecontrol" href="#"></a>
<a id="cachecontrol" href="#"></a>
<h2 class="head"><span class="numb">9.6</span><span class="text">Cache Control</span></h2>
<p> The cache may be enabled, disabled and purged from the Server
Administration facility. In addition the same control may be exercised from the
command-line using
<div class="blockof code">$ HTTPD /DO=CACHE=ON
$ HTTPD /DO=CACHE=OFF
$ HTTPD /DO=CACHE=PURGE
</div>
<p> If cache parameters are altered in the configuration file the server must
be restarted to put these into effect. Disabling the cache on an ad hoc basis
(from menu or command line) does not alter the contents in any way so it can
merely be reenabled with use of the cache's previous contents resuming. In
this way comparisions between the two environments may more easily be made.
<a id="9.7" href="#"></a>
<a id="9.7.circumventingthecache" href="#"></a>
<a id="circumventingthecache" href="#"></a>
<h2 class="head"><span class="numb">9.7</span><span class="text">Circumventing The Cache</span></h2>
<p> There are often good reasons for bypassing or avoiding the cache. For
instance, where a document is being refreshed within the cache revalidation
period specified by [CacheValidateSeconds] (<a class="link" href="config009.html#9.4.cachecontentvalidation">9.4 Cache Content Validation</a>).
There are two mechanisms available for bypassing or invalidating the file
cache.
<ol class="list">
<li class="item"> This directs the server to always get the file from the file-system.
<div class="blockof code">SET /path/not/to/cache/* cache=none
</div>
<li class="item"> Specify a version component when requesting the file. WASD never caches a
file if the request contains a version component. It does not need to be a
full version number, a semi-colon is sufficient. For example:
<div class="blockof code">/wasd_root/robots.txt;
</div>
</ol>
<!-- source:1200_PROCESSING.WASDOC -->
<table class="NAVtable NAVprint"><tr>
<td><a href="javascript:window.history.back();">↩︎</a>
<td><a href="config008.html#8.">↖︎</a>
<td><a href="config000.html#0.">↑︎</a>
<td><a href="config010.html#10.">↘︎</a>
<td><a href="javascript:window.history.forward();">↪︎</a>
</table>