cache: Evaluate an expression and cache its results

Description

This function extracts all dependencies of an R expression, hashes them together with the expression itself and either loads the already-existing file, or evaluates the expression and stores the result in that file.

Usage

cache(expr, extra = NULL, …)

Arguments

expr

An expression to evaluate or load from cache, unquoted.

extra

Any R value that should be considered part of the state deciding whether the expression should be re-computed. For example, if expr reads a file, consider using file.mtime or md5sum to check for changes in it.

…

Additional options, see depcache.options.

Value

The result of evaluating expr, either directly, or loaded from cache.

Details

Currently, the hash is obtained by means of serialisation. In order to make semantically same values have same hashes on a wide range of R versions, the following steps were taken:

When computing the hash of the serialized data (only the XDR format version 2 or 3 is supported), the first 14 bytes containing the header (including the version of R that serialized the data) are ignored.
Every function is “rebuilt” from its body before hashing, forcing R to discard the bytecode and the source references from the copy of the function before it's hashed.
Strings are converted to UTF-8 before hashing.
All this is done recursively.

The exact algorithm used and the way hash is obtained are implementation details and may eventually change, though not without a good reason.

Other aspects of R data structures are currently not handled:

Nothing is done about environments. Due to them being reference objects, any fix-up must re-create them from scratch, taking potentially recursive dependencies into account, which is likely expensive.
Some S4 classes (like reference class implementations) just have different representations in different versions of R and third-party packages. They may mean the same thing, but they serialize to different byte sequences.

Examples

Run this code

# NOT RUN {
  
# }
# NOT RUN {
  a <- 1
  # will evaluate the expression the first time
  cache({ message('evaluating expression'); a + 1 }) # 2
  # saved value of the expression will be used
  cache({
    message('evaluating expression')
    # even if written a bit differently
    a + 1
  }) # 2
  a <- -1
  # expression evaluated again because dependencies changed
  cache({ message('evaluating expression'); a + 1 }) # 0
  
# }