Functions to create and work with a cache — createCache • reproducible

These are not intended for normal use.

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

loadFromCache(
  cachePath = getOption("reproducible.cachePath"),
  cacheId,
  fullCacheTableForObj = NULL,
  format = getOption("reproducible.cacheSaveFormat", "rds"),
  .functionName = NULL,
  .dotsFromCache = NULL,
  drv = getDrv(getOption("reproducible.drv", NULL)),
  conn = getOption("reproducible.conn", NULL),
  verbose = getOption("reproducible.verbose")
)

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

CacheDBFile(
  cachePath = getOption("reproducible.cachePath"),
  drv = getDrv(getOption("reproducible.drv", NULL)),
  conn = getOption("reproducible.conn", NULL)
)

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

CacheStoredFile(
  cachePath = getOption("reproducible.cachePath"),
  cacheId,
  format = NULL,
  obj = NULL
)

CacheDBTableName(
  cachePath = getOption("reproducible.cachePath"),
  drv = getDrv(getOption("reproducible.drv", NULL))
)

CacheIsACache(
  cachePath = getOption("reproducible.cachePath"),
  create = FALSE,
  drv = getDrv(getOption("reproducible.drv", NULL)),
  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: an optional 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.
fullCacheTableForObj: The result of showCache, but subsetted for only the cacheId being loaded or selected
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")
.functionName: Optional. Used for messaging when this function is called from Cache
.dotsFromCache: Optional. Used internally.
obj: The optional object that is of interest; it may have an attribute "saveRawFile" that would be important.
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, when useDBI() == FALSE, or NULL if TRUE. CacheDBFiles (i.e,. plural) returns the name of all the database files for a given Cache when useDBI() == TRUE, or NULL if FALSE

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.

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

Examples

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

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

rmFromCache(newCache, cacheId = cacheId)

# clean up
unlink(newCache, recursive = TRUE)

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

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

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

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

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

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

# clean up
unlink(newCache, recursive = TRUE)