CacheHelpers: Low-level functions to create and work with a cache

In PredictiveEcology/reproducible: Enhance Reproducibility of R Code

Low-level functions to create and work with a cache

Description

These are intended for advanced use only.

Usage

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.

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.

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;

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)

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
CacheStorageDir(newCache) # identifies the directory where cached objects are stored

out <- Cache(rnorm(1), cachePath = newCache)
cacheId <- gsub("cacheId:", "", attr(out, "tags"))
CacheStoredFile(newCache, cacheId = cacheId)

# The name of the table inside the SQL database
CacheDBTableName(newCache)

CacheIsACache(newCache) # returns TRUE

# clean up
unlink(newCache, recursive = TRUE)

PredictiveEcology/reproducible documentation built on Dec. 12, 2024, 7:26 p.m.