evalWithCache: evalWithCache

In gmbecker/RCacheSuite: State and Dependency Aware Caching

Description

This function accepts a piece of R code and performs state (input variable value) dependent cached evaluation of it.

Usage

evalWithCache(code, env = parent.frame(),
  cache = cachingEngine(write_on_cache = TRUE), codeInfo = NULL,
  inputVars = NULL, outputVars = NULL, eval_fun = cache$eval_fun,
  return_handler = cache$return_handler, force = FALSE, cacheRand = FALSE,
  verbose = FALSE, gexts = "png", gdev = sapply(gexts, function(nm)
  get(nm, mode = "function")), last = TRUE, stopMissingInput = FALSE,
  singleEntFun = sameOutVar, unCacheable = mustForce, ...)

Arguments

code	The code to evaluate
env	The environment in which to evaluate the code or load the cached outputs
cache	The CachingEngine to use when evaluating the code. Defaults to an engine which writes caches out immediately, mimicing caching behavior of other systems. See note.
codeInfo	A ScriptNodeInfo object, defaults to the result of calling getInputs on the code with default handling options
inputVars	A vector of variable names which are inputs to the code block. Overrides automatically detected inputs
outputVars	A vector of variable name which are outputs generated by the code block. Overrides automatically detected outputs
eval_fun	A function to perform evaluation of the code. Defaults to the code evaluator associated with cache
return_handler	A function to be called on the value returned by evaluating the code (or loading from cache). Defaults to return handler associated with cache
force	A logical indicating whether to force a cache refresh. If TRUE, cached values will NOT be used, but a new cache will be written after evaluating code. Defaults to FALSE
cacheRand	A logical indicating whether to create/use caches for expressions with a detected random component. Defaults to FALSE
verbose	Should extra informative messages be emitted. Defaults to FALSE
gexts	A vector of graphics file extensions for caching graphics
gdev	A vector of graphics devices to use to generate the files indicated by gexts for caching graphics. Defaults to functions named directly for their extensions (e.g., png).
last	logical. Is this the last expression in the codeblock being evaluated. Passed to return handler. Generally this should not be manually set.
stopMissingInput	Should an error be thrown when an input variable is not present in the evaluation scope. If FALSE a warning will be emitted. Defaults to FALSE
singleEntFun	A function, or NULL. If a function, it is called on codeInfo to determine if code should be treated as a single entity for caching purposes. If NULL, or a function that returns FALSE, expressions in code are evaluated and cached separately. Defautls to sameOutVar
unCacheable	A function which accepts a ScriptNodeInfo object and returns a logical value indicating whether the computation is cacheable. Defaults to mustForce
...	Passed to eval_fun if code is evaluated.

Details

This function performs state-aware cached evaluation of R code. This means that a cache is considered to apply if and only if both the code (after parsing) and the values of any variables used as inputs to the code are identical to those present when the cache was created.

Cached evaluation is done via a caching engine (CachingEngine object), which has a set of caches it already knows about, the ability to create new caches, and a set of behaviors for when - if ever - a cache should be written to disk, an evaluator function which evaluates the code, and a return handler which processes the object returned from the evaluator or loaded from a matching cache.

The evaluator function is charged with evaluating code and capturing any side-effects of the code that the user wishes to cache and recreate, encoding them in the object it returns. The return handler is tasked with processing that return value, recreating any side effects (including plots, messages printed to the console, etc) and then returning the raw result of the evaluation.

Value

The value generated by cache$return_handler when called on the value returned by evaluating code using cache$eval_fun.

In other words, the value

   cache$return_handler(cache$eval_fun(code, env, ...))
 

is returned, though if a valid cache is found, cache$eval_fun is not called and the cached return value (of the evaluator function at the time of caching) is passed to cache$return_handler.

The return value of cache$return_handler is returned invisibly. The cache$return_handler function itself is responsible for the duplication of any side effects, including any printing of errors, warnings, or messages as well as any necessary regeneration of graphical output.

Author(s)

Gabriel Becker

See Also

cachingEngine, getInputs

Examples

## Not run: 
   res = evalWithCache("x = 5; y = x+7;y")

## End(Not run)

gmbecker/RCacheSuite documentation built on May 17, 2019, 6:42 a.m.