Functions to create and work with a cache

These are not intended for normal use.

createCache(
  cachePath = getOption("reproducible.cachePath"),
  drv = getOption("reproducible.drv", RSQLite::SQLite()),
  conn = getOption("reproducible.conn", NULL),
  force = FALSE,
  verbose = getOption("reproducible.verbose")
)

loadFromCache(
  cachePath = getOption("reproducible.cachePath"),
  cacheId,
  format = getOption("reproducible.cacheSaveFormat", "rds"),
  drv = getOption("reproducible.drv", RSQLite::SQLite()),
  conn = getOption("reproducible.conn", NULL)
)

rmFromCache(
  cachePath = getOption("reproducible.cachePath"),
  cacheId,
  drv = getOption("reproducible.drv", RSQLite::SQLite()),
  conn = getOption("reproducible.conn", NULL),
  format = getOption("reproducible.cacheSaveFormat", "rds")
)

CacheDBFile(
  cachePath = getOption("reproducible.cachePath"),
  drv = getOption("reproducible.drv", RSQLite::SQLite()),
  conn = getOption("reproducible.conn", NULL)
)

CacheStorageDir(cachePath = getOption("reproducible.cachePath"))

CacheStoredFile(
  cachePath = getOption("reproducible.cachePath"),
  cacheId,
  format = getOption("reproducible.cacheSaveFormat", "rds")
)

CacheDBTableName(
  cachePath = getOption("reproducible.cachePath"),
  drv = getOption("reproducible.drv", RSQLite::SQLite())
)

CacheIsACache(
  cachePath = getOption("reproducible.cachePath"),
  create = FALSE,
  drv = getOption("reproducible.drv", RSQLite::SQLite()),
  conn = getOption("reproducible.conn", NULL)
)

Arguments

cachePath

A path describing the directory in which to create the database file(s)

drv

A driver, passed to dbConnect

conn

A DBIConnection object, as returned by dbConnect().

force

Logical. Should it create a cache in the cachePath, even if it already exists, overwriting.

verbose

Numeric, -1 silent (where possible), 0 being very quiet, 1 showing more messaging, 2 being more messaging, etc. Default is 1. Above 3 will output much more information about the internals of Caching, which may help diagnose Caching challenges. Can set globally with an option, e.g., options('reproducible.verbose' = 0) to reduce to minimal

cacheId

The cacheId or otherwise digested hash value, as character string.

format

The text string representing the file extension used normally by different save formats; currently only "rds" or "qs". Defaults to getOption("reproducible.cacheSaveFormat", "rds")

create

Logical. Currently only affects non RQSLite default drivers. If this is TRUE and there is no Cache database, the function will create one.

Value

createCache does not return a value; it is called for side effects.

loadFromCache returns the object from the cache that has the particular cacheId.

rmFromCache has no return value; it is called for its side effects.

CacheDBFile returns the name of the database file for a given Cache.

CacheStorageDir returns the name of the directory where cached objects are stored.

CacheStoredFile returns the name of the file in which the cacheId object is stored. This can be loaded to memory with e.g., loadFile.

CacheDBTableName returns the name of the table inside the SQL database, if that is being used.

CacheIsACache returns a logical indicating whether the cachePath is currently a reproducible cache database.

Details

createCache function will create a Cache folder structure and necessary files, based on the particular drv or conn provided.

loadFromCache is a function to get a single object from the cache, given its cacheId.

rmFromCache removes one or more items from the cache, and updates the cache database files.

CacheStoredFile returns the file path to the file with the specified hash value.

CacheStoredFile returns the file path to the file with the specified hash value.

CacheIsACache returns a logical of whether the specified cachePath is actually a functioning cache.

Examples

data.table::setDTthreads(2)
newCache <- tempdir2("cacheHelperExamples")
createCache(newCache)

out <- Cache(rnorm(1), cachePath = newCache)
cacheId <- gsub("cacheId:", "", attr(out, "tags"))
loadFromCache(newCache, cacheId = cacheId)
#> [1] -1.269758
#> attr(,".Cache")
#> attr(,".Cache")$newCache
#> [1] TRUE
#> 
#> attr(,"tags")
#> [1] "cacheId:422bae4ed2f770cc"
#> attr(,"call")
#> [1] ""

rmFromCache(newCache, cacheId = cacheId)

# clean up
unlink(dirname(newCache), recursive = TRUE)

data.table::setDTthreads(2)
newCache <- tempdir2("cacheHelperExamples")

# Given the drv and conn, creates the minimum infrastructure for a cache
createCache(newCache)

CacheDBFile(newCache) # identifies the database file
#> [1] "/tmp/Rtmp56YhgE/reproducible/cacheHelperExamples/cache.db"
CacheStorageDir(newCache) # identifies the directory where cached objects are stored
#> [1] "/tmp/Rtmp56YhgE/reproducible/cacheHelperExamples/cacheOutputs"

out <- Cache(rnorm(1), cachePath = newCache)
cacheId <- gsub("cacheId:", "", attr(out, "tags"))
CacheStoredFile(newCache, cacheId = cacheId)
#> [1] "/tmp/Rtmp56YhgE/reproducible/cacheHelperExamples/cacheOutputs/422bae4ed2f770cc.rds"

# The name of the table inside the SQL database
CacheDBTableName(newCache)
#> [1] "reproducible_cacheHelperExamples"

CacheIsACache(newCache) # returns TRUE
#> [1] TRUE

# clean up
unlink(dirname(newCache), recursive = TRUE)