5 <title>JSDoc: Class: BuildCache</title>
7 <script src="scripts/prettify/prettify.js"> </script>
8 <script src="scripts/prettify/lang-css.js"> </script>
10 <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
12 <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
13 <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
20 <h1 class="page-title">Class: BuildCache</h1>
31 <h2><span class="attribs"><span class="type-signature"></span></span>BuildCache<span class="signature">(diag)</span><span class="type-signature"></span></h2>
37 <div class="container-overview">
44 <h4 class="name" id="BuildCache"><span class="type-signature"></span>new BuildCache<span class="signature">(diag)</span><span class="type-signature"></span></h4>
51 <div class="description">
52 Constructs a cache object. The cache object is intended to store objects of
53 arbitrary JavaScript type, which are built from on-disk source files of some
54 kind. The cache tracks the source files of each object, and makes sure the
55 objects are rebuilt as required if the source files change on disk.
69 <table class="params">
82 <th class="last">Description</th>
91 <td class="name"><code>diag</code></td>
97 <span class="param-type">boolean</span>
107 <td class="description last">Should diagnostic messages be printed to the
147 <dt class="tag-source">Source:</dt>
148 <dd class="tag-source"><ul class="dummy"><li>
149 <a href="BuildCache.js.html">BuildCache.js</a>, <a href="BuildCache.js.html#line39">line 39</a>
197 <h3 class="subsection-title">Methods</h3>
205 <h4 class="name" id="build"><span class="type-signature"></span>build<span class="signature">(key, result)</span><span class="type-signature"></span></h4>
212 <div class="description">
213 Abstract method which is expected to build and return an object, given its
214 key. Called from "get()" when the object does not exist or is out of date.
216 If this method throws an exception, the key will be deleted from the cache
217 and the exception re-thrown to the caller of "get()". If there are multiple
218 callers to "get()" blocking and waiting for the build, they all receive the
219 same exception object. So one has to be careful the exception is shareable.
233 <table class="params">
246 <th class="last">Description</th>
255 <td class="name"><code>key</code></td>
261 <span class="param-type">string</span>
271 <td class="description last">Usually the path to the main source file on disk.</td>
278 <td class="name"><code>result</code></td>
284 <span class="param-type">object</span>
294 <td class="description last">A dictionary to receive information about the built
295 object, you can optionally set "result.deps" to a list of dependency files
296 whose modification would invalidate the just-built and cached object.</td>
335 <dt class="tag-source">Source:</dt>
336 <dd class="tag-source"><ul class="dummy"><li>
337 <a href="BuildCache.js.html">BuildCache.js</a>, <a href="BuildCache.js.html#line61">line 61</a>
373 <h4 class="name" id="get"><span class="type-signature"></span>get<span class="signature">(key, once)</span><span class="type-signature"></span></h4>
380 <div class="description">
381 Retrieves the object stored in the cache under "key". If "key" already
382 exists in the cache, then it will be checked for up-to-dateness. If present
383 and up-to-date then its object is returned directly. Otherwise the abstract
384 "build()" method is called to attempt to build the object, and either an
385 exception is thrown or the built object is stored and return to the caller.
387 Other callers requsting the same object while the original build progresses
388 will be blocked, and all will wait for the build to complete. In this time,
389 no new up-to-date check will be initiated. But as soon as the build is
390 completed and the cache updated, further up-to-date checks become possible.
392 An interesting alternate usage is provided for objects whose contents only
393 matter if they have been rebuilt since last time. For example, suppose we
394 want to periodically read a configuration file, and then possibly restart
395 some long-running process if the configuration has changed. Then it is not
396 necessary to store the result of configuration parsing in the cache, since
397 it is only needed momentarily (while we're actually restarting the process).
398 In such case, pass "once = true" and an "undefined" return means no change.
412 <table class="params">
425 <th class="last">Description</th>
434 <td class="name"><code>key</code></td>
440 <span class="param-type">string</span>
450 <td class="description last">Usually the path to the main source file on disk.</td>
457 <td class="name"><code>once</code></td>
463 <span class="param-type">boolean</span>
473 <td class="description last">If "true", it means the returned object will only be
474 used once. See above for a more comprehensive discussion of this feature.</td>
513 <dt class="tag-source">Source:</dt>
514 <dd class="tag-source"><ul class="dummy"><li>
515 <a href="BuildCache.js.html">BuildCache.js</a>, <a href="BuildCache.js.html#line90">line 90</a>
551 <h4 class="name" id="kick"><span class="type-signature"></span>kick<span class="signature">()</span><span class="type-signature"></span></h4>
558 <div class="description">
559 Call this periodically to allow the cache to clean itself of stale objects.
560 It can be called as often as convenient, but since the cache can be large,
561 the frequency of calls to "kick()" should be kept low. For example, if
562 unreferenced objects should be kept for one day, then call "kick()" once
563 per hour, and the actual lifetime will be at least 24 and up to 25 hours.
565 The cache cleaning is not yet implemented, but the dummy "kick()" function
566 is provided so that you can start to put the cleaning infrastructure in your
567 code already. The constructor arguments might change later for this feature.
609 <dt class="tag-source">Source:</dt>
610 <dd class="tag-source"><ul class="dummy"><li>
611 <a href="BuildCache.js.html">BuildCache.js</a>, <a href="BuildCache.js.html#line165">line 165</a>
657 <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="BuildCache.html">BuildCache</a></li></ul>
663 Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.3</a> on Wed Feb 05 2020 00:11:43 GMT+1100 (Australian Eastern Daylight Time)
666 <script> prettyPrint(); </script>
667 <script src="scripts/linenumber.js"> </script>