Class: BuildCache

BuildCache(diag)

new BuildCache(diag)

Constructs a cache object. The cache object is intended to store objects of arbitrary JavaScript type, which are built from on-disk source files of some kind. The cache tracks the source files of each object, and makes sure the objects are rebuilt as required if the source files change on disk.
Parameters:
NameTypeDescription
diagbooleanShould diagnostic messages be printed to the console.
Source:

Methods

build(key, result)

Abstract method which is expected to build and return an object, given its key. Called from "get()" when the object does not exist or is out of date. If this method throws an exception, the key will be deleted from the cache and the exception re-thrown to the caller of "get()". If there are multiple callers to "get()" blocking and waiting for the build, they all receive the same exception object. So one has to be careful the exception is shareable.
Parameters:
NameTypeDescription
keystringUsually the path to the main source file on disk.
resultobjectA dictionary to receive information about the built object, you can optionally set "result.deps" to a list of dependency files whose modification would invalidate the just-built and cached object.
Source:

get(key, once)

Retrieves the object stored in the cache under "key". If "key" already exists in the cache, then it will be checked for up-to-dateness. If present and up-to-date then its object is returned directly. Otherwise the abstract "build()" method is called to attempt to build the object, and either an exception is thrown or the built object is stored and return to the caller. Other callers requsting the same object while the original build progresses will be blocked, and all will wait for the build to complete. In this time, no new up-to-date check will be initiated. But as soon as the build is completed and the cache updated, further up-to-date checks become possible. An interesting alternate usage is provided for objects whose contents only matter if they have been rebuilt since last time. For example, suppose we want to periodically read a configuration file, and then possibly restart some long-running process if the configuration has changed. Then it is not necessary to store the result of configuration parsing in the cache, since it is only needed momentarily (while we're actually restarting the process). In such case, pass "once = true" and an "undefined" return means no change.
Parameters:
NameTypeDescription
keystringUsually the path to the main source file on disk.
oncebooleanIf "true", it means the returned object will only be used once. See above for a more comprehensive discussion of this feature.
Source:

kick()

Call this periodically to allow the cache to clean itself of stale objects. It can be called as often as convenient, but since the cache can be large, the frequency of calls to "kick()" should be kept low. For example, if unreferenced objects should be kept for one day, then call "kick()" once per hour, and the actual lifetime will be at least 24 and up to 25 hours. The cache cleaning is not yet implemented, but the dummy "kick()" function is provided so that you can start to put the cleaning infrastructure in your code already. The constructor arguments might change later for this feature.
Source:

Documentation generated by JSDoc 3.6.3 on Wed Feb 05 2020 00:11:43 GMT+1100 (Australian Eastern Daylight Time)