Low-level functions to create and work with a cache

These are intended for advanced use only.

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,
  preDigest,
  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")
)

extractFromCache(sc, elem, ifNot = NULL)

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.
preDigest: The list of preDigest that comes from CacheDigest of an object
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.
sc: a cache tags data.table object
elem: character string specifying a tagKey value to match
ifNot: character (or NULL) specifying the return value to use if elem not matched
obj: The optional object that is of interest; it may have an attribute "saveRawFile" that would be important.
create: Logical. Currently only affects non RSQLite default drivers. If TRUE and there is no Cache database, the function will create one.

Value

createCache() returns NULL (invisibly) and intended to be called for side effects;

loadFromCache() returns the object from the cache that has the particular cacheId;

extractFromCache() returns the tagValue from the cache corresponding to elem if found, otherwise the value of ifNot;

rmFromCache() returns NULL (invisibly) and is intended to be called for 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;
CacheStoredFile() returns the file path to the file with the specified hash value, This can be loaded to memory with e.g., loadFile().;

CacheStorageDir() returns the name of the directory where cached objects are stored;

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

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() will create a Cache folder structure and necessary files, based on the particular drv or conn provided;

loadFromCache() retrieves a single object from the cache, given its cacheId;

extractFromCache() retrieves a single tagValue from the cache based on the tagKey of elem;

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

Examples

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

out <- Cache(rnorm(1), cachePath = newCache)
#> Saved! Cache file: 422bae4ed2f770cc.rds; fn: rnorm
cacheId <- gsub("cacheId:", "", attr(out, "tags"))
loadFromCache(newCache, cacheId = cacheId)
#> Loaded! Cached result from previous  call
#> [1] 1.591054
#> 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/RtmpxA3jdR/reproducible/ae0QJHoD/cache.db"
CacheStorageDir(newCache) # identifies the directory where cached objects are stored
#> [1] "/tmp/RtmpxA3jdR/reproducible/ae0QJHoD/cacheOutputs"

out <- Cache(rnorm(1), cachePath = newCache)
#> Saved! Cache file: 422bae4ed2f770cc.rds; fn: rnorm
cacheId <- gsub("cacheId:", "", attr(out, "tags"))
CacheStoredFile(newCache, cacheId = cacheId)
#> [1] "/tmp/RtmpxA3jdR/reproducible/ae0QJHoD/cacheOutputs/422bae4ed2f770cc.rds"

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

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

# clean up
unlink(newCache, recursive = TRUE)