You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
pollen/doc/Cache.html

2 lines
19 KiB
HTML

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"/><title>10.1&nbsp;Cache</title><link rel="stylesheet" type="text/css" href="scribble.css" title="default"/><link rel="stylesheet" type="text/css" href="racket.css" title="default"/><link rel="stylesheet" type="text/css" href="manual-style.css" title="default"/><link rel="stylesheet" type="text/css" href="manual-racket.css" title="default"/><script type="text/javascript" src="scribble-common.js"></script><script type="text/javascript" src="manual-racket.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><body id="scribble-racket-lang-org"><div class="tocset"><div class="tocview"><div class="tocviewlist tocviewlisttopspace"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,&quot;tocview_0&quot;);">&#9658;</a></td><td></td><td><a href="index.html" class="tocviewlink" data-pltdoc="x">Pollen:<span class="mywbr"> &nbsp;</span> the book is a program</a></td></tr></table></div><div class="tocviewsublisttop" style="display: none;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1&nbsp;</td><td><a href="Installation.html" class="tocviewlink" data-pltdoc="x">Installation</a></td></tr><tr><td align="right">2&nbsp;</td><td><a href="quick-tour.html" class="tocviewlink" data-pltdoc="x">Quick tour</a></td></tr><tr><td align="right">3&nbsp;</td><td><a href="Backstory.html" class="tocviewlink" data-pltdoc="x">Backstory</a></td></tr><tr><td align="right">4&nbsp;</td><td><a href="big-picture.html" class="tocviewlink" data-pltdoc="x">The big picture</a></td></tr><tr><td align="right">5&nbsp;</td><td><a href="first-tutorial.html" class="tocviewlink" data-pltdoc="x">First tutorial</a></td></tr><tr><td align="right">6&nbsp;</td><td><a href="second-tutorial.html" class="tocviewlink" data-pltdoc="x">Second tutorial</a></td></tr><tr><td align="right">7&nbsp;</td><td><a href="raco-pollen.html" class="tocviewlink" data-pltdoc="x">Using <span class="stt">raco pollen</span></a></td></tr><tr><td align="right">8&nbsp;</td><td><a href="File_formats.html" class="tocviewlink" data-pltdoc="x">File formats</a></td></tr><tr><td align="right">9&nbsp;</td><td><a href="reader.html" class="tocviewlink" data-pltdoc="x">&#9674; command overview</a></td></tr><tr><td align="right">10&nbsp;</td><td><a href="Module_reference.html" class="tocviewselflink" data-pltdoc="x">Module reference</a></td></tr><tr><td align="right">11&nbsp;</td><td><a href="Acknowledgments.html" class="tocviewlink" data-pltdoc="x">Acknowledgments</a></td></tr><tr><td align="right">12&nbsp;</td><td><a href="License___source_code.html" class="tocviewlink" data-pltdoc="x">License &amp; source code</a></td></tr><tr><td align="right"></td><td><a href="doc-index.html" class="tocviewlink" data-pltdoc="x">Index</a></td></tr></table></div></div><div class="tocviewlist"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,&quot;tocview_1&quot;);">&#9660;</a></td><td>10&nbsp;</td><td><a href="Module_reference.html" class="tocviewlink" data-pltdoc="x">Module reference</a></td></tr></table><div class="tocviewsublistbottom" style="display: block;" id="tocview_1"><table cellspacing="0" cellpadding="0"><tr><td align="right">10.1&nbsp;</td><td><a href="Cache.html" class="tocviewselflink" data-pltdoc="x">Cache</a></td></tr><tr><td align="right">10.2&nbsp;</td><td><a href="Decode.html" class="tocviewlink" data-pltdoc="x">Decode</a></td></tr><tr><td align="right">10.3&nbsp;</td><td><a href="file-types.html" class="tocviewlink" data-pltdoc="x">File</a></td></tr><tr><td align="right">10.4&nbsp;</td><td><a href="Pagetree.html" class="tocviewlink" data-pltdoc="x">Pagetree</a></td></tr><tr><td align="right">10.5&nbsp;</td><td><a href="Render.html" class="tocviewlink" data-pltdoc="x">Render</a></td></tr><tr><td align="right">10.6&nbsp;</td><td><a href="Template.html" class="tocviewlink" data-pltdoc="x">Template</a></td></tr><tr><td align="right">10.7&nbsp;</td><td><a href="Tag.html" class="tocviewlink" data-pltdoc="x">Tag</a></td></tr><tr><td align="right">10.8&nbsp;</td><td><a href="Top.html" class="tocviewlink" data-pltdoc="x">Top</a></td></tr><tr><td align="right">10.9&nbsp;</td><td><a href="World.html" class="tocviewlink" data-pltdoc="x">World</a></td></tr></table></div></div></div><div class="tocsub"><div class="tocsubtitle">On this page:</div><table class="tocsublist" cellspacing="0"><tr><td><a href="#%28def._%28%28lib._pollen%2Fcache..rkt%29._current-cache%29%29" class="tocsublink" data-pltdoc="x"><span class="RktSym">current-<wbr></wbr>cache</span></a></td></tr><tr><td><a href="#%28def._%28%28lib._pollen%2Fcache..rkt%29._cached-require%29%29" class="tocsublink" data-pltdoc="x"><span class="RktSym">cached-<wbr></wbr>require</span></a></td></tr><tr><td><a href="#%28def._%28%28lib._pollen%2Fcache..rkt%29._make-cache%29%29" class="tocsublink" data-pltdoc="x"><span class="RktSym">make-<wbr></wbr>cache</span></a></td></tr><tr><td><a href="#%28def._%28%28lib._pollen%2Fcache..rkt%29._reset-cache%29%29" class="tocsublink" data-pltdoc="x"><span class="RktSym">reset-<wbr></wbr>cache</span></a></td></tr><tr><td><a href="#%28def._%28%28lib._pollen%2Fcache..rkt%29._cache-ref%29%29" class="tocsublink" data-pltdoc="x"><span class="RktSym">cache-<wbr></wbr>ref</span></a></td></tr></table></div></div><div class="maincolumn"><div class="main"><div class="versionbox"><span class="version">6.0.1.13</span></div><div class="navsettop"><span class="navleft"><div class="nosearchform"></div>&nbsp;&nbsp;</span><span class="navright">&nbsp;&nbsp;<a href="Module_reference.html" title="backward to &quot;10 Module reference&quot;" data-pltdoc="x">&larr; prev</a>&nbsp;&nbsp;<a href="Module_reference.html" title="up to &quot;10 Module reference&quot;" data-pltdoc="x">up</a>&nbsp;&nbsp;<a href="Decode.html" title="forward to &quot;10.2 Decode&quot;" data-pltdoc="x">next &rarr;</a></span>&nbsp;</div><h4>10.1<tt>&nbsp;</tt><a name="(part._.Cache)"></a><a name="(mod-path._pollen/cache)"></a>Cache</h4><p><table cellspacing="0" cellpadding="0" class="defmodule"><tr><td align="left"><span class="hspace">&nbsp;</span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29" class="RktStxLink" data-pltdoc="x">require</a></span><span class="stt"> </span><a href="Cache.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen/cache</span></a><span class="RktPn">)</span></td><td align="right"><span class="RpackageSpec"><span class="Smaller">&nbsp;package:</span> <span class="stt">pollen</span></span></td></tr></table></p><p>The slowest part of a <span class="RktSym"><a href="Render.html#%28def._%28%28lib._pollen%2Frender..rkt%29._render%29%29" class="RktValLink" data-pltdoc="x">render</a></span> is parsing and decoding the source file. Often, previewing a single source file necessarily means decoding others (for instance templates, or other source files that are linked into the main source file). But usually, only one source file is changing at a time. Therefore, Pollen stores copies of the exports of source files &#8212;&#160;namely, whatever is stored in <span class="RktSym">doc</span><span class="RktMeta"></span> and <span class="RktSym">metas</span><span class="RktMeta"></span> &#8212;&#160;in the cache so they can be reused.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>parameter</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._pollen/cache..rkt)._current-cache))"></a><span title="Provided from: pollen/cache | Package: pollen"><span class="RktSym"><span class="RktSymDef RktSym">current-cache</span></span></span><span class="RktPn"></span><span class="RktPn">)</span><span class="hspace">&nbsp;</span>&rarr;<span class="hspace">&nbsp;</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/hashtables.html#%28def._%28%28quote._~23~25kernel%29._hash~3f%29%29" class="RktValLink" data-pltdoc="x">hash?</a></span></p></blockquote></td></tr><tr><td><span class="RktPn">(</span><span title="Provided from: pollen/cache | Package: pollen"><span class="RktSym"><span class="RktSymDef RktSym">current-cache</span></span></span><span class="hspace">&nbsp;</span><span class="RktVar">hash</span><span class="RktPn">)</span><span class="hspace">&nbsp;</span>&rarr;<span class="hspace">&nbsp;</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></td></tr><tr><td><span class="hspace">&nbsp;&nbsp;</span><span class="RktVar">hash</span><span class="hspace">&nbsp;</span>:<span class="hspace">&nbsp;</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/hashtables.html#%28def._%28%28quote._~23~25kernel%29._hash~3f%29%29" class="RktValLink" data-pltdoc="x">hash?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">A parameter that refers to the current cache. It is initialized with <span class="RktSym">make-cache</span>.</div></p><p>The cache is a hash table that uses the complete path of a source file as its keys. The value associated with each of these keys is a subcache &#8212;&#160;another hash table with keys <span class="RktVal">'</span><span class="RktVal">doc</span>, <span class="RktVal">'</span><span class="RktVal">metas</span> (for storing the exports of the source file) and <span class="RktVal">'</span><span class="RktVal">mod-time</span> (for storing the modification time, provided by <span class="RktSym"><a href="http://docs.racket-lang.org/reference/Filesystem.html#%28def._%28%28quote._~23~25kernel%29._file-or-directory-modify-seconds%29%29" class="RktValLink" data-pltdoc="x">file-or-directory-modify-seconds</a></span>).</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._pollen/cache..rkt)._cached-require))"></a><span title="Provided from: pollen/cache | Package: pollen"><span class="RktSym"><span class="RktSymDef RktSym">cached-require</span></span></span><span class="hspace">&nbsp;</span><span class="RktVar">source-path</span><span class="hspace">&nbsp;</span><span class="RktVar">key</span><span class="RktPn">)</span><span class="hspace">&nbsp;</span>&rarr;<span class="hspace">&nbsp;</span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace">&nbsp;</span><span class="RktSym"><a href="http://docs.racket-lang.org/txexpr/index.html#%28def._%28%28lib._txexpr%2Fmain..rkt%29._txexpr~3f%29%29" class="RktValLink" data-pltdoc="x">txexpr?</a></span><span class="hspace">&nbsp;</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/hashtables.html#%28def._%28%28quote._~23~25kernel%29._hash~3f%29%29" class="RktValLink" data-pltdoc="x">hash?</a></span><span class="hspace">&nbsp;</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/number-types.html#%28def._%28%28quote._~23~25kernel%29._integer~3f%29%29" class="RktValLink" data-pltdoc="x">integer?</a></span><span class="RktPn">)</span></p></blockquote></td></tr><tr><td><span class="hspace">&nbsp;&nbsp;</span><span class="RktVar">source-path</span><span class="hspace">&nbsp;</span>:<span class="hspace">&nbsp;</span><span class="RktSym"><a href="http://docs.racket-lang.org/sugar/Coercion.html#%28def._%28%28lib._sugar%2Fcoerce%2Fvalue..rkt%29._pathish~3f%29%29" class="RktValLink" data-pltdoc="x">pathish?</a></span></td></tr><tr><td><span class="hspace">&nbsp;&nbsp;</span><span class="RktVar">key</span><span class="hspace">&nbsp;</span>:<span class="hspace">&nbsp;</span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace">&nbsp;</span><span class="RktVal">'</span><span class="RktVal">doc</span><span class="hspace">&nbsp;</span><span class="RktVal">'</span><span class="RktVal">metas</span><span class="hspace">&nbsp;</span><span class="RktVal">'</span><span class="RktVal">mod-time</span><span class="RktPn">)</span></td></tr></table></blockquote></div><div class="SIntrapara">Similar to <span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/Module_Names_and_Loading.html#%28def._%28%28quote._~23~25kernel%29._dynamic-require%29%29" class="RktValLink" data-pltdoc="x">dynamic-require</a></span><span class="stt"> </span><span class="RktVar">source-path</span><span class="stt"> </span><span class="RktVar">key</span><span class="RktPn">)</span>, except that it first tries to retrieve the requested value out of <span class="RktSym">current-cache</span>. If it&rsquo;s not there, or out of date, <span class="RktSym"><a href="http://docs.racket-lang.org/reference/Module_Names_and_Loading.html#%28def._%28%28quote._~23~25kernel%29._dynamic-require%29%29" class="RktValLink" data-pltdoc="x">dynamic-require</a></span> is used to update the value.</div></p><p>The only keys&#160;supported are <span class="RktVal">'</span><span class="RktVal">doc</span>, <span class="RktVal">'</span><span class="RktVal">metas</span>, and <span class="RktVal">'</span><span class="RktVal">mod-time</span>.</p><p>If you want the speed benefit of the cache, you should <span style="font-weight: bold">always</span> use <span class="RktSym">cached-require</span> to get data from Pollen source files. That doesn&rsquo;t mean you can&rsquo;t still use functions like <span class="RktSym"><a href="http://docs.racket-lang.org/reference/require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29" class="RktStxLink" data-pltdoc="x">require</a></span>, <span class="RktSym"><a href="http://docs.racket-lang.org/reference/require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._local-require%29%29" class="RktStxLink" data-pltdoc="x">local-require</a></span>, and <span class="RktSym"><a href="http://docs.racket-lang.org/reference/Module_Names_and_Loading.html#%28def._%28%28quote._~23~25kernel%29._dynamic-require%29%29" class="RktValLink" data-pltdoc="x">dynamic-require</a></span>. They&rsquo;ll just be slower.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._pollen/cache..rkt)._make-cache))"></a><span title="Provided from: pollen/cache | Package: pollen"><span class="RktSym"><span class="RktSymDef RktSym">make-cache</span></span></span><span class="RktPn"></span><span class="RktPn">)</span><span class="hspace">&nbsp;</span>&rarr;<span class="hspace">&nbsp;</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/hashtables.html#%28def._%28%28quote._~23~25kernel%29._hash~3f%29%29" class="RktValLink" data-pltdoc="x">hash?</a></span></p></blockquote></td></tr></table></blockquote></div><div class="SIntrapara">Initializes <span class="RktSym">current-cache</span>.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._pollen/cache..rkt)._reset-cache))"></a><span title="Provided from: pollen/cache | Package: pollen"><span class="RktSym"><span class="RktSymDef RktSym">reset-cache</span></span></span><span class="RktPn"></span><span class="RktPn">)</span><span class="hspace">&nbsp;</span>&rarr;<span class="hspace">&nbsp;</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></p></blockquote></td></tr></table></blockquote></div><div class="SIntrapara">Clears <span class="RktSym">current-cache</span>. When only the nuclear option will do.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._pollen/cache..rkt)._cache-ref))"></a><span title="Provided from: pollen/cache | Package: pollen"><span class="RktSym"><span class="RktSymDef RktSym">cache-ref</span></span></span><span class="hspace">&nbsp;</span><span class="RktVar">source-path</span><span class="RktPn">)</span><span class="hspace">&nbsp;</span>&rarr;<span class="hspace">&nbsp;</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/hashtables.html#%28def._%28%28quote._~23~25kernel%29._hash~3f%29%29" class="RktValLink" data-pltdoc="x">hash?</a></span></p></blockquote></td></tr><tr><td><span class="hspace">&nbsp;&nbsp;</span><span class="RktVar">source-path</span><span class="hspace">&nbsp;</span>:<span class="hspace">&nbsp;</span><span class="RktSym"><a href="http://docs.racket-lang.org/sugar/Coercion.html#%28def._%28%28lib._sugar%2Fcoerce%2Fvalue..rkt%29._pathish~3f%29%29" class="RktValLink" data-pltdoc="x">pathish?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Returns the subcache associated with the key <span class="RktVar">source-path</span>, which will itself be a hash table. See <span class="RktSym">current-cache</span>.</div></p><div class="navsetbottom"><span class="navleft"><div class="nosearchform"></div>&nbsp;&nbsp;</span><span class="navright">&nbsp;&nbsp;<a href="Module_reference.html" title="backward to &quot;10 Module reference&quot;" data-pltdoc="x">&larr; prev</a>&nbsp;&nbsp;<a href="Module_reference.html" title="up to &quot;10 Module reference&quot;" data-pltdoc="x">up</a>&nbsp;&nbsp;<a href="Decode.html" title="forward to &quot;10.2 Decode&quot;" data-pltdoc="x">next &rarr;</a></span>&nbsp;</div></div></div><div id="contextindicator">&nbsp;</div></body></html>