createCache {reproducible}

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)